velocity-python 0.1.95__tar.gz → 0.1.98__tar.gz

{velocity_python-0.1.95 → velocity_python-0.1.98}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.95
+Version: 0.1.98
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -253,7 +253,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
-| Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |
+| Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing and SMTP sending |
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 

{velocity_python-0.1.95 → velocity_python-0.1.98}/README.md

@@ -159,7 +159,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions, async jobs (JobHandler + job result stores) |
 | NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
-| Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |
+| Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing and SMTP sending |
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |
 | Security | `docs/SECURITY.md` | Pre-commit hooks, credential scanning |
 

{velocity_python-0.1.95 → velocity_python-0.1.98}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.95"
+version = "0.1.98"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.95 → velocity_python-0.1.98}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.95"
+__version__ = version = "0.1.98"
 
 import importlib as _importlib
 

{velocity_python-0.1.95 → velocity_python-0.1.98}/src/velocity/aws/handlers/mixins/web_handler.py

@@ -395,13 +395,27 @@ Request Details:
         return ""
 
     def _get_sendmail_callable(self):
-        """Resolve notification sender callable without hard dependency."""
+        """Resolve notification sender callable without hard dependency.
+
+        An application-supplied ``support.app.helpers.sendmail`` wins so
+        existing projects keep their own delivery rules (recipient whitelists,
+        non-production rewriting, send logging). Projects without that package
+        fall back to velocity's own SMTP sender, which resolves configuration
+        from an ``email_settings`` row or the ``Mail*`` config keys — before
+        this fallback existed they silently sent nothing.
+        """
         try:
             from support.app import helpers
 
-            return getattr(helpers, "sendmail", None)
+            app_sendmail = getattr(helpers, "sendmail", None)
+            if app_sendmail is not None:
+                return app_sendmail
         except ImportError:
-            return None
+            pass
+
+        from velocity.misc.mail import sendmail
+
+        return sendmail
 
     def _get_error_context(self, context) -> str:
         """Sanitize request context for reporting"""

velocity_python-0.1.98/src/velocity/misc/mail.py

@@ -0,0 +1,453 @@
+#!/usr/local/bin/python
+from email.parser import Parser as EmailParser
+from email.message import Message
+from typing import Any, Dict, List, Optional, Sequence, cast
+import mimetypes
+import hashlib
+
+
+class NotSupportedMailFormat(Exception):
+    """Exception raised for unsupported mail formats."""
+
+    pass
+
+
+class Attachment:
+    """Represents an email attachment."""
+
+    def __init__(self, name: str, data: bytes):
+        self.name = name
+        self.data = data
+        self.ctype = mimetypes.guess_type(name)[0] or "application/octet-stream"
+        self.size = len(data)
+        self.hash = hashlib.sha1(data).hexdigest()
+
+
+def get_full_emails(addresses: Sequence[Any]) -> List[str]:
+    """Generates a list of formatted email addresses with names."""
+    results = []
+    for a in addresses:
+        mailbox = a.mailbox.decode("utf-8")
+        host = a.host.decode("utf-8")
+        name = a.name.decode("utf-8") if a.name else None
+        if name:
+            results.append(f"{name} <{mailbox}@{host}>")
+        else:
+            results.append(f"{mailbox}@{host}")
+    return results
+
+
+def get_address_only(addresses: Sequence[Any]) -> List[str]:
+    """Generates a list of email addresses without names."""
+    return [f"{a.mailbox.decode('utf-8')}@{a.host.decode('utf-8')}" for a in addresses]
+
+
+def parse_attachment(part: Message) -> Optional[Attachment]:
+    """Parses an attachment from a message part if present."""
+    content_disposition = part.get("Content-Disposition")
+    if content_disposition:
+        dispositions = content_disposition.strip().split(";")
+        if dispositions[0].lower() == "attachment":
+            name = part.get_filename()
+            payload = part.get_payload(decode=True)
+            data = cast(
+                Optional[bytes],
+                payload if isinstance(payload, (bytes, bytearray)) else None,
+            )
+            if name and data is not None:
+                return Attachment(name=name, data=bytes(data))
+    return None
+
+
+def parse(content: str) -> Dict[str, Any]:
+    """Parses the email content and extracts plain text, HTML, and attachments."""
+    body = bytearray()
+    html = bytearray()
+    attachments: List[Attachment] = []
+
+    message = EmailParser().parsestr(content)
+    for part in message.walk():
+        attachment = parse_attachment(part)
+        if attachment:
+            attachments.append(attachment)
+        elif part.get_content_type() == "text/plain":
+            payload = part.get_payload(decode=True)
+            if isinstance(payload, (bytes, bytearray)):
+                body.extend(payload)
+        elif part.get_content_type() == "text/html":
+            payload = part.get_payload(decode=True)
+            if isinstance(payload, (bytes, bytearray)):
+                html.extend(payload)
+
+    return {
+        "body": body.decode("utf-8") if body else None,
+        "html": html.decode("utf-8") if html else None,
+        "attachments": attachments,
+    }
+
+
+# ── Outbound mail ───────────────────────────────────────────────────────────
+#
+# Everything above parses inbound mail. Everything below sends it.
+#
+# velocity had no sender: `WebHandler.send_error_notification` resolves a
+# `sendmail` callable by importing an application package, so any project
+# without that package silently sent nothing. `sendmail` below is a drop-in
+# with the same signature, so the framework can fall back to it.
+#
+# Two configuration sources, because both are already in use:
+#   * `SmtpConfig.from_env()`            — Mail* keys via velocity's ssm_config
+#   * `SmtpConfig.from_email_settings()` — an `email_settings` row (rot13-obscured,
+#                                          the legacy storage format)
+
+import codecs
+import smtplib
+from dataclasses import dataclass, replace
+from email.message import EmailMessage
+
+
+class MailConfigurationError(Exception):
+    """Raised when SMTP configuration is absent or incomplete."""
+
+
+DEFAULT_EMAIL_SETTINGS_ID = 1000
+
+
+def _clean(value: Any) -> str:
+    return "" if value is None else str(value).strip()
+
+
+def _as_list(value: Any) -> List[str]:
+    """Normalize None / str / iterable into a list of non-empty addresses."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        items = [value]
+    else:
+        items = list(value)
+    return [_clean(item) for item in items if _clean(item)]
+
+
+def _rot13(value: Any) -> str:
+    text = _clean(value)
+    return codecs.decode(text, "rot13") if text else ""
+
+
+@dataclass(frozen=True)
+class SmtpConfig:
+    """Connection settings for an SMTP relay.
+
+    ``sender`` is the default From address; it can be overridden per message.
+    """
+
+    host: str
+    port: int = 587
+    username: Optional[str] = None
+    password: Optional[str] = None
+    sender: Optional[str] = None
+    use_tls: bool = True
+    timeout: int = 30
+
+    def __post_init__(self):
+        if not _clean(self.host):
+            raise MailConfigurationError("SmtpConfig: host is required")
+
+    @classmethod
+    def from_env(cls, **overrides) -> "SmtpConfig":
+        """Build from the ``Mail*`` config keys, resolved through ssm_config.
+
+        Reads ``MailHost``, ``MailPort``, ``MailAccount``, ``MailPassword``,
+        ``MailFrom`` and ``MailUseTls`` — SSM first, then the environment,
+        following the standard ``/{Project}/{stage}/`` → ``/Global/{stage}/``
+        lookup order. Keyword arguments override any resolved value.
+        """
+        from velocity.aws import ssm_config
+
+        host = overrides.pop("host", None) or ssm_config.getenv("MailHost")
+        if not _clean(host):
+            raise MailConfigurationError(
+                "SmtpConfig.from_env: MailHost is not configured (checked SSM "
+                "and the environment)"
+            )
+        use_tls = overrides.pop("use_tls", None)
+        if use_tls is None:
+            use_tls = _clean(ssm_config.getenv("MailUseTls", "true")).lower() not in (
+                "false",
+                "0",
+                "no",
+            )
+        config = cls(
+            host=_clean(host),
+            port=int(overrides.pop("port", None) or ssm_config.getenv("MailPort", 587)),
+            username=overrides.pop("username", None)
+            or ssm_config.getenv("MailAccount"),
+            password=overrides.pop("password", None)
+            or ssm_config.getenv("MailPassword"),
+            sender=overrides.pop("sender", None) or ssm_config.getenv("MailFrom"),
+            use_tls=bool(use_tls),
+        )
+        return replace(config, **overrides) if overrides else config
+
+    @classmethod
+    def from_email_settings(
+        cls,
+        tx,
+        sys_id: int = DEFAULT_EMAIL_SETTINGS_ID,
+        obscured: bool = True,
+        **overrides,
+    ) -> "SmtpConfig":
+        """Build from a row of the ``email_settings`` table.
+
+        The legacy storage format rot13-obscures ``host_name``, ``user_name``
+        and ``password`` — that is obfuscation, not encryption, and is decoded
+        here for compatibility with existing rows. Pass ``obscured=False`` for
+        rows stored in the clear.
+        """
+        row = tx.table("email_settings").find(sys_id)
+        if not row:
+            raise MailConfigurationError(
+                f"SmtpConfig.from_email_settings: no email_settings row {sys_id}"
+            )
+        decode = _rot13 if obscured else _clean
+        config = cls(
+            host=decode(row.get("host_name")),
+            port=int(row.get("port") or 587),
+            username=decode(row.get("user_name")) or None,
+            password=decode(row.get("password")) or None,
+            sender=_clean(row.get("sender")) or None,
+            use_tls=bool(row.get("ttls")),
+        )
+        return replace(config, **overrides) if overrides else config
+
+
+def build_message(
+    subject: str,
+    sender: str,
+    recipient: Any,
+    body: Optional[str] = None,
+    html: Optional[str] = None,
+    cc: Any = None,
+    bcc: Any = None,
+    reply_to: Any = None,
+    attachments: Optional[Dict[str, Any]] = None,
+    headers: Optional[Dict[str, str]] = None,
+) -> EmailMessage:
+    """Assemble an ``EmailMessage`` from plain text and/or HTML.
+
+    Pure: builds and returns, never connects. ``attachments`` maps a filename
+    to bytes, a readable object, or a path to read.
+    """
+    if not _clean(body) and not _clean(html):
+        raise ValueError("build_message: one of body or html is required")
+    if not _clean(sender):
+        raise ValueError("build_message: sender is required")
+
+    to = _as_list(recipient)
+    if not to:
+        raise ValueError("build_message: at least one recipient is required")
+
+    message = EmailMessage()
+    message["Subject"] = _clean(subject)
+    message["From"] = _clean(sender)
+    message["To"] = ", ".join(to)
+
+    cc_list = _as_list(cc)
+    if cc_list:
+        message["Cc"] = ", ".join(cc_list)
+    bcc_list = _as_list(bcc)
+    if bcc_list:
+        message["Bcc"] = ", ".join(bcc_list)
+    reply_to_list = _as_list(reply_to)
+    if reply_to_list:
+        message["Reply-To"] = ", ".join(reply_to_list)
+    for key, value in (headers or {}).items():
+        message[key] = value
+
+    # set_content then add_alternative yields multipart/alternative with the
+    # plain part first, which is the order mail clients expect.
+    if _clean(body):
+        message.set_content(body)
+        if _clean(html):
+            message.add_alternative(html, subtype="html")
+    else:
+        message.set_content(html, subtype="html")
+
+    for name, value in (attachments or {}).items():
+        if isinstance(value, bytes):
+            data = value
+        elif hasattr(value, "read"):
+            data = value.read()
+        elif isinstance(value, str):
+            with open(value, "rb") as handle:
+                data = handle.read()
+        else:
+            raise TypeError(
+                f"build_message: cannot attach {name!r} of type {type(value)}"
+            )
+        maintype, _, subtype = (
+            mimetypes.guess_type(name)[0] or "application/octet-stream"
+        ).partition("/")
+        message.add_attachment(
+            data, maintype=maintype, subtype=subtype or "octet-stream", filename=name
+        )
+
+    return message
+
+
+class Mailer:
+    """Sends ``EmailMessage``s over SMTP.
+
+    ``connection_factory`` exists so tests (and alternate transports) can
+    supply their own connection; by default a ``smtplib.SMTP`` is opened per
+    send and closed again.
+    """
+
+    def __init__(self, config: SmtpConfig, connection_factory=None):
+        self.config = config
+        self._connection_factory = connection_factory
+
+    def _connect(self):
+        if self._connection_factory is not None:
+            return self._connection_factory(self.config)
+        return smtplib.SMTP(
+            self.config.host, self.config.port, timeout=self.config.timeout
+        )
+
+    def send_message(self, message: EmailMessage) -> EmailMessage:
+        """Deliver an already-built message; returns it for logging."""
+        recipients = []
+        for header in ("To", "Cc", "Bcc"):
+            value = message.get(header)
+            if value:
+                recipients.extend(
+                    part.strip() for part in str(value).split(",") if part.strip()
+                )
+        if not recipients:
+            raise ValueError("Mailer.send_message: message has no recipients")
+
+        sender = _clean(message.get("From")) or _clean(self.config.sender)
+        connection = self._connect()
+        try:
+            connection.ehlo()
+            if self.config.use_tls:
+                connection.starttls()
+                connection.ehlo()
+            if _clean(self.config.username):
+                connection.login(self.config.username, self.config.password or "")
+            connection.sendmail(sender, recipients, message.as_string())
+        finally:
+            try:
+                connection.quit()
+            except Exception:  # pragma: no cover - best-effort close
+                pass
+        return message
+
+    def send(
+        self,
+        subject: str,
+        recipient: Any,
+        body: Optional[str] = None,
+        html: Optional[str] = None,
+        sender: Optional[str] = None,
+        cc: Any = None,
+        bcc: Any = None,
+        reply_to: Any = None,
+        attachments: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> EmailMessage:
+        """Build and deliver one message."""
+        from_address = _clean(sender) or _clean(self.config.sender)
+        if not from_address:
+            raise MailConfigurationError(
+                "Mailer.send: no sender given and the config has no default (MailFrom)"
+            )
+        message = build_message(
+            subject=subject,
+            sender=from_address,
+            recipient=recipient,
+            body=body,
+            html=html,
+            cc=cc,
+            bcc=bcc,
+            reply_to=reply_to,
+            attachments=attachments,
+            headers=headers,
+        )
+        return self.send_message(message)
+
+
+def _resolve_config(tx, email_settings_id: Optional[int]) -> SmtpConfig:
+    """email_settings row when one is named and reachable, otherwise Mail* keys.
+
+    A project can have the framework's default settings id without having the
+    table (velocity's own error notifier passes 1001 unconditionally), so a
+    missing row falls through to environment config rather than failing.
+    """
+    if email_settings_id is not None and tx is not None:
+        try:
+            return SmtpConfig.from_email_settings(tx, email_settings_id)
+        except MailConfigurationError:
+            pass
+        except Exception:
+            pass
+    return SmtpConfig.from_env()
+
+
+def sendmail(
+    tx=None,
+    subject: str = "",
+    body: Optional[str] = None,
+    html: Optional[str] = None,
+    sender: Optional[str] = None,
+    recipient: Any = None,
+    cc: Any = None,
+    bcc: Any = None,
+    attachments: Optional[Dict[str, Any]] = None,
+    email_settings_id: Optional[int] = None,
+    reply_to: Any = None,
+    config: Optional[SmtpConfig] = None,
+    connection_factory=None,
+    log_table: Optional[str] = None,
+) -> EmailMessage:
+    """Send one message, resolving configuration the way each caller expects.
+
+    Signature-compatible with the application-supplied ``sendmail`` that
+    ``WebHandler.send_error_notification`` looks for, so it can serve as the
+    framework's own fallback.
+
+    Configuration precedence: an explicit ``config``; else the ``email_settings``
+    row named by ``email_settings_id`` (when both it and ``tx`` are given);
+    else the ``Mail*`` config keys.
+
+    When ``log_table`` is given and ``tx`` is available, one row per send is
+    written there — the table must already exist; this never creates schema.
+    """
+    if config is None:
+        config = _resolve_config(tx, email_settings_id)
+
+    message = Mailer(config, connection_factory=connection_factory).send(
+        subject=subject,
+        recipient=recipient,
+        body=body,
+        html=html,
+        sender=sender,
+        cc=cc,
+        bcc=bcc,
+        reply_to=reply_to,
+        attachments=attachments,
+    )
+
+    if log_table and tx is not None:
+        tx.table(log_table).insert(
+            {
+                "subject": _clean(subject),
+                "body": body,
+                "html": html,
+                "sender": _clean(message.get("From")),
+                "recipient": ", ".join(_as_list(recipient)),
+                "cc": ", ".join(_as_list(cc)) or None,
+                "bcc": ", ".join(_as_list(bcc)) or None,
+            }
+        )
+
+    return message