persistence-kit 3.12.0__tar.gz → 3.13.0__tar.gz

{persistence_kit-3.12.0 → persistence_kit-3.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.12.0
+Version: 3.13.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -22,6 +22,7 @@ Provides-Extra: all
 Provides-Extra: api
 Provides-Extra: dynamodb
 Provides-Extra: encrypted
+Provides-Extra: mail
 Provides-Extra: restclient
 Provides-Extra: security
 Provides-Extra: security-cognito
@@ -33,6 +34,7 @@ Requires-Dist: boto3 (>=1.35.0,<2.0.0) ; extra == "storage-s3" or extra == "secu
 Requires-Dist: cryptography (>=42.0.0,<43.0.0) ; extra == "encrypted" or extra == "testing" or extra == "all"
 Requires-Dist: fastapi (>=0.115.0,<1.0.0) ; extra == "api" or extra == "storage-routes" or extra == "security" or extra == "security-cognito" or extra == "encrypted" or extra == "testing" or extra == "all"
 Requires-Dist: httpx (>=0.28.0,<1.0.0) ; extra == "restclient" or extra == "testing" or extra == "all"
+Requires-Dist: jinja2 (>=3.1.4,<4.0.0) ; extra == "mail" or extra == "testing" or extra == "all"
 Requires-Dist: motor (>=3.7.1,<4.0.0)
 Requires-Dist: pydantic-settings (>=2.3.0,<3.0.0)
 Requires-Dist: pyjwt[crypto] (>=2.10.1,<3.0.0) ; extra == "security" or extra == "security-cognito" or extra == "testing" or extra == "all"
@@ -152,7 +154,8 @@ pip install "persistence-kit[api,security,restclient]"
 | `dynamodb` | DynamoDB repository backend | boto3 |
 | `restclient` | The REST client and its cache | httpx |
 | `encrypted` | Encrypted request and response payloads | fastapi, cryptography |
-| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography |
+| `mail` | Mail templates rendered with Jinja2 (sending itself needs no extra) | jinja2 |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2 |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -171,6 +174,7 @@ add, not an obscure `ImportError`.
 | `security/` | Identity providers and JWT verifiers, memory or Cognito, and the encrypted envelope format |
 | `restclient/` | HTTP client with pluggable auth, endpoint resolution, retries and DTO decoding |
 | `cache/` | Key-value cache with TTL: memory, Mongo or DynamoDB |
+| `mail/` | Outbound mail through an SMTP relay, with templates that live in the app |
 | `resilience/` | Circuit breaker, shared by anything that calls out |
 | `api/` | Reusable FastAPI pieces: error handlers, pagination, rate limiting, encrypted routes |
 | `bootstrap/` | Startup helpers, configuration registry, seed orchestration |
@@ -333,6 +337,69 @@ Both are covered in depth in [`docs/restclient_and_cache.md`](docs/restclient_an
 
 Needs `[restclient]`.
 
+## Mail
+
+Sending mail from an application without it knowing which relay carries it.
+The kit ships the machinery and no templates: the words belong to the app that
+sends them.
+
+```python
+from persistence_kit.mail import MailMessage, build_mailer
+
+mailer = build_mailer("app/templates/mail")
+
+message = mailer.compose(
+    "user_roles_changed",
+    to="ana@udea.edu.co",
+    cc=["coordinacion@udea.edu.co"],
+    bcc="auditoria@udea.edu.co",
+    context={"name": "Ana", "roles": ["Préstamos", "Reportes"]},
+)
+mailer.dispatch(message)
+```
+
+A template is up to three files in the app's directory: `user_roles_changed.subject.txt`
+(required), and `user_roles_changed.html` or `user_roles_changed.txt` (at least one).
+They are Jinja2, so a layout can be shared with `{% extends %}`. HTML is autoescaped,
+and a variable missing from the context fails instead of rendering blank.
+
+`to`, `cc`, `bcc` and `reply_to` take a string, a `MailAddress` or a list of them.
+Blind copies travel in the SMTP envelope only and never appear in the headers.
+Attachments go in `attachments` as `MailAttachment(filename, content, content_type)`.
+
+`compose` raises on a broken template, so a test that composes every template
+catches it. `dispatch` delivers in the background: if the relay fails, the error
+is logged and the request that triggered the mail carries on. Use `await
+mailer.send(message)` when the caller has to know, and `await
+mailer.wait_for_pending()` in tests or at shutdown.
+
+Images are embedded, not linked: `<img src="cid:logo.png">` in a template attaches
+`images/logo.png` from the same directory as an inline part, so it shows even where
+remote images are blocked. `compose` adds it on its own; a missing file or one that
+is not an image fails like a missing variable. `MailAttachment(..., content_id=...)`
+does the same for images the caller builds.
+
+A template can carry a fourth file, `user_roles_changed.sample.json`, with an
+example context. `MailTemplates.names()` lists the templates and
+`sample_context(name)` reads that file, so one parametrized test covers them all.
+The same sample drives the preview, which renders without sending:
+
+```bash
+python -m persistence_kit.mail.preview app/templates/mail user_roles_changed
+```
+
+It writes the `.html` and the `.txt` to a temporary folder, prints the subject
+and opens the HTML in the browser. Without names it renders every template;
+`--output` changes the folder and `--no-open` skips the browser.
+
+The sender is chosen by `MAIL_BACKEND`. `memory` keeps messages in
+`MemoryMailSender.sent`, for tests and for local runs where no relay accepts you.
+`smtp` delivers through `SmtpMailSender`, which upgrades with STARTTLS and logs in
+only if `MAIL_SMTP_USERNAME` is set, so a relay that authorizes by IP works as is.
+
+Needs `[mail]` for templates. `MailMessage` and the senders use only the standard
+library.
+
 ## Resilience
 
 `CircuitBreaker` is domain-agnostic and shared by anything that calls out: after
@@ -357,7 +424,7 @@ class Settings(PersistenceKitSettings):
 ```
 
 The factories read that object: `get_identity_provider`, `get_token_verifier`,
-`get_export_storage`, `get_cache`.
+`get_export_storage`, `get_cache`, `get_mail_sender`.
 
 ### Environment variables
 
@@ -375,6 +442,12 @@ The factories read that object: `get_identity_provider`, `get_token_verifier`,
 | `ENCRYPTED_PRIVATE_KEY` | Base64 PEM of the RSA private key that unwraps encrypted payloads |
 | `ENCRYPTED_TYPE` | `memory` (default, key generated at startup), `local`, or `kms` for AWS KMS |
 | `KMS_KEY_ID` | The KMS key that unwraps the AES key, required by `kms` |
+| `MAIL_BACKEND` | `memory` (default) or `smtp` |
+| `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | Default sender. The address is required by `smtp` |
+| `MAIL_SMTP_HOST`, `MAIL_SMTP_PORT` | The relay. Port defaults to `587` |
+| `MAIL_SMTP_STARTTLS` | Upgrade the connection with STARTTLS. Defaults to `true` |
+| `MAIL_SMTP_USERNAME`, `MAIL_SMTP_PASSWORD` | Only for relays that require a login |
+| `MAIL_SMTP_TIMEOUT_SECONDS` | Connection and command timeout. Defaults to `30` |
 
 ## Wiring it into an application
 
@@ -498,11 +571,11 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **555 tests passing** (version 3.12.0). Async tests use
+Current baseline: **621 tests passing** (version 3.13.0). Async tests use
 `pytest-asyncio` in strict mode, so each one carries `@pytest.mark.asyncio`.
 
 `tests/test_capabilities.py` guards the lazy-import promise: it fails if merely
-importing `persistence_kit` drags in fastapi, pyjwt or boto3.
+importing `persistence_kit` drags in fastapi, pyjwt, boto3 or jinja2.
 
 ## Releasing
 

{persistence_kit-3.12.0 → persistence_kit-3.13.0}/README.md

@@ -106,7 +106,8 @@ pip install "persistence-kit[api,security,restclient]"
 | `dynamodb` | DynamoDB repository backend | boto3 |
 | `restclient` | The REST client and its cache | httpx |
 | `encrypted` | Encrypted request and response payloads | fastapi, cryptography |
-| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography |
+| `mail` | Mail templates rendered with Jinja2 (sending itself needs no extra) | jinja2 |
+| `testing` | Everything the test suite needs | fastapi, pyjwt, httpx, python-multipart, cryptography, jinja2 |
 | `all` | Every optional capability | all of the above |
 
 Importing `persistence_kit` never loads an optional dependency by itself. Ask for
@@ -125,6 +126,7 @@ add, not an obscure `ImportError`.
 | `security/` | Identity providers and JWT verifiers, memory or Cognito, and the encrypted envelope format |
 | `restclient/` | HTTP client with pluggable auth, endpoint resolution, retries and DTO decoding |
 | `cache/` | Key-value cache with TTL: memory, Mongo or DynamoDB |
+| `mail/` | Outbound mail through an SMTP relay, with templates that live in the app |
 | `resilience/` | Circuit breaker, shared by anything that calls out |
 | `api/` | Reusable FastAPI pieces: error handlers, pagination, rate limiting, encrypted routes |
 | `bootstrap/` | Startup helpers, configuration registry, seed orchestration |
@@ -287,6 +289,69 @@ Both are covered in depth in [`docs/restclient_and_cache.md`](docs/restclient_an
 
 Needs `[restclient]`.
 
+## Mail
+
+Sending mail from an application without it knowing which relay carries it.
+The kit ships the machinery and no templates: the words belong to the app that
+sends them.
+
+```python
+from persistence_kit.mail import MailMessage, build_mailer
+
+mailer = build_mailer("app/templates/mail")
+
+message = mailer.compose(
+    "user_roles_changed",
+    to="ana@udea.edu.co",
+    cc=["coordinacion@udea.edu.co"],
+    bcc="auditoria@udea.edu.co",
+    context={"name": "Ana", "roles": ["Préstamos", "Reportes"]},
+)
+mailer.dispatch(message)
+```
+
+A template is up to three files in the app's directory: `user_roles_changed.subject.txt`
+(required), and `user_roles_changed.html` or `user_roles_changed.txt` (at least one).
+They are Jinja2, so a layout can be shared with `{% extends %}`. HTML is autoescaped,
+and a variable missing from the context fails instead of rendering blank.
+
+`to`, `cc`, `bcc` and `reply_to` take a string, a `MailAddress` or a list of them.
+Blind copies travel in the SMTP envelope only and never appear in the headers.
+Attachments go in `attachments` as `MailAttachment(filename, content, content_type)`.
+
+`compose` raises on a broken template, so a test that composes every template
+catches it. `dispatch` delivers in the background: if the relay fails, the error
+is logged and the request that triggered the mail carries on. Use `await
+mailer.send(message)` when the caller has to know, and `await
+mailer.wait_for_pending()` in tests or at shutdown.
+
+Images are embedded, not linked: `<img src="cid:logo.png">` in a template attaches
+`images/logo.png` from the same directory as an inline part, so it shows even where
+remote images are blocked. `compose` adds it on its own; a missing file or one that
+is not an image fails like a missing variable. `MailAttachment(..., content_id=...)`
+does the same for images the caller builds.
+
+A template can carry a fourth file, `user_roles_changed.sample.json`, with an
+example context. `MailTemplates.names()` lists the templates and
+`sample_context(name)` reads that file, so one parametrized test covers them all.
+The same sample drives the preview, which renders without sending:
+
+```bash
+python -m persistence_kit.mail.preview app/templates/mail user_roles_changed
+```
+
+It writes the `.html` and the `.txt` to a temporary folder, prints the subject
+and opens the HTML in the browser. Without names it renders every template;
+`--output` changes the folder and `--no-open` skips the browser.
+
+The sender is chosen by `MAIL_BACKEND`. `memory` keeps messages in
+`MemoryMailSender.sent`, for tests and for local runs where no relay accepts you.
+`smtp` delivers through `SmtpMailSender`, which upgrades with STARTTLS and logs in
+only if `MAIL_SMTP_USERNAME` is set, so a relay that authorizes by IP works as is.
+
+Needs `[mail]` for templates. `MailMessage` and the senders use only the standard
+library.
+
 ## Resilience
 
 `CircuitBreaker` is domain-agnostic and shared by anything that calls out: after
@@ -311,7 +376,7 @@ class Settings(PersistenceKitSettings):
 ```
 
 The factories read that object: `get_identity_provider`, `get_token_verifier`,
-`get_export_storage`, `get_cache`.
+`get_export_storage`, `get_cache`, `get_mail_sender`.
 
 ### Environment variables
 
@@ -329,6 +394,12 @@ The factories read that object: `get_identity_provider`, `get_token_verifier`,
 | `ENCRYPTED_PRIVATE_KEY` | Base64 PEM of the RSA private key that unwraps encrypted payloads |
 | `ENCRYPTED_TYPE` | `memory` (default, key generated at startup), `local`, or `kms` for AWS KMS |
 | `KMS_KEY_ID` | The KMS key that unwraps the AES key, required by `kms` |
+| `MAIL_BACKEND` | `memory` (default) or `smtp` |
+| `MAIL_FROM_ADDRESS`, `MAIL_FROM_NAME` | Default sender. The address is required by `smtp` |
+| `MAIL_SMTP_HOST`, `MAIL_SMTP_PORT` | The relay. Port defaults to `587` |
+| `MAIL_SMTP_STARTTLS` | Upgrade the connection with STARTTLS. Defaults to `true` |
+| `MAIL_SMTP_USERNAME`, `MAIL_SMTP_PASSWORD` | Only for relays that require a login |
+| `MAIL_SMTP_TIMEOUT_SECONDS` | Connection and command timeout. Defaults to `30` |
 
 ## Wiring it into an application
 
@@ -452,11 +523,11 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **555 tests passing** (version 3.12.0). Async tests use
+Current baseline: **621 tests passing** (version 3.13.0). Async tests use
 `pytest-asyncio` in strict mode, so each one carries `@pytest.mark.asyncio`.
 
 `tests/test_capabilities.py` guards the lazy-import promise: it fails if merely
-importing `persistence_kit` drags in fastapi, pyjwt or boto3.
+importing `persistence_kit` drags in fastapi, pyjwt, boto3 or jinja2.
 
 ## Releasing
 

persistence_kit-3.13.0/persistence_kit/mail/__init__.py

@@ -0,0 +1,57 @@
+from importlib import import_module
+
+from persistence_kit.mail.contracts import MailSender
+from persistence_kit.mail.errors import (
+    MailConfigError,
+    MailDeliveryError,
+    MailError,
+    MailMessageError,
+    MailRecipientsRefusedError,
+    MailTemplateError,
+)
+from persistence_kit.mail.factory import build_mailer, get_mail_sender, reset_mail_sender
+from persistence_kit.mail.message import MailAddress, MailAttachment, MailMessage
+from persistence_kit.settings.mail_settings import MailBackend, MailSettings
+
+_LAZY_EXPORTS = {
+    "MemoryMailSender": ("persistence_kit.mail.memory", "MemoryMailSender"),
+    "SmtpMailSender": ("persistence_kit.mail.smtp", "SmtpMailSender"),
+    "MailTemplates": ("persistence_kit.mail.templates", "MailTemplates"),
+    "RenderedMail": ("persistence_kit.mail.templates", "RenderedMail"),
+    "Mailer": ("persistence_kit.mail.mailer", "Mailer"),
+}
+
+__all__ = [
+    "MailSender",
+    "MailAddress",
+    "MailAttachment",
+    "MailMessage",
+    "MailError",
+    "MailConfigError",
+    "MailMessageError",
+    "MailTemplateError",
+    "MailDeliveryError",
+    "MailRecipientsRefusedError",
+    "MailBackend",
+    "MailSettings",
+    "get_mail_sender",
+    "build_mailer",
+    "reset_mail_sender",
+    *_LAZY_EXPORTS,
+]
+
+
+def __getattr__(name: str):
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr_name = _LAZY_EXPORTS[name]
+    try:
+        module = import_module(module_name)
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            f"{name} requires the optional capability 'mail'. "
+            "Install it with: pip install 'persistence-kit[mail]'"
+        ) from exc
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value

persistence_kit-3.13.0/persistence_kit/mail/contracts.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from persistence_kit.mail.message import MailMessage
+
+
+class MailSender(Protocol):
+    async def send(self, message: MailMessage) -> None: ...

persistence_kit-3.13.0/persistence_kit/mail/errors.py

@@ -0,0 +1,26 @@
+class MailError(Exception):
+    """Base exception for the mail capability."""
+
+
+class MailConfigError(MailError):
+    """Raised when the mail backend is not configured correctly."""
+
+
+class MailMessageError(MailError, ValueError):
+    """Raised when a message cannot be built: no recipients, no body or unsafe header values."""
+
+
+class MailTemplateError(MailError):
+    """Raised when a mail template is missing or fails to render."""
+
+
+class MailDeliveryError(MailError):
+    """Raised when the relay cannot be reached or rejects the message."""
+
+
+class MailRecipientsRefusedError(MailDeliveryError):
+    """Raised when the relay accepted the message for some recipients and refused the rest."""
+
+    def __init__(self, refused: dict[str, tuple[int, bytes]]) -> None:
+        self.refused = refused
+        super().__init__(f"The relay refused {len(refused)} recipient(s): {', '.join(sorted(refused))}")

persistence_kit-3.13.0/persistence_kit/mail/factory.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from persistence_kit.mail.contracts import MailSender
+from persistence_kit.mail.errors import MailConfigError
+from persistence_kit.mail.message import MailAddress
+from persistence_kit.settings.mail_settings import MailBackend, MailSettings
+
+if TYPE_CHECKING:
+    from persistence_kit.mail.mailer import Mailer
+
+
+def _configured_sender(settings: MailSettings) -> MailAddress | None:
+    if not settings.mail_from_address:
+        return None
+    return MailAddress(email=settings.mail_from_address, name=settings.mail_from_name)
+
+
+@lru_cache
+def _memory_sender_cached(default_sender: MailAddress | None) -> MailSender:
+    from persistence_kit.mail.memory import MemoryMailSender
+
+    if default_sender is None:
+        return MemoryMailSender()
+    return MemoryMailSender(default_sender=default_sender)
+
+
+@lru_cache
+def _smtp_sender_cached(
+    host: str,
+    port: int,
+    starttls: bool,
+    username: str | None,
+    password: str | None,
+    timeout_seconds: float,
+    default_sender: MailAddress,
+) -> MailSender:
+    from persistence_kit.mail.smtp import SmtpMailSender
+
+    return SmtpMailSender(
+        host=host,
+        port=port,
+        starttls=starttls,
+        username=username,
+        password=password,
+        timeout_seconds=timeout_seconds,
+        default_sender=default_sender,
+    )
+
+
+def get_mail_sender(settings: MailSettings | None = None) -> MailSender:
+    """Returns the sender chosen by `MAIL_BACKEND`; `smtp` requires a host and a from address."""
+    settings = settings or MailSettings()
+    default_sender = _configured_sender(settings)
+
+    if settings.mail_backend == MailBackend.MEMORY:
+        return _memory_sender_cached(default_sender)
+
+    if settings.mail_backend == MailBackend.SMTP:
+        if not settings.mail_smtp_host:
+            raise MailConfigError("MAIL_SMTP_HOST is required when MAIL_BACKEND is smtp.")
+        if default_sender is None:
+            raise MailConfigError("MAIL_FROM_ADDRESS is required when MAIL_BACKEND is smtp.")
+        return _smtp_sender_cached(
+            settings.mail_smtp_host,
+            settings.mail_smtp_port,
+            settings.mail_smtp_starttls,
+            settings.mail_smtp_username,
+            settings.mail_smtp_password,
+            settings.mail_smtp_timeout_seconds,
+            default_sender,
+        )
+
+    backend = getattr(settings.mail_backend, "value", settings.mail_backend)
+    raise MailConfigError(f"Unsupported mail backend: '{backend}'.")
+
+
+def build_mailer(templates_dir: str | Path, settings: MailSettings | None = None) -> Mailer:
+    """A `Mailer` over the configured sender and the application's template directory."""
+    from persistence_kit.mail.mailer import Mailer
+    from persistence_kit.mail.templates import MailTemplates
+
+    return Mailer(sender=get_mail_sender(settings), templates=MailTemplates(templates_dir))
+
+
+def reset_mail_sender() -> None:
+    _memory_sender_cached.cache_clear()
+    _smtp_sender_cached.cache_clear()

persistence_kit-3.13.0/persistence_kit/mail/mailer.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+from persistence_kit.mail.contracts import MailSender
+from persistence_kit.mail.message import MailAddress, MailAttachment, MailMessage, Recipients
+from persistence_kit.mail.templates import MailTemplates
+
+logger = logging.getLogger(__name__)
+
+
+class Mailer:
+    """Composes messages from the application's templates and sends them.
+
+    `compose` raises on a broken template, so it shows up in tests. `dispatch` delivers in the
+    background: a relay failure is logged and never reaches the request that triggered it.
+    """
+
+    def __init__(self, *, sender: MailSender, templates: MailTemplates) -> None:
+        self._sender = sender
+        self._templates = templates
+        self._pending: set[asyncio.Task[None]] = set()
+
+    def compose(
+        self,
+        template: str,
+        *,
+        to: Recipients = (),
+        cc: Recipients = (),
+        bcc: Recipients = (),
+        reply_to: Recipients = (),
+        context: Mapping[str, Any] | None = None,
+        attachments: tuple[MailAttachment, ...] = (),
+        sender: str | MailAddress | None = None,
+    ) -> MailMessage:
+        rendered = self._templates.render(template, context)
+        return MailMessage(
+            subject=rendered.subject,
+            html=rendered.html,
+            text=rendered.text,
+            to=to,
+            cc=cc,
+            bcc=bcc,
+            reply_to=reply_to,
+            attachments=(*rendered.inline_images, *attachments),
+            sender=sender,
+        )
+
+    async def send(self, message: MailMessage) -> None:
+        await self._sender.send(message)
+
+    def dispatch(self, message: MailMessage) -> asyncio.Task[None]:
+        task = asyncio.create_task(self._send_logging_failures(message))
+        self._pending.add(task)
+        task.add_done_callback(self._pending.discard)
+        return task
+
+    async def wait_for_pending(self) -> None:
+        """Waits for every dispatched message, for tests and for a clean shutdown."""
+        if self._pending:
+            await asyncio.gather(*self._pending, return_exceptions=True)
+
+    async def _send_logging_failures(self, message: MailMessage) -> None:
+        try:
+            await self._sender.send(message)
+        except Exception:
+            logger.exception(
+                "mail.dispatch_failed subject=%r recipients=%d",
+                message.subject,
+                len(message.envelope_recipients),
+            )

persistence_kit-3.13.0/persistence_kit/mail/memory.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from email.message import EmailMessage
+
+from persistence_kit.mail.message import MailAddress, MailMessage
+from persistence_kit.mail.mime import build_mime_message
+
+DEFAULT_MEMORY_SENDER = MailAddress(email="no-reply@localhost.localdomain")
+
+
+class MemoryMailSender:
+    """Keeps every message in process instead of delivering it. Used by tests and local runs.
+
+    It still builds the MIME message, so a message the relay would reject fails here too.
+    """
+
+    def __init__(self, *, default_sender: MailAddress = DEFAULT_MEMORY_SENDER) -> None:
+        self._default_sender = default_sender
+        self.sent: list[MailMessage] = []
+        self.mime: list[EmailMessage] = []
+
+    async def send(self, message: MailMessage) -> None:
+        self.mime.append(build_mime_message(message, default_sender=self._default_sender))
+        self.sent.append(message)
+
+    def clear(self) -> None:
+        self.sent.clear()
+        self.mime.clear()

persistence_kit-3.13.0/persistence_kit/mail/message.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from email.utils import formataddr
+
+from persistence_kit.mail.errors import MailMessageError
+
+_LINE_BREAKS = ("\r", "\n")
+CONTENT_ID_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._@-]*")
+
+
+def _reject_line_breaks(value: str, what: str) -> None:
+    for line_break in _LINE_BREAKS:
+        if line_break in value:
+            raise MailMessageError(f"{what} cannot contain line breaks: {value!r}")
+
+
+@dataclass(frozen=True, kw_only=True)
+class MailAddress:
+    """An address with an optional display name."""
+
+    email: str
+    name: str | None = None
+
+    def __post_init__(self) -> None:
+        email = self.email.strip()
+        if not email or "@" not in email:
+            raise MailMessageError(f"Not a mail address: {self.email!r}")
+        _reject_line_breaks(email, "An address")
+        if self.name is not None:
+            _reject_line_breaks(self.name, "A display name")
+        object.__setattr__(self, "email", email)
+
+    def formatted(self) -> str:
+        return formataddr((self.name or "", self.email))
+
+
+Recipients = str | MailAddress | Iterable[str | MailAddress]
+
+
+def to_address(value: str | MailAddress) -> MailAddress:
+    if isinstance(value, MailAddress):
+        return value
+    return MailAddress(email=value)
+
+
+def to_addresses(value: Recipients | None) -> tuple[MailAddress, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, (str, MailAddress)):
+        return (to_address(value),)
+    addresses: list[MailAddress] = []
+    for item in value:
+        addresses.append(to_address(item))
+    return tuple(addresses)
+
+
+@dataclass(frozen=True, kw_only=True)
+class MailAttachment:
+    """A file sent with the message. With `content_id` it goes inline, for `<img src="cid:...">`."""
+
+    filename: str
+    content: bytes
+    content_type: str = "application/octet-stream"
+    content_id: str | None = None
+
+    def __post_init__(self) -> None:
+        _reject_line_breaks(self.filename, "An attachment name")
+        if self.content_type.count("/") != 1:
+            raise MailMessageError(f"Not a content type: {self.content_type!r}")
+        if self.content_id is not None and not CONTENT_ID_PATTERN.fullmatch(self.content_id):
+            raise MailMessageError(f"Not a content id: {self.content_id!r}")
+
+    @property
+    def inline(self) -> bool:
+        return self.content_id is not None
+
+
+@dataclass(frozen=True, kw_only=True)
+class MailMessage:
+    """One message. `to`, `cc`, `bcc` and `reply_to` take a string, an address or a list of them.
+
+    Blind copies travel in the envelope only; they never appear in the headers.
+    """
+
+    subject: str
+    to: Recipients = ()
+    cc: Recipients = ()
+    bcc: Recipients = ()
+    reply_to: Recipients = ()
+    html: str | None = None
+    text: str | None = None
+    attachments: tuple[MailAttachment, ...] = field(default_factory=tuple)
+    sender: str | MailAddress | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "to", to_addresses(self.to))
+        object.__setattr__(self, "cc", to_addresses(self.cc))
+        object.__setattr__(self, "bcc", to_addresses(self.bcc))
+        object.__setattr__(self, "reply_to", to_addresses(self.reply_to))
+        object.__setattr__(self, "attachments", tuple(self.attachments))
+        if self.sender is not None:
+            object.__setattr__(self, "sender", to_address(self.sender))
+
+        _reject_line_breaks(self.subject, "The subject")
+        if not self.to and not self.cc and not self.bcc:
+            raise MailMessageError("A message needs at least one recipient in to, cc or bcc.")
+        if not self.html and not self.text:
+            raise MailMessageError("A message needs an html or a text body.")
+        if not self.html and any(attachment.inline for attachment in self.attachments):
+            raise MailMessageError("Inline attachments need an html body.")
+
+    @property
+    def envelope_recipients(self) -> tuple[str, ...]:
+        """Every address the relay has to deliver to, blind copies included, without repeats."""
+        seen: dict[str, str] = {}
+        for address in (*self.to, *self.cc, *self.bcc):
+            seen.setdefault(address.email.lower(), address.email)
+        return tuple(seen.values())