pymailfeedback 0.1.0__py3-none-any.whl

pymailfeedback/__init__.py

@@ -0,0 +1,3 @@
+from .core import sendstatus, sendmsg, sendbeacon, readsec
+
+__all__ = ["sendstatus", "sendmsg", "sendbeacon", "readsec"]

pymailfeedback/core.py

@@ -0,0 +1,480 @@
+import os
+import sys
+import time
+import json
+import socket
+import smtplib
+import platform
+import traceback
+import getpass
+import inspect
+from pathlib import Path
+from functools import wraps
+from email.message import EmailMessage
+import multiprocessing as mp
+
+# Global configuration variables, lazily populated by _ensure_config_loaded()
+_SENDER_EMAIL = ""
+_SENDER_PASSWORD = ""
+_SMTP_SERVER = "smtp.mail.yahoo.com"
+_SMTP_PORT = 465
+_DEFAULT_RECIPIENT = ""
+_DEFAULT_VERBOSE = 0
+_CONFIG_LOADED = False  # NEW: tracks whether config has been loaded yet
+
+_TIC_TIMES = []
+_BEACON_NEXT_TIME = None
+
+_TIC_TIMES = []
+_BEACON_NEXT_TIME = None
+
+_CONFIG_PATH_HOME = Path.home() / ".pymailfeedback.json"
+_CONFIG_PATH_CWD = Path.cwd() / ".pymailfeedback.json"
+
+_CONFIG_FACSIMILE = """{
+    "sender_email": "sender_email@gmail.com",
+    "sender_password": "sender__app_password",
+    "smtp_server": "smtp.mail.yahoo.com",
+    "smtp_port": 465,
+    "default_recipient": "recipient@example.com",
+    "default_verbose": 0
+}"""
+
+
+# ---------------------------------------------------------------------------
+# CONFIGURATION HANDLING
+# ---------------------------------------------------------------------------
+
+def _interactive_setup():
+    """Guides the user interactively to create a configuration file."""
+    print("\n" + "=" * 50)
+    print(" pymailfeedback - First Time Setup")
+    print("=" * 50)
+    print("Let's create a configuration file now.")
+    print(f"It will be saved to: {_CONFIG_PATH_HOME.resolve()}\n")
+
+    try:
+        email = input("Sender Email (e.g., myemail@gmail.com): ").strip()
+        password = input("Sender Password (e.g., App Password): ").strip()
+        server = input("SMTP Server [press Enter for 'smtp.mail.yahoo.com']: ").strip() or "smtp.mail.yahoo.com"
+        port_str = input("SMTP Port [press Enter for '465']: ").strip() or "465"
+        port = int(port_str)
+        default_recipient = input("Default recipient email (optional, press Enter to skip): ").strip()
+        verbose_str = input("Default verbose level [0, 1, 2] (press Enter for '0'): ").strip() or "0"
+        default_verbose = int(verbose_str)
+    except (KeyboardInterrupt, EOFError):
+        print("\nSetup cancelled by user.", file=sys.stderr)
+        return False
+
+    if not email or not password:
+        print("\nError: Email and password are required. Setup aborted.", file=sys.stderr)
+        return False
+
+    config_data = {
+        "sender_email": email,
+        "sender_password": password,
+        "smtp_server": server,
+        "smtp_port": port,
+        "default_recipient": default_recipient,
+        "default_verbose": default_verbose,
+    }
+
+    try:
+        with open(_CONFIG_PATH_HOME, 'w', encoding='utf-8') as f:
+            json.dump(config_data, f, indent=4)
+        print(f"\nSuccess! Configuration saved to: {_CONFIG_PATH_HOME.resolve()}")
+        print("=" * 50 + "\n")
+
+        global _SENDER_EMAIL, _SENDER_PASSWORD, _SMTP_SERVER, _SMTP_PORT, _DEFAULT_RECIPIENT, _DEFAULT_VERBOSE
+        _SENDER_EMAIL = email
+        _SENDER_PASSWORD = password
+        _SMTP_SERVER = server
+        _SMTP_PORT = port
+        _DEFAULT_RECIPIENT = default_recipient
+        _DEFAULT_VERBOSE = default_verbose
+        return True
+    except Exception as e:
+        print(f"\nFailed to save configuration: {e}", file=sys.stderr)
+        return False
+
+
+def _raise_missing_config_error():
+    """Raises a descriptive error explaining how to fix a missing configuration."""
+    raise RuntimeError(
+        "\n\nNo pymailfeedback configuration found.\n"
+        "You have two options:\n\n"
+        "1) Create the file manually at one of these locations:\n"
+        f"   - {_CONFIG_PATH_CWD.resolve()}\n"
+        f"   - {_CONFIG_PATH_HOME.resolve()}\n\n"
+        "   Using this template:\n"
+        f"{_CONFIG_FACSIMILE}\n\n"
+        "2) Run the interactive setup wizard:\n"
+        "   python -c \"from pymailfeedback.core import _interactive_setup; _interactive_setup()\"\n"
+        "   (or use the 'pymailfeedback-init' command if installed as a CLI entry point)\n"
+    )
+
+def _is_main_process():
+    """Returns True only if running in the main process (not a DataLoader worker
+    or any other multiprocessing child process)."""
+    return mp.current_process().name == "MainProcess"
+
+
+def _load_config():
+    """
+    Loads SMTP configuration. Order of precedence:
+    1. Environment variables
+    2. Local directory JSON file (./.pymailfeedback.json)
+    3. User home directory JSON file (~/.pymailfeedback.json)
+    4. Interactive setup (only in an interactive terminal)
+    If nothing is found, raises a RuntimeError explaining how to fix it.
+    """
+    global _SENDER_EMAIL, _SENDER_PASSWORD, _SMTP_SERVER, _SMTP_PORT, _DEFAULT_RECIPIENT, _DEFAULT_VERBOSE
+
+    env_email = os.getenv("PYMAIL_SENDER_EMAIL")
+    env_pwd = os.getenv("PYMAIL_SENDER_PASSWORD")
+    if env_email and env_pwd:
+        if _is_main_process():
+            print("[pymailfeedback] Using email configuration from environment variables.", file=sys.stderr)
+        _SENDER_EMAIL = env_email
+        _SENDER_PASSWORD = env_pwd
+        _SMTP_SERVER = os.getenv("PYMAIL_SMTP_SERVER", _SMTP_SERVER)
+        _SMTP_PORT = int(os.getenv("PYMAIL_SMTP_PORT", _SMTP_PORT))
+        _DEFAULT_RECIPIENT = os.getenv("PYMAIL_DEFAULT_RECIPIENT", _DEFAULT_RECIPIENT)
+        _DEFAULT_VERBOSE = int(os.getenv("PYMAIL_DEFAULT_VERBOSE", _DEFAULT_VERBOSE))
+        return
+
+    for config_path in (_CONFIG_PATH_CWD, _CONFIG_PATH_HOME):
+        if config_path.is_file():
+            try:
+                with open(config_path, 'r', encoding='utf-8') as f:
+                    config = json.load(f)
+                    _SENDER_EMAIL = config.get("sender_email", _SENDER_EMAIL)
+                    _SENDER_PASSWORD = config.get("sender_password", _SENDER_PASSWORD)
+                    _SMTP_SERVER = config.get("smtp_server", _SMTP_SERVER)
+                    _SMTP_PORT = config.get("smtp_port", _SMTP_PORT)
+                    _DEFAULT_RECIPIENT = config.get("default_recipient", _DEFAULT_RECIPIENT)
+                    _DEFAULT_VERBOSE = config.get("default_verbose", _DEFAULT_VERBOSE)
+                    if _is_main_process():
+                        print(f"[pymailfeedback] Loaded email configuration from {config_path.resolve()}.", file=sys.stderr)
+                return
+            except Exception as e:
+                print(f"Warning: Failed to read config file {config_path}: {e}", file=sys.stderr)
+
+    # Attempt interactive setup directly instead of relying on isatty().
+    # isatty() reports False in many IDE run consoles (e.g. PyCharm's Run
+    # window), even though input() still works fine there. We try the
+    # actual input() call and only give up on a real EOFError/OSError,
+    # which happens in truly non-interactive contexts (cron, CI, piped stdin).
+    try:
+        response = input("[pymailfeedback] No email configuration found. Setup now? (y/n): ").strip().lower()
+    except (EOFError, OSError):
+        _raise_missing_config_error()
+        return
+
+    if response == 'y' and _interactive_setup():
+        return
+
+    _raise_missing_config_error()
+
+
+def _ensure_config_loaded():
+    """
+    Lazily loads the configuration on first actual use.
+    This avoids raising an error just because the module was imported
+    (e.g. to call _interactive_setup() manually).
+    """
+    global _CONFIG_LOADED
+    if not _CONFIG_LOADED:
+        _load_config()
+        _CONFIG_LOADED = True
+
+def _resolve_recipient(to_addresses):
+    """Resolves the recipient list, falling back to the default recipient if none provided."""
+    if to_addresses:
+        return to_addresses
+    if _DEFAULT_RECIPIENT:
+        return _DEFAULT_RECIPIENT
+    raise ValueError(
+        "No recipient specified and no default_recipient configured. "
+        "Pass a recipient explicitly or set 'default_recipient' in your .pymailfeedback.json."
+    )
+
+
+# ---------------------------------------------------------------------------
+# UTILITIES
+# ---------------------------------------------------------------------------
+
+def _plural(n):
+    return "" if n == 1 else "s"
+
+
+def readsec(t):
+    """Converts seconds into a readable format (DAY:HH:MM:SS.mmm)."""
+    days = int(t // (24 * 3600))
+    t %= (24 * 3600)
+    hours = int(t // 3600)
+    t %= 3600
+    mins = int(t // 60)
+    sec = t % 60
+
+    time_string = ""
+    if days > 0:
+        time_string += f"{days} day{_plural(days)}, "
+    if hours > 0:
+        time_string += f"{hours} hour{_plural(hours)}, "
+    if mins > 0:
+        time_string += f"{mins} min and "
+
+    time_string += f"{sec:.3f} s"
+    return time_string
+
+
+def _shutdown_computer():
+    """Executes the appropriate system shutdown command based on the OS."""
+    system = platform.system()
+    try:
+        if system == "Windows":
+            os.system("shutdown /s /t 0")
+        elif system == "Linux":
+            os.system("sudo shutdown -h now")
+        elif system == "Darwin":
+            os.system("""osascript -e 'tell app "System Events" to shut down'""")
+        else:
+            print(f"Shutdown not supported for {system}.", file=sys.stderr)
+    except Exception as e:
+        print(f"Error during shutdown: {e}", file=sys.stderr)
+
+
+def _handle_shutdown(shutdown, shutdown_delay):
+    """Shuts down the machine after shutdown_delay seconds if shutdown is True."""
+    if shutdown:
+        print(f"[pymailfeedback] System will shut down in {shutdown_delay} seconds...")
+        time.sleep(shutdown_delay)
+        _shutdown_computer()
+
+
+# ---------------------------------------------------------------------------
+# HTML EMAIL BUILDER
+# ---------------------------------------------------------------------------
+
+def _build_html_body(title_color, content_lines, footer_lines):
+    """Builds a styled HTML email body (no leading title, subject already states it)."""
+    content_html = "".join(f"<p style='margin:4px 0;'>{line}</p>" for line in content_lines)
+    footer_html = "".join(f"<p style='margin:2px 0; color:#888; font-size:12px;'>{line}</p>" for line in footer_lines)
+
+    html = f"""\
+<html>
+<body style="font-family: Arial, sans-serif; color: #333;">
+    <div style="border-left: 4px solid {title_color}; padding-left: 12px; margin: 12px 0;">
+        {content_html}
+    </div>
+    <hr style="border:none; border-top:1px solid #ddd; margin: 16px 0;">
+    <div>
+        {footer_html}
+        <p style="margin:2px 0; font-size:12px; color:#aaa;">Generated automatically by <b>pymailfeedback</b></p>
+    </div>
+</body>
+</html>
+"""
+    return html
+
+
+def _build_plain_body(content_lines, footer_lines):
+    """Builds the plain-text fallback body (no leading title)."""
+    lines = content_lines + [""] + footer_lines + ["", "Generated automatically by pymailfeedback"]
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CORE MAIL FUNCTIONS
+# ---------------------------------------------------------------------------
+
+def sendmsg(to_addresses=None, subject="", message="", attachments=None, html_body=None):
+    """Sends an email with a subject, body message, and optional attachments."""
+    _ensure_config_loaded()
+    to_addresses = _resolve_recipient(to_addresses)
+
+    if not _SENDER_EMAIL or not _SENDER_PASSWORD:
+        print("Warning: Email credentials not configured. Skipping email.", file=sys.stderr)
+        return
+
+    msg = EmailMessage()
+    msg['Subject'] = subject
+    msg['From'] = _SENDER_EMAIL
+    msg['To'] = ", ".join(to_addresses) if isinstance(to_addresses, list) else to_addresses
+    msg.set_content(message)
+
+    if html_body:
+        msg.add_alternative(html_body, subtype='html')
+
+    if attachments:
+        if isinstance(attachments, str):
+            attachments = [attachments]
+        for filepath in attachments:
+            if os.path.exists(filepath):
+                with open(filepath, 'rb') as f:
+                    file_data = f.read()
+                    file_name = os.path.basename(filepath)
+                msg.add_attachment(file_data, maintype='application',
+                                   subtype='octet-stream', filename=file_name)
+
+    try:
+        if _SMTP_PORT == 465:
+            with smtplib.SMTP_SSL(_SMTP_SERVER, _SMTP_PORT) as server:
+                server.login(_SENDER_EMAIL, _SENDER_PASSWORD)
+                server.send_message(msg)
+        else:
+            with smtplib.SMTP(_SMTP_SERVER, _SMTP_PORT) as server:
+                server.starttls()
+                server.login(_SENDER_EMAIL, _SENDER_PASSWORD)
+                server.send_message(msg)
+    except Exception as e:
+        print(f"Failed to send email: {e}", file=sys.stderr)
+
+
+def sendstatus(to_addresses=None, verbose=None, shutdown=False, shutdown_delay=60):
+    """
+    Decorator to send the execution status via email.
+    Wraps the decorated function in a try/except block.
+
+    verbose = None: uses the default_verbose from configuration (falls back to 0)
+    verbose = 0: No attachments
+    verbose = 1: Attaches the file that caused the error
+    verbose = 2: Attaches the entire error stack trace files
+
+    shutdown: if True, shuts down the machine after the run completes (success or failure).
+    shutdown_delay: seconds to wait before shutting down the machine.
+    """
+    _ensure_config_loaded()
+    if verbose is None:
+        verbose = _DEFAULT_VERBOSE
+
+    # Summary of the decorator's configuration (recepient, verbosity, shutdown behavior)
+    if _is_main_process():
+        print(f"[pymailfeedback] sendstatus decorator configured with recipient(s): {to_addresses or _DEFAULT_RECIPIENT}, "
+                f"shutdown: {shutdown}, shutdown_delay: {shutdown_delay} seconds.", file=sys.stderr)
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            global _TIC_TIMES
+            start_time = time.time()
+            _TIC_TIMES.append(start_time)
+
+            try:
+                username = getpass.getuser()
+                computername = socket.gethostname()
+            except Exception:
+                username, computername = "Unknown", "Unknown"
+
+            func_name = func.__name__
+            try:
+                func_file = inspect.getsourcefile(func)
+                file_label = os.path.basename(func_file) if func_file else "unknown_file"
+            except TypeError:
+                func_file = "Unknown path"
+                file_label = "unknown_file"
+
+            exit_status = 0
+            error_traceback = ""
+            try:
+                result = func(*args, **kwargs)
+                return result
+            except Exception:
+                exit_status = 1
+                error_traceback = traceback.format_exc()
+                raise
+            finally:
+                elapsed = time.time() - start_time
+                elapsed_str = readsec(elapsed)
+
+                if exit_status == 1:
+                    subject = f"[{file_label}] {func_name} — ❌ FAILURE"
+                    title_color = "#d32f2f"
+                    content_lines = [
+                        f"<b>Dear {username},</b>",
+                        f"Function <b>{func_name}</b> in <b>{file_label}</b> has failed with the following error:",
+                        f"<pre style='color:#d32f2f; font-weight:bold; background:#fdecea; padding:8px; border-radius:4px; white-space:pre-wrap;'>{error_traceback}</pre>",
+                    ]
+                    plain_content = [
+                        f"Dear {username},",
+                        f"Function {func_name} in {file_label} failed with the following error:",
+                        error_traceback,
+                    ]
+                else:
+                    subject = f"[{file_label}] {func_name} — ✅ SUCCESS"
+                    title_color = "#2e7d32"
+                    content_lines = [
+                        f"<b>Dear {username},</b>",
+                        f"Function <b>{func_name}</b> in <b>{file_label}</b> completed successfully.",
+                    ]
+                    plain_content = [
+                        f"Dear {username},",
+                        f"Function {func_name} in {file_label} completed successfully.",
+                    ]
+
+                footer_lines = [
+                    f"Machine: {computername}",
+                    f"Full path: {func_file}",
+                    f"Elapsed time: {elapsed_str}",
+                    f"Verbose level: {verbose}",
+                ]
+
+                html_body = _build_html_body(title_color, content_lines, footer_lines)
+                plain_body = _build_plain_body(plain_content, footer_lines)
+
+                attachments = []
+                if exit_status == 1 and verbose > 0:
+                    _, _, tb = sys.exc_info()
+                    extracted_tb = traceback.extract_tb(tb)
+
+                    if verbose >= 1 and func_file and os.path.exists(func_file):
+                        attachments.append(func_file)
+
+                    if verbose >= 2:
+                        module_file = Path(__file__).resolve()
+                        for frame in extracted_tb:
+                            if Path(frame.filename) == module_file: # exclude this file
+                                continue
+                            if os.path.exists(frame.filename) and frame.filename not in attachments:
+                                attachments.append(frame.filename)
+
+                sendmsg(to_addresses, subject, plain_body, attachments, html_body=html_body)
+
+                _handle_shutdown(shutdown, shutdown_delay)
+
+        return wrapper
+    return decorator
+
+
+def sendbeacon(to_addresses=None, delta_time_minutes=60):
+    """Sends a periodic 'alive' email if delta_time_minutes has passed since the last beacon."""
+    _ensure_config_loaded()
+    global _BEACON_NEXT_TIME
+    current_time = time.time()
+
+    if _BEACON_NEXT_TIME is None:
+        _BEACON_NEXT_TIME = current_time + (delta_time_minutes * 60)
+        return
+
+    if current_time >= _BEACON_NEXT_TIME:
+        to_addresses = _resolve_recipient(to_addresses)
+        try:
+            computername = socket.gethostname()
+        except Exception:
+            computername = "Unknown"
+
+        subject = f"[{computername}] beacon — 🟢 Still Running"
+        content_lines = [
+            "<b>So far so good!</b>",
+            f"Beacon signal generated every {readsec(delta_time_minutes * 60)}."
+        ]
+        html_body = _build_html_body("#2e7d32", content_lines, [f"Machine: {computername}"])
+        plain_body = _build_plain_body(
+            ["So far so good!", f"Beacon signal generated every {readsec(delta_time_minutes * 60)}"],
+            [f"Machine: {computername}"]
+        )
+
+        sendmsg(to_addresses, subject, plain_body, html_body=html_body)
+
+        _BEACON_NEXT_TIME = current_time + (delta_time_minutes * 60)

pymailfeedback-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: pymailfeedback
+Version: 0.1.0
+Summary: Email yourself automatically when a long-running Python script succeeds or fails — with traceback, attachments, and more
+Author-email: Daniele Mascali <danielemascali@gmail.com>
+Project-URL: Homepage, https://github.com/dmascali/pymailfeedback
+Project-URL: Repository, https://github.com/dmascali/pymailfeedback
+Project-URL: Issues, https://github.com/dmascali/pymailfeedback/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+
+# pymailfeedback
+
+**Never wonder if your long-running script finished or crashed.**
+
+**pymailfeedback** is Python decorator that emails you the moment your script finishes, whether it succeeded or crashed. Get instant notifications with full tracebacks on failure and optional file attachments.
+
+<div>
+  <img src="https://raw.githubusercontent.com/dmascali/pymailfeedback/refs/heads/master/assets/example_success_msg.png" alt="Example Success" width="75%" />
+</div>
+<br />
+<div>
+  <img src="https://raw.githubusercontent.com/dmascali/pymailfeedback/refs/heads/master/assets/example_failure_msg.png" alt="Example Failure" width="75%" />
+</div>
+
+This project is a Python port of [MatlabMailFeedback](https://github.com/dmascali/MatlabMailFeedback). `pymailfeedback` reproduces the same core idea — wrapping a script/function in a try/except block to report its exit status by email.
+
+## Installation
+
+```bash
+pip install pymailfeedback
+```
+
+---
+
+## Quick start
+
+```python
+from pymailfeedback import sendstatus
+
+@sendstatus("recipient@example.com")
+def train_model():
+    # your long-running code here
+    ...
+
+train_model()
+```
+
+That's it. If `train_model()` finishes normally, you get a ✅ SUCCESS email. If it raises an exception, you get a ❌ FAILURE email with the full traceback — and the exception is still re-raised, so your program behaves exactly as if the decorator wasn't there.
+
+---
+
+## `sendstatus` — the core feature
+
+`sendstatus` is a **decorator**. Place it directly above the function or script entry point you want to monitor:
+
+```python
+@sendstatus(to_addresses=None, verbose=None, shutdown=False, shutdown_delay=60)
+def my_function(...):
+    ...
+```
+
+| Parameter | Description                                                                                                                                                                                                                        |
+|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `to_addresses` | Recipient email address, or a list of addresses. If omitted, the `default_recipient` from your configuration is used.                                                                                                              |
+| `verbose` | Controls attachments sent on failure: `0` = no attachment, `1` = attach the file that caused the error, `2` = attach the entire traceback's file stack. If omitted, uses `default_verbose` from your configuration (default: `0`). |
+| `shutdown` | If `True`, shuts down the machine after the run completes, regardless of success or failure.                                                                                                                                       |
+| `shutdown_delay` | Seconds to wait before shutting down (default 60 seconds).                                                                                                                                                                         |
+
+## Configuration
+
+`pymailfeedback` needs SMTP credentials (sender email + password) to actually send mail.
+There are three ways to configure it, checked in this order (note: you probably want to go with option 2 or 3):
+
+### 1. Environment variables
+
+| Variable | Maps to                                          | Required |
+|---|--------------------------------------------------|---|
+| `PYMAIL_SENDER_EMAIL` | sender email                                     | Yes |
+| `PYMAIL_SENDER_PASSWORD` | sender password (e.g. a Yahoo Mail App Password) | Yes |
+| `PYMAIL_SMTP_SERVER` | SMTP server                                      | No (default: `smtp.mail.yahoo.com`) |
+| `PYMAIL_SMTP_PORT` | SMTP port                                        | No (default: `465`) |
+| `PYMAIL_DEFAULT_RECIPIENT` | default recipient if none is passed explicitly   | No |
+| `PYMAIL_DEFAULT_VERBOSE` | default verbose level                            | No (default: `0`) |
+
+```bash
+export PYMAIL_SENDER_EMAIL="you@gmail.com"
+export PYMAIL_SENDER_PASSWORD="your_app_password"
+export PYMAIL_DEFAULT_RECIPIENT="you@example.com"
+python train.py
+```
+
+If both `PYMAIL_SENDER_EMAIL` and `PYMAIL_SENDER_PASSWORD` are set, environment variables take priority over any JSON config file.
+
+### 2. A JSON configuration file (recommended)
+
+Create a file named `.pymailfeedback.json`, either in your current working directory or in your home directory (checked in that order):
+
+```json
+{
+    "sender_email": "you@gmail.com",
+    "sender_password": "your_app_password",
+    "smtp_server": "smtp.mail.yahoo.com",
+    "smtp_port": 465,
+    "default_recipient": "you@example.com",
+    "default_verbose": 0
+}
+```
+
+### 3. Interactive setup wizard
+
+If no environment variables or config file are found, and you're running in an interactive terminal, `pymailfeedback` will offer to walk you through creating `~/.pymailfeedback.json` on the spot. You can also trigger this manually at any time:
+
+```bash
+python -c "from pymailfeedback.core import _interactive_setup; _interactive_setup()"
+```
+
+It will prompt you for the sender email, password, SMTP server/port, default recipient, and default verbose level, then print exactly where the file was saved.
+
+### No configuration found?
+
+If configuration is missing and no interactive terminal is available (e.g. inside a script run non-interactively), `pymailfeedback` raises a `RuntimeError` with a ready-to-copy JSON template and the command to launch the setup wizard.
+
+---
+
+## A note on security: don't use your personal email
+
+Whichever configuration method you choose, the sender password ends up stored in plain text somewhere on your machine — in a JSON file, in an environment variable, or in your shell history. That's fine for a throwaway or dedicated address, but it is **not wise** to use your personal, everyday email account for this. If that password (or app password) ever leaks — through a shared server, a committed config file, a misconfigured Docker image — you don't want it to be the same account tied to your personal identity, contacts, and other services.
+
+**Best practice: create a dedicated, "burner" email account used only for sending these notifications.** [Yahoo Mail](https://mail.yahoo.com) is a good, free choice for this. Once created, don't use its regular password in `pymailfeedback` — generate a dedicated **App Password** instead, which can be revoked independently at any time without affecting the account's main login:
+
+1. Sign in to your new Yahoo account and go to **Account settings**.
+2. Open **External Connections** (sometimes shown as "App passwords" depending on the region/UI).
+3. Select **Create app password** (a generic label like "python" or "pymailfeedback" is fine).
+4. Copy the generated password and use it as `sender_password` — either in your `.pymailfeedback.json` file or as the `PYMAIL_SENDER_PASSWORD` environment variable.
+5. Set `smtp_server` to `smtp.mail.yahoo.com` when using a Yahoo account.
+
+This way, even in the worst case, the only thing exposed is a disposable notification account, not your main mailbox.
+
+---
+
+## Extra utilities
+
+These are optional helpers built on top of the same configuration system. `sendstatus` is the main feature — the rest are conveniences for specific use cases.
+
+### `sendmsg`
+
+Send a one-off email manually, with an optional attachment:
+
+```python
+from pymailfeedback import sendmsg
+
+sendmsg("you@example.com", subject="Checkpoint saved", message="Epoch 50 completed.")
+```
+
+If `to_addresses` is omitted, the configured `default_recipient` is used.
+
+### `sendbeacon`
+
+Send a periodic "still alive" email from inside a long-running loop, without spamming your inbox every iteration:
+
+```python
+from pymailfeedback import sendbeacon
+
+for epoch in range(1000):
+    # ... training code ...
+    sendbeacon(delta_time_minutes=60 * 12)  # one email every ~12 hours
+```

pymailfeedback-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pymailfeedback/__init__.py,sha256=1oXCXkGTORPhXDajYmMu3feFUXVDCl1PS078IkV7VlI,124
+pymailfeedback/core.py,sha256=kKCf5Cu4fNhKCOmCGuhdDaK423Hb5kleXQcMU0Oe_WY,19296
+pymailfeedback-0.1.0.dist-info/METADATA,sha256=awpjSBpBwePT0P5nvOFETISdl-2JiyrWsu9YZa9IFAo,8858
+pymailfeedback-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pymailfeedback-0.1.0.dist-info/entry_points.txt,sha256=kRaKkoDbzDloENXMFfQ9WaECHlCmqjqs-RH0CSY3uPk,79
+pymailfeedback-0.1.0.dist-info/top_level.txt,sha256=k2bEc_OQS7wPgeNdH3QXMRyIDGw4EIqAxbFydbrzxd8,15
+pymailfeedback-0.1.0.dist-info/RECORD,,

pymailfeedback-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pymailfeedback-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pymailfeedback-init = pymailfeedback.core:_interactive_setup

pymailfeedback-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pymailfeedback