Metadata-Version: 2.2
Name: dc_texter
Version: 0.1.2
Summary: A simple SMS text alert utility for Python projects
Author-email: Denise Case <denisecase@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Denise Case
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/denisecase/dc_texter
Project-URL: Repository, https://github.com/denisecase/dc_texter
Project-URL: BugTracker, https://github.com/denisecase/dc_texter/issues
Keywords: sms,text,alert,notification
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"

# dc-texter

> Send an SMS text alert using Python and Gmail

## Requirements

- Python 3.11+ (required for reading toml files)
- A configured Gmail Account (see below)
---

## Step 1. Install this Module

Use `pip install dc-texter`
or add `dc-texter` to your requirements.txt and install. 

## Step 2. Add .env.toml To your Python Project

Create a new .env.toml file in your Python project (or add these entries).
- Update the outgoing email address to your gmail address.
- Update the sms address for texts to your number, using your carrier's gateway (see .env.example.toml or do a search).
- We'll create an app password below.  

```
# SMTP Email Configuration
outgoing_email_host = "smtp.gmail.com"
outgoing_email_port = 587
outgoing_email_address = "yourname@gmail.com"
outgoing_email_password = "aaaabbbbccccdddd"

# SMS Configuration
sms_address_for_texts = "1112224444@msg.fi.google.com"
```

## Step 3. Add .env.toml To .gitignore

Ensure your secrets are not published with an entry in .gitignore:

```
.env.toml
```

## Step 4. Gmail - Enable IMAP

 - Open Gmail.
 - Click Settings or ⚙️ in the top-right.
 - Then click "See all settings".
 - Navigate to "Forwarding and POP/IMAP".
 - Under "IMAP access", select "Enable IMAP".
-  Click "Save Changes".

## Step 5. Gmail - Generate an App Password

If your account has 2FA enabled, you must generate an App Password:
- Go to <https://support.google.com/accounts/answer/185833?hl=en> 
- Click on "Create and manage your app passwords".
- Sign in and navigate to Account "Security" / "App Passwords"
- Create an app password - name it (e.g., "PythonTextAlerts"). 
- Generate and copy the 16-character password.
- Paste the 16-char as your password in .env.toml file. 
  - Remove any spaces
  - Keep it private - ensure your .env.toml file is listed in .gitignore

## Step 6. Import and Use in a Python Script

Once installed and your .env.toml file is ready, you can use it in your code. 

```python
from dc_texter import send_text

message = "Testing text alerts from Python."

try:
    send_text(body=message)
    print(f"SUCCESS. Text sent: {message}")
except RuntimeError as e:
    print(f"ERROR:  Sending failed: {e}")
```
---

## Testing

To run this file locally for testing, fork & clone the repo, add .env.toml. 
Open the project repository in VS Code, open a PowerShell terminal and run 

```
pytest
py dc_texter\texter.py
```
