swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/mail/facade.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import types
+from collections.abc import Callable
+from contextvars import ContextVar, Token
+from typing import Any, Self, TypedDict
+
+from swiftpy.mail.mailable import Mailable
+from swiftpy.mail.manager import MailManager
+from swiftpy.mail.message import MailMessage
+from swiftpy.mail.models import MailSendResult
+from swiftpy.mail.queue.job import SendQueuedMailableJob
+from swiftpy.mail.transports.base import MailTransport
+
+
+class _SentMailRecord(TypedDict):
+    """Correlated record of a message captured by MailFake."""
+
+    message: MailMessage
+    mailable: Mailable | None
+    mailer: str | None
+
+
+class MailFake(MailTransport):
+    """
+    In-memory test double for SwiftPY Mail subsystem.
+    Records sent messages and queued mailables with expressive assertion helpers.
+    Supports task-local isolation via ContextVar and synchronous/asynchronous context managers.
+    """
+
+    def __init__(self) -> None:
+        self.sent_messages: list[MailMessage] = []
+        self.sent_mailables: list[Mailable] = []
+        self.sent_records: list[_SentMailRecord] = []
+        self.queued_mailables: list[dict[str, Any]] = []
+        self._token: Token[MailFake | None] | None = None
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> None:
+        Mail.restore()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: types.TracebackType | None,
+    ) -> None:
+        Mail.restore()
+
+    async def send(
+        self,
+        message: MailMessage,
+        *,
+        mailable: Mailable | None = None,
+        mailer: str | None = None,
+    ) -> MailSendResult:
+        self.sent_messages.append(message)
+        if mailable is not None:
+            self.sent_mailables.append(mailable)
+        self.sent_records.append(
+            {
+                "message": message,
+                "mailable": mailable,
+                "mailer": mailer,
+            }
+        )
+        return MailSendResult(
+            success=True,
+            message_id=f"fake-{len(self.sent_messages)}",
+            provider="fake",
+            accepted=message.all_recipient_addresses(),
+            rejected=[],
+        )
+
+    def record_queued(
+        self,
+        mailable: Mailable,
+        queue: str | None = None,
+        delay: float = 0,
+        after_commit: bool = False,
+    ) -> None:
+        self.queued_mailables.append(
+            {
+                "mailable": mailable,
+                "queue": queue or mailable.queue,
+                "delay": delay,
+                "after_commit": after_commit,
+            }
+        )
+
+    @staticmethod
+    def _record_matches(
+        record: _SentMailRecord,
+        mailable_cls_or_filter: type[Mailable]
+        | Callable[[MailMessage], bool]
+        | None,
+        recipient: str | None,
+    ) -> tuple[bool, str | None]:
+        msg = record["message"]
+        if recipient and recipient not in msg.all_recipient_addresses():
+            return False, None
+
+        if mailable_cls_or_filter is not None:
+            if isinstance(mailable_cls_or_filter, type) and issubclass(
+                mailable_cls_or_filter, Mailable
+            ):
+                if not isinstance(record["mailable"], mailable_cls_or_filter):
+                    return False, None
+                suffix = f" to recipient '{recipient}'" if recipient else ""
+                return (
+                    True,
+                    f"Unexpected mailable of type '{mailable_cls_or_filter.__name__}' was sent{suffix}",
+                )
+            if not isinstance(mailable_cls_or_filter, type) and callable(
+                mailable_cls_or_filter
+            ):
+                if not mailable_cls_or_filter(msg):
+                    return False, None
+                suffix = f" to recipient '{recipient}'" if recipient else ""
+                return True, f"Unexpected email matching predicate was sent{suffix}"
+
+        if recipient:
+            return True, f"Unexpected email sent to recipient '{recipient}'"
+        return True, "Unexpected email was sent"
+
+    def assert_sent(
+        self,
+        mailable_cls_or_filter: type[Mailable]
+        | Callable[[MailMessage], bool]
+        | None = None,
+        recipient: str | None = None,
+        count: int | None = None,
+    ) -> None:
+        """Assert that matching emails were sent."""
+        matches = [
+            record["message"]
+            for record in self.sent_records
+            if self._record_matches(record, mailable_cls_or_filter, recipient)[0]
+        ]
+
+        if count is not None:
+            assert len(matches) == count, (
+                f"Expected {count} emails matching criteria, found {len(matches)}."
+            )
+        else:
+            assert len(matches) > 0, "Expected email was not sent."
+
+    def assert_not_sent(
+        self,
+        mailable_cls_or_filter: type[Mailable]
+        | Callable[[MailMessage], bool]
+        | None = None,
+        recipient: str | None = None,
+    ) -> None:
+        """Assert that no matching emails were sent."""
+        for record in self.sent_records:
+            matched, reason = self._record_matches(
+                record, mailable_cls_or_filter, recipient
+            )
+            if matched:
+                raise AssertionError(reason)
+
+    def assert_queued(
+        self,
+        mailable_cls: type[Mailable],
+        count: int | None = None,
+    ) -> None:
+        """Assert that a mailable of the given class was queued."""
+        matches = [
+            item
+            for item in self.queued_mailables
+            if isinstance(item["mailable"], mailable_cls)
+        ]
+        if count is not None:
+            assert len(matches) == count, (
+                f"Expected {count} queued mailables of type '{mailable_cls.__name__}', found {len(matches)}."
+            )
+        else:
+            assert len(matches) > 0, (
+                f"Expected mailable '{mailable_cls.__name__}' was not queued."
+            )
+
+    def assert_nothing_sent(self) -> None:
+        """Assert that zero emails were sent or queued."""
+        assert len(self.sent_messages) == 0, (
+            f"Expected no emails to be sent, but {len(self.sent_messages)} were sent."
+        )
+        assert len(self.queued_mailables) == 0, (
+            f"Expected no mailables to be queued, but {len(self.queued_mailables)} were queued."
+        )
+
+    def reset(self) -> None:
+        self.sent_messages.clear()
+        self.sent_mailables.clear()
+        self.sent_records.clear()
+        self.queued_mailables.clear()
+
+
+class Mail:
+    """Class-level facade for SwiftPY Mail Subsystem."""
+
+    _fake_var: ContextVar[MailFake | None] = ContextVar(
+        "swiftpy_mail_fake", default=None
+    )
+
+    @classmethod
+    def _manager(cls) -> MailManager:
+        return MailManager.get_instance()
+
+    @classmethod
+    def fake(cls) -> MailFake:
+        """Swap real delivery with the MailFake test double in the current task/context."""
+        current = cls._fake_var.get()
+        if current is None:
+            fake_instance = MailFake()
+            fake_instance._token = cls._fake_var.set(fake_instance)
+            return fake_instance
+        current.reset()
+        return current
+
+    @classmethod
+    def restore(cls) -> None:
+        """Restore real mail delivery after testing."""
+        cls._fake_var.set(None)
+
+    @classmethod
+    def is_faked(cls) -> bool:
+        return cls._fake_var.get() is not None
+
+    @classmethod
+    def mailer(cls, name: str | None = None) -> MailTransport:
+        """Resolve a configured mail transport instance."""
+        fake_instance = cls._fake_var.get()
+        if fake_instance is not None:
+            return fake_instance
+        return cls._manager().mailer(name)
+
+    @classmethod
+    def extend(
+        cls,
+        driver_name: str,
+        factory: Callable[[dict[str, Any]], MailTransport],
+    ) -> None:
+        """Register a custom mail transport."""
+        cls._manager().extend(driver_name, factory)
+
+    @classmethod
+    async def send(
+        cls,
+        mailable_or_message: Mailable | MailMessage,
+        mailer: str | None = None,
+    ) -> MailSendResult:
+        """Deliver an email immediately."""
+        if isinstance(mailable_or_message, Mailable):
+            msg = await mailable_or_message.build_message()
+            target_mailer = mailer or mailable_or_message.mailer_name
+            sent_mailable: Mailable | None = mailable_or_message
+        else:
+            msg = mailable_or_message
+            target_mailer = mailer
+            sent_mailable = None
+
+        fake_instance = cls._fake_var.get()
+        if fake_instance is not None:
+            return await fake_instance.send(
+                msg, mailable=sent_mailable, mailer=target_mailer
+            )
+
+        return await cls._manager().send(msg, mailer=target_mailer)
+
+    @classmethod
+    async def queue(
+        cls,
+        mailable: Mailable,
+        queue: str | None = None,
+        delay: float = 0,
+        after_commit: bool = False,
+    ) -> str:
+        """Dispatch a mailable onto the background queue."""
+        fake_instance = cls._fake_var.get()
+        if fake_instance is not None:
+            fake_instance.record_queued(
+                mailable,
+                queue=queue,
+                delay=delay,
+                after_commit=after_commit,
+            )
+            return f"fake-job-{len(fake_instance.queued_mailables)}"
+
+        job = SendQueuedMailableJob(
+            mailable=mailable,
+            queue=queue or mailable.queue,
+            delay=delay,
+        )
+        return await job.dispatch(
+            queue=queue or mailable.queue,
+            delay=delay,
+            after_commit=after_commit,
+        )
+
+
+__all__ = ["Mail", "MailFake"]

swiftpy/mail/mailable.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import inspect
+from abc import ABC, abstractmethod
+from typing import Any
+
+from swiftpy.mail.message import MailMessage
+from swiftpy.mail.templates.renderer import MailTemplateRenderer
+
+
+class Mailable(ABC):
+    """
+    Abstract base class for reusable email definitions.
+    Separates email composition and rendering from business logic.
+    """
+
+    mailer_name: str | None = None
+    queue: str = "emails"
+    tries: int = 3
+    timeout: float | None = 60.0
+    backoff: int | float = 5
+
+    @abstractmethod
+    def build(self) -> MailMessage | Any:
+        """Construct the MailMessage representing this email."""
+
+    async def build_message(self) -> MailMessage:
+        """
+        Execute build(), awaiting if asynchronous, apply template rendering if needed,
+        and return the validated MailMessage.
+        """
+        result = self.build()
+        if inspect.isawaitable(result):
+            result = await result
+
+        if not isinstance(result, MailMessage):
+            raise TypeError(
+                f"Mailable {self.__class__.__name__}.build() must return MailMessage, "
+                f"got {type(result).__name__}"
+            )
+
+        if result.template:
+            renderer = MailTemplateRenderer.get_instance()
+            rendered = await renderer.render(result.template, result.context)
+            if rendered.html and not result.html_body:
+                result.html_body = rendered.html
+            if rendered.text and not result.text_body:
+                result.text_body = rendered.text
+
+        return result
+
+
+__all__ = ["Mailable"]

swiftpy/mail/manager.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+from typing import Any
+
+from swiftpy.core.config import Config
+from swiftpy.core.container import get_container
+from swiftpy.mail.config import MailConfig
+from swiftpy.mail.exceptions import (
+    AttachmentTooLargeError,
+    MailConfigurationError,
+    MailerNotFoundError,
+)
+from swiftpy.mail.message import MailMessage, _validate_no_crlf, parse_mail_address
+from swiftpy.mail.models import MailSendResult
+from swiftpy.mail.transports.api.mailgun import MailgunTransport
+from swiftpy.mail.transports.api.resend import ResendTransport
+from swiftpy.mail.transports.api.sendgrid import SendGridTransport
+from swiftpy.mail.transports.base import MailTransport
+from swiftpy.mail.transports.console import ConsoleTransport
+from swiftpy.mail.transports.sendmail import SendmailTransport
+from swiftpy.mail.transports.smtp import SMTPTransport
+
+
+class MailManager:
+    """
+    Registry and factory for configured MailTransport instances.
+    Integrates with SwiftPY's configuration repository and DI container.
+    """
+
+    _instance: MailManager | None = None
+
+    def __init__(self, config: Config | None = None) -> None:
+        if config is None:
+            try:
+                container = get_container()
+                if container.has(Config):
+                    self.config = container.resolve(Config)
+                else:
+                    self.config = Config.get_instance()
+            except RuntimeError:
+                self.config = Config.get_instance()
+        else:
+            self.config = config
+
+        self._transports: dict[str, MailTransport] = {}
+        self._custom_creators: dict[str, Callable[[dict[str, Any]], MailTransport]] = {}
+
+    @classmethod
+    def get_instance(cls) -> MailManager:
+        if cls._instance is not None:
+            return cls._instance
+
+        try:
+            container = get_container()
+            if container.has(cls):
+                return container.resolve(cls)
+        except RuntimeError:
+            pass
+
+        cls._instance = cls()
+        return cls._instance
+
+    @property
+    def mail_config(self) -> MailConfig:
+        raw_mail = self.config.get("mail", {})
+        if isinstance(raw_mail, dict):
+            return MailConfig.from_dict(raw_mail)
+        return MailConfig()
+
+    @property
+    def default_mailer_name(self) -> str:
+        return self.mail_config.default
+
+    @property
+    def default_from(self) -> tuple[str, str | None]:
+        cfg = self.mail_config
+        return cfg.from_address, cfg.from_name
+
+    def extend(
+        self,
+        driver_name: str,
+        factory: Callable[[dict[str, Any]], MailTransport],
+    ) -> None:
+        """Register a custom mail transport creator."""
+        self._custom_creators[driver_name.lower()] = factory
+
+    def mailer(self, name: str | None = None) -> MailTransport:
+        """Resolve a mail transport instance by name, or return the default mailer."""
+        mailer_name = name or self.default_mailer_name
+
+        if mailer_name in self._transports:
+            return self._transports[mailer_name]
+
+        transport = self._resolve_transport(mailer_name)
+        self._transports[mailer_name] = transport
+        return transport
+
+    def _resolve_transport(self, name: str) -> MailTransport:
+        mailers = self.mail_config.mailers
+        if name not in mailers:
+            # Fallback check directly in config if not parsed into mailers dict
+            raw_mailers = self.config.get("mail.mailers", {})
+            if isinstance(raw_mailers, dict) and name in raw_mailers:
+                mailer_config = raw_mailers[name]
+            else:
+                raise MailerNotFoundError(f"Mailer '{name}' is not configured.")
+        else:
+            mailer_config = mailers[name]
+
+        if not isinstance(mailer_config, dict):
+            raise MailConfigurationError(
+                f"Configuration for mailer '{name}' must be a dictionary."
+            )
+
+        driver_type = str(mailer_config.get("transport", "")).lower()
+
+        cfg = self.mail_config
+        max_att_val = mailer_config.get(
+            "max_attachment_size_bytes", cfg.max_attachment_size_bytes
+        )
+        max_msg_val = mailer_config.get(
+            "max_message_size_bytes", cfg.max_message_size_bytes
+        )
+        max_att = int(max_att_val) if max_att_val is not None else None
+        max_msg = int(max_msg_val) if max_msg_val is not None else None
+
+        if driver_type in self._custom_creators:
+            return self._custom_creators[driver_type](mailer_config)
+
+        if driver_type == "smtp":
+            return SMTPTransport.from_config(
+                mailer_config,
+                default_from=self.default_from,
+                max_attachment_size_bytes=max_att,
+                max_message_size_bytes=max_msg,
+            )
+
+        if driver_type in ("console", "log"):
+            return ConsoleTransport.from_config(
+                mailer_config,
+                max_attachment_size_bytes=max_att,
+                max_message_size_bytes=max_msg,
+            )
+
+        if driver_type == "sendmail":
+            return SendmailTransport.from_config(
+                mailer_config,
+                default_from=self.default_from,
+                max_attachment_size_bytes=max_att,
+                max_message_size_bytes=max_msg,
+            )
+
+        if driver_type == "resend":
+            return ResendTransport.from_config(
+                mailer_config,
+                default_from=self.default_from,
+                max_attachment_size_bytes=max_att,
+                max_message_size_bytes=max_msg,
+            )
+
+        if driver_type == "sendgrid":
+            return SendGridTransport.from_config(
+                mailer_config,
+                default_from=self.default_from,
+                max_attachment_size_bytes=max_att,
+                max_message_size_bytes=max_msg,
+            )
+
+        if driver_type == "mailgun":
+            return MailgunTransport.from_config(
+                mailer_config,
+                default_from=self.default_from,
+                max_attachment_size_bytes=max_att,
+                max_message_size_bytes=max_msg,
+            )
+
+        raise MailConfigurationError(f"Unsupported mail transport: '{driver_type}'")
+
+    async def send(
+        self,
+        message: MailMessage,
+        mailer: str | None = None,
+    ) -> MailSendResult:
+        """Deliver an email message using the specified or default mailer."""
+        cfg = self.mail_config
+        default_addr, default_name = cfg.from_address, cfg.from_name
+        if default_addr:
+            parse_mail_address(default_addr, field_name="default_from")
+        if default_name:
+            _validate_no_crlf(default_name, "default_from_name")
+
+        outbound_from_addr = message.from_address or default_addr or None
+        outbound_from_name = (
+            message.from_name
+            if message.from_address
+            else (message.from_name or default_name)
+        )
+        outbound = replace(
+            message,
+            to=list(message.to),
+            cc=list(message.cc),
+            bcc=list(message.bcc),
+            from_address=outbound_from_addr,
+            from_name=outbound_from_name,
+            context=dict(message.context),
+            attachments=list(message.attachments),
+            headers=dict(message.headers),
+            tags=list(message.tags),
+            metadata=dict(message.metadata),
+        )
+
+        # Enforce upfront limits for known sizes across all transports
+        total_known = len((outbound.text_body or "").encode("utf-8")) + len(
+            (outbound.html_body or "").encode("utf-8")
+        )
+        for att in outbound.attachments:
+            if att.size is not None:
+                if att.size > cfg.max_attachment_size_bytes:
+                    raise AttachmentTooLargeError(
+                        f"Attachment '{att.filename}' ({att.size} bytes) exceeds size limit ({cfg.max_attachment_size_bytes} bytes)"
+                    )
+                total_known += att.size
+        if total_known > cfg.max_message_size_bytes:
+            raise AttachmentTooLargeError(
+                f"Total email size ({total_known} bytes) exceeds configured limit ({cfg.max_message_size_bytes} bytes)"
+            )
+
+        transport = self.mailer(mailer)
+        return await transport.send(outbound)
+
+    async def close(self) -> None:
+        """Close and clean up all instantiated mail transports."""
+        for transport in self._transports.values():
+            await transport.close()
+        self._transports.clear()
+
+
+__all__ = ["MailManager"]