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

{velocity_python-0.1.98/src/velocity_python.egg-info → velocity_python-0.1.99}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.98
+Version: 0.1.99
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

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

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

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

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

velocity_python-0.1.99/src/velocity/aws/email.py

@@ -0,0 +1,173 @@
+"""Outbound email over Amazon SES.
+
+The counterpart to ``velocity.aws.sms``: same shape, same injectable-client
+pattern, same "lazily construct boto3 on first use" behaviour.
+
+Why this exists alongside the SMTP sender in ``velocity.misc.mail``: SES
+authenticates with the caller's **IAM role**, so there is no password to store,
+rotate, obfuscate, or leak. An SMTP relay needs a credential kept somewhere,
+and "somewhere" is where credentials rot — in a config key, in a database
+column, in two places that drift apart.
+
+Messages are handed to SES as raw MIME (``Content.Raw``) rather than as the
+simple subject/body structure, because ``velocity.misc.mail.build_message``
+already produces a correct ``EmailMessage`` — multipart/alternative, Reply-To,
+attachments and all — and re-expressing that in SES's simple format would only
+lose fidelity.
+"""
+
+from __future__ import annotations
+
+import logging
+from email.message import EmailMessage
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["EmailClient", "SesError"]
+
+
+class SesError(Exception):
+    """Raised when SES rejects a message."""
+
+
+def _header_addresses(message: EmailMessage, header: str) -> List[str]:
+    value = message.get(header)
+    if not value:
+        return []
+    return [part.strip() for part in str(value).split(",") if part.strip()]
+
+
+class EmailClient:
+    """Outbound email via Amazon SES (v2).
+
+    ``sender`` is the default From address and must be a verified SES identity
+    (or belong to a verified domain). A per-call ``sender`` overrides it.
+
+    ``configuration_set`` is how bounce and complaint events get published —
+    set one up pointing at an SNS topic and SES will report what happened to
+    each message, which is the part SMTP never told you.
+    """
+
+    def __init__(
+        self,
+        sender: Optional[str] = None,
+        configuration_set: Optional[str] = None,
+        client=None,
+        region: Optional[str] = None,
+    ):
+        self.sender = sender
+        self.configuration_set = configuration_set
+        self.region = region
+        self._client = client
+
+    @property
+    def client(self):
+        if self._client is None:
+            import boto3
+
+            kwargs = {"region_name": self.region} if self.region else {}
+            self._client = boto3.client("sesv2", **kwargs)
+        return self._client
+
+    def send_message(
+        self,
+        message: EmailMessage,
+        sender: Optional[str] = None,
+        configuration_set: Optional[str] = None,
+    ) -> str:
+        """Deliver an already-built ``EmailMessage``; returns the SES message id.
+
+        Bcc recipients are passed to SES as destinations and the Bcc header is
+        removed from the transmitted MIME — a Bcc header left in place is
+        visible to every recipient, which defeats the point of blind copying.
+        """
+        to = _header_addresses(message, "To")
+        cc = _header_addresses(message, "Cc")
+        bcc = _header_addresses(message, "Bcc")
+        if not (to or cc or bcc):
+            raise ValueError("EmailClient.send_message: message has no recipients")
+
+        if bcc:
+            del message["Bcc"]
+
+        from_address = str(sender or message.get("From") or self.sender or "").strip()
+        if not from_address:
+            raise ValueError(
+                "EmailClient.send_message: no sender given and the client has no default"
+            )
+
+        params: Dict[str, Any] = {
+            "FromEmailAddress": from_address,
+            "Destination": {"ToAddresses": to},
+            "Content": {"Raw": {"Data": message.as_bytes()}},
+        }
+        if cc:
+            params["Destination"]["CcAddresses"] = cc
+        if bcc:
+            params["Destination"]["BccAddresses"] = bcc
+        configuration_set = configuration_set or self.configuration_set
+        if configuration_set:
+            params["ConfigurationSetName"] = configuration_set
+
+        try:
+            response = self.client.send_email(**params)
+        except Exception as exc:  # surface SES's own message, typed
+            raise SesError(f"SES rejected the message: {exc}") from exc
+        return response.get("MessageId", "")
+
+    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,
+        configuration_set: Optional[str] = None,
+    ) -> str:
+        """Build and deliver one message; returns the SES message id."""
+        # Imported here rather than at module scope: misc.mail imports nothing
+        # from aws, and keeping the dependency one-directional avoids a cycle.
+        from velocity.misc.mail import build_message
+
+        from_address = str(sender or self.sender or "").strip()
+        if not from_address:
+            raise ValueError(
+                "EmailClient.send: no sender given and the client has no default "
+                "(set MailFrom, or pass sender=)"
+            )
+        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, configuration_set=configuration_set)
+
+    @classmethod
+    def from_env(cls, **overrides) -> "EmailClient":
+        """Build from config: ``MailFrom``, ``MailConfigurationSet``, ``AWS_REGION``."""
+        from velocity.aws import ssm_config
+
+        sender = overrides.pop("sender", None) or ssm_config.getenv("MailFrom")
+        configuration_set = overrides.pop(
+            "configuration_set", None
+        ) or ssm_config.getenv("MailConfigurationSet")
+        region = overrides.pop("region", None) or ssm_config.get_region(None)
+        return cls(
+            sender=sender,
+            configuration_set=configuration_set,
+            region=region,
+            **overrides,
+        )

velocity_python-0.1.99/src/velocity/aws/tests/test_email.py

@@ -0,0 +1,344 @@
+"""Unit tests for velocity.aws.email (SES) and the transport selection in
+velocity.misc.mail.sendmail.
+
+Nothing here talks to AWS: EmailClient takes an injectable client, the same way
+SmsClient does.
+"""
+
+import unittest
+from email import message_from_bytes
+from email import policy
+
+from velocity.aws.email import EmailClient, SesError
+from velocity.misc.mail import (
+    TRANSPORT_SES,
+    TRANSPORT_SMTP,
+    build_message,
+    resolve_transport,
+    sendmail,
+)
+
+
+class FakeSes:
+    """Records what would have been handed to SES."""
+
+    def __init__(self, error=None):
+        self.calls = []
+        self.error = error
+
+    def send_email(self, **params):
+        self.calls.append(params)
+        if self.error:
+            raise self.error
+        return {"MessageId": "ses-message-id-1"}
+
+    # Convenience: the raw MIME of the most recent call, parsed back.
+    def last_message(self):
+        # policy=default so the round trip yields an EmailMessage (with
+        # iter_attachments), not a legacy compat32 Message.
+        return message_from_bytes(
+            self.calls[-1]["Content"]["Raw"]["Data"], policy=policy.default
+        )
+
+
+class FakeTable:
+    def __init__(self, inserts):
+        self.inserts = inserts
+
+    def insert(self, data):
+        self.inserts.append(dict(data))
+        return dict(data)
+
+
+class FakeTx:
+    def __init__(self):
+        self.inserts = []
+
+    def table(self, name):
+        return FakeTable(self.inserts)
+
+
+class TestEmailClient(unittest.TestCase):
+    def client(self, **kwargs):
+        ses = FakeSes(error=kwargs.pop("error", None))
+        return EmailClient(client=ses, **kwargs), ses
+
+    def test_send_delivers_raw_mime_with_destinations(self):
+        client, ses = self.client(sender="Tenspace <info@example.com>")
+        message_id = client.send(
+            subject="Hello",
+            recipient="visitor@example.com",
+            body="Plain",
+            html="<p>Rich</p>",
+        )
+        self.assertEqual(message_id, "ses-message-id-1")
+        params = ses.calls[0]
+        self.assertEqual(params["FromEmailAddress"], "Tenspace <info@example.com>")
+        self.assertEqual(params["Destination"]["ToAddresses"], ["visitor@example.com"])
+        parsed = ses.last_message()
+        self.assertEqual(parsed["Subject"], "Hello")
+        self.assertTrue(parsed.is_multipart())
+
+    def test_reply_to_and_attachments_survive_the_raw_round_trip(self):
+        client, ses = self.client(sender="info@example.com")
+        client.send(
+            subject="Hello",
+            recipient="visitor@example.com",
+            body="Plain",
+            reply_to="sales@example.com",
+            attachments={"note.txt": b"file body"},
+        )
+        parsed = ses.last_message()
+        self.assertEqual(parsed["Reply-To"], "sales@example.com")
+        self.assertEqual(
+            [p.get_filename() for p in parsed.iter_attachments()], ["note.txt"]
+        )
+
+    def test_bcc_is_a_destination_but_never_a_transmitted_header(self):
+        # A Bcc header left in the MIME is shown to every recipient, which is
+        # precisely what a blind copy must not do.
+        client, ses = self.client(sender="info@example.com")
+        client.send(
+            subject="Hello",
+            recipient="visitor@example.com",
+            body="Plain",
+            cc="cc@example.com",
+            bcc="secret@example.com",
+        )
+        params = ses.calls[0]
+        self.assertEqual(params["Destination"]["CcAddresses"], ["cc@example.com"])
+        self.assertEqual(params["Destination"]["BccAddresses"], ["secret@example.com"])
+        parsed = ses.last_message()
+        self.assertIsNone(parsed["Bcc"])
+        self.assertEqual(parsed["Cc"], "cc@example.com")
+
+    def test_configuration_set_is_passed_when_set(self):
+        client, ses = self.client(
+            sender="info@example.com", configuration_set="tracking"
+        )
+        client.send(subject="Hello", recipient="a@example.com", body="x")
+        self.assertEqual(ses.calls[0]["ConfigurationSetName"], "tracking")
+
+    def test_no_configuration_set_key_when_unset(self):
+        client, ses = self.client(sender="info@example.com")
+        client.send(subject="Hello", recipient="a@example.com", body="x")
+        self.assertNotIn("ConfigurationSetName", ses.calls[0])
+
+    def test_sender_is_required(self):
+        client, _ = self.client()
+        with self.assertRaises(ValueError):
+            client.send(subject="Hello", recipient="a@example.com", body="x")
+
+    def test_message_without_recipients_is_rejected(self):
+        client, _ = self.client(sender="info@example.com")
+        message = build_message(
+            subject="s", sender="info@example.com", recipient="a@example.com", body="x"
+        )
+        del message["To"]
+        with self.assertRaises(ValueError):
+            client.send_message(message)
+
+    def test_ses_failures_are_typed(self):
+        client, _ = self.client(
+            sender="info@example.com", error=RuntimeError("Throttled")
+        )
+        with self.assertRaises(SesError) as caught:
+            client.send(subject="Hello", recipient="a@example.com", body="x")
+        self.assertIn("Throttled", str(caught.exception))
+
+
+class TestTransportSelection(unittest.TestCase):
+    def test_explicit_argument_wins(self):
+        self.assertEqual(resolve_transport("ses"), TRANSPORT_SES)
+        self.assertEqual(resolve_transport("SMTP"), TRANSPORT_SMTP)
+
+    def test_sendmail_routes_to_ses_and_logs_the_send(self):
+        ses = FakeSes()
+        tx = FakeTx()
+        message = sendmail(
+            tx,
+            subject="Hello",
+            body="Plain",
+            html="<p>Rich</p>",
+            sender="Tenspace <info@example.com>",
+            recipient="visitor@example.com",
+            reply_to="visitor@example.com",
+            transport="ses",
+            client=ses,
+            log_table="sys_log_email",
+        )
+        self.assertEqual(len(ses.calls), 1)
+        self.assertEqual(message["Subject"], "Hello")
+        self.assertEqual(len(tx.inserts), 1)
+        self.assertEqual(tx.inserts[0]["recipient"], "visitor@example.com")
+
+    def test_ses_transport_needs_no_smtp_credential(self):
+        # The point of the migration: no email_settings row, no Mail* password,
+        # no tx required for configuration.
+        ses = FakeSes()
+        sendmail(
+            None,
+            subject="Hello",
+            body="Plain",
+            sender="info@example.com",
+            recipient="a@example.com",
+            transport="ses",
+            client=ses,
+        )
+        self.assertEqual(len(ses.calls), 1)
+
+    def test_ses_is_the_default_transport(self):
+        import os
+
+        saved = os.environ.get("MailTransport")
+        os.environ.pop("MailTransport", None)
+        os.environ["VELOCITY_SSM_ENABLED"] = "false"
+        try:
+            from velocity.aws import ssm_config
+
+            ssm_config.clear_cache()
+            self.assertEqual(resolve_transport(), TRANSPORT_SES)
+        finally:
+            if saved is not None:
+                os.environ["MailTransport"] = saved
+
+    def test_mail_transport_config_key_pins_smtp(self):
+        import os
+
+        saved = os.environ.get("MailTransport")
+        os.environ["MailTransport"] = "smtp"
+        os.environ["VELOCITY_SSM_ENABLED"] = "false"
+        try:
+            from velocity.aws import ssm_config
+
+            ssm_config.clear_cache()
+            self.assertEqual(resolve_transport(), TRANSPORT_SMTP)
+        finally:
+            if saved is None:
+                os.environ.pop("MailTransport", None)
+            else:
+                os.environ["MailTransport"] = saved
+
+    def test_mail_transport_config_key_selects_ses(self):
+        import os
+
+        saved = os.environ.get("MailTransport")
+        os.environ["MailTransport"] = "ses"
+        os.environ["VELOCITY_SSM_ENABLED"] = "false"
+        try:
+            from velocity.aws import ssm_config
+
+            ssm_config.clear_cache()
+            self.assertEqual(resolve_transport(), TRANSPORT_SES)
+        finally:
+            if saved is None:
+                os.environ.pop("MailTransport", None)
+            else:
+                os.environ["MailTransport"] = saved
+
+
+class TestSesFallsBackToSmtp(unittest.TestCase):
+    """SES is the default; SMTP catches it when SES cannot deliver."""
+
+    def smtp_config(self):
+        from velocity.misc.mail import SmtpConfig
+
+        return SmtpConfig(
+            host="smtp.example.com",
+            username="test-user@example.com",
+            password="test-password",
+            sender="Tenspace <info@example.com>",
+        )
+
+    def test_ses_failure_delivers_over_smtp(self):
+        from velocity.misc.tests.test_mail_send import FakeSmtp
+
+        ses = FakeSes(error=RuntimeError("Throttled"))
+        smtp = FakeSmtp()
+        with self.assertLogs("velocity.misc.mail", level="WARNING"):
+            message = sendmail(
+                None,
+                subject="Hello",
+                body="Plain",
+                sender="info@example.com",
+                recipient="a@example.com",
+                transport="ses",
+                client=ses,
+                config=self.smtp_config(),
+                connection_factory=lambda _c: smtp,
+            )
+        self.assertEqual(len(ses.calls), 1)
+        self.assertEqual(len(smtp.sent), 1)
+        self.assertEqual(message["Subject"], "Hello")
+
+    def test_smtp_is_untouched_when_ses_succeeds(self):
+        from velocity.misc.tests.test_mail_send import FakeSmtp
+
+        ses = FakeSes()
+        smtp = FakeSmtp()
+        sendmail(
+            None,
+            subject="Hello",
+            body="Plain",
+            sender="info@example.com",
+            recipient="a@example.com",
+            transport="ses",
+            client=ses,
+            config=self.smtp_config(),
+            connection_factory=lambda _c: smtp,
+        )
+        self.assertEqual(len(ses.calls), 1)
+        self.assertEqual(smtp.sent, [])
+
+    def test_both_failing_reports_both_causes(self):
+        from velocity.misc.mail import MailDeliveryError
+
+        ses = FakeSes(error=RuntimeError("Throttled"))
+
+        def exploding_smtp(_config):
+            from velocity.misc.tests.test_mail_send import FakeSmtp
+
+            smtp = FakeSmtp()
+
+            def boom(*_a, **_k):
+                raise RuntimeError("relay refused")
+
+            smtp.sendmail = boom
+            return smtp
+
+        with self.assertLogs("velocity.misc.mail", level="WARNING"):
+            with self.assertRaises(MailDeliveryError) as caught:
+                sendmail(
+                    None,
+                    subject="Hello",
+                    body="Plain",
+                    sender="info@example.com",
+                    recipient="a@example.com",
+                    transport="ses",
+                    client=ses,
+                    config=self.smtp_config(),
+                    connection_factory=exploding_smtp,
+                )
+        text = str(caught.exception)
+        self.assertIn("Throttled", text)
+        self.assertIn("relay refused", text)
+
+    def test_fallback_can_be_disabled(self):
+        ses = FakeSes(error=RuntimeError("Throttled"))
+        with self.assertRaises(Exception) as caught:
+            sendmail(
+                None,
+                subject="Hello",
+                body="Plain",
+                sender="info@example.com",
+                recipient="a@example.com",
+                transport="ses",
+                client=ses,
+                config=self.smtp_config(),
+                fallback=False,
+            )
+        self.assertIn("Throttled", str(caught.exception))
+
+
+if __name__ == "__main__":
+    unittest.main()