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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: persistence-kit
-Version: 3.13.0
+Version: 3.14.0
 Summary: Reusable persistence and repository toolkit
 License: MIT
 License-File: LICENSE
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Database
 Classifier: Typing :: Typed
 Provides-Extra: all
@@ -358,10 +359,24 @@ message = mailer.compose(
 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.
+A template is a folder in the app's directory, `user_roles_changed/`, with
+`subject.txt` (required) and `body.html` or `body.txt` (at least one). The same
+files can also live loose in the directory as `user_roles_changed.subject.txt`,
+`user_roles_changed.html` and `user_roles_changed.txt`; the folder wins when both
+exist. They are Jinja2, so a layout can be shared with `{% extends "shared/layout.html" %}`,
+resolved from the directory root. HTML is autoescaped, and a variable missing from
+the context fails instead of rendering blank.
+
+```text
+templates/mail/
+  shared/layout.html
+  images/logo.png
+  user_roles_changed/
+    subject.txt
+    body.html
+    body.txt
+    sample.json
+```
 
 `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.
@@ -379,8 +394,8 @@ remote images are blocked. `compose` adds it on its own; a missing file or one t
 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
+A template can carry a fourth file, `sample.json` (`user_roles_changed.sample.json`
+when loose), 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:
 
@@ -571,7 +586,7 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **621 tests passing** (version 3.13.0). Async tests use
+Current baseline: **627 tests passing** (version 3.14.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

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

@@ -310,10 +310,24 @@ message = mailer.compose(
 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.
+A template is a folder in the app's directory, `user_roles_changed/`, with
+`subject.txt` (required) and `body.html` or `body.txt` (at least one). The same
+files can also live loose in the directory as `user_roles_changed.subject.txt`,
+`user_roles_changed.html` and `user_roles_changed.txt`; the folder wins when both
+exist. They are Jinja2, so a layout can be shared with `{% extends "shared/layout.html" %}`,
+resolved from the directory root. HTML is autoescaped, and a variable missing from
+the context fails instead of rendering blank.
+
+```text
+templates/mail/
+  shared/layout.html
+  images/logo.png
+  user_roles_changed/
+    subject.txt
+    body.html
+    body.txt
+    sample.json
+```
 
 `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.
@@ -331,8 +345,8 @@ remote images are blocked. `compose` adds it on its own; a missing file or one t
 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
+A template can carry a fourth file, `sample.json` (`user_roles_changed.sample.json`
+when loose), 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:
 
@@ -523,7 +537,7 @@ poetry install --with dev --all-extras
 poetry run pytest -q
 ```
 
-Current baseline: **621 tests passing** (version 3.13.0). Async tests use
+Current baseline: **627 tests passing** (version 3.14.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

{persistence_kit-3.13.0 → persistence_kit-3.14.0}/persistence_kit/mail/templates.py

@@ -24,6 +24,10 @@ SUBJECT_SUFFIX = ".subject.txt"
 HTML_SUFFIX = ".html"
 TEXT_SUFFIX = ".txt"
 SAMPLE_SUFFIX = ".sample.json"
+FOLDER_SUBJECT = "subject.txt"
+FOLDER_HTML = "body.html"
+FOLDER_TEXT = "body.txt"
+FOLDER_SAMPLE = "sample.json"
 IMAGES_DIRECTORY = "images"
 CID_SOURCE = re.compile(r"""\bsrc\s*=\s*["']cid:([^"']+)["']""", re.IGNORECASE)
 
@@ -36,12 +40,21 @@ class RenderedMail:
     inline_images: tuple[MailAttachment, ...] = ()
 
 
+@dataclass(frozen=True, kw_only=True)
+class _TemplateFiles:
+    subject: str
+    html: str
+    text: str
+    sample: str
+
+
 class MailTemplates:
     """Renders the templates of the application that sends; the kit ships none of its own.
 
-    A template `name` is up to three files in `directory`: `name.subject.txt` (required) and
-    `name.html` or `name.txt` (at least one). HTML is autoescaped, subject and text are not.
-    An optional `name.sample.json` holds an example context for previews and tests.
+    A template `name` is a folder `name/` with `subject.txt` (required) and `body.html` or
+    `body.txt` (at least one), or the same files loose in `directory` as `name.subject.txt`,
+    `name.html` and `name.txt`. HTML is autoescaped, subject and text are not. An optional
+    `sample.json` (`name.sample.json` when loose) holds an example context for previews and tests.
     Every `src="cid:file.png"` in the HTML embeds `images/file.png` in the message.
     """
 
@@ -58,15 +71,14 @@ class MailTemplates:
 
     def render(self, name: str, context: Mapping[str, Any] | None = None) -> RenderedMail:
         values = dict(context or {})
-        subject = self._render_file(f"{name}{SUBJECT_SUFFIX}", values)
+        files = self._files(name)
+        subject = self._render_file(files.subject, values)
         if subject is None:
-            raise MailTemplateError(f"Template '{name}' has no {name}{SUBJECT_SUFFIX}.")
-        html = self._render_file(f"{name}{HTML_SUFFIX}", values)
-        text = self._render_file(f"{name}{TEXT_SUFFIX}", values)
+            raise MailTemplateError(f"Template '{name}' has no {files.subject}.")
+        html = self._render_file(files.html, values)
+        text = self._render_file(files.text, values)
         if html is None and text is None:
-            raise MailTemplateError(
-                f"Template '{name}' needs {name}{HTML_SUFFIX} or {name}{TEXT_SUFFIX}."
-            )
+            raise MailTemplateError(f"Template '{name}' needs {files.html} or {files.text}.")
         return RenderedMail(
             subject=" ".join(subject.split()),
             html=html,
@@ -76,23 +88,41 @@ class MailTemplates:
 
     def names(self) -> list[str]:
         """Every template in the directory, identified by its subject file."""
-        return sorted(
+        loose = (
             path.name.removesuffix(SUBJECT_SUFFIX)
             for path in self._directory.glob(f"*{SUBJECT_SUFFIX}")
         )
+        folders = (path.parent.name for path in self._directory.glob(f"*/{FOLDER_SUBJECT}"))
+        return sorted({*loose, *folders})
 
     def sample_context(self, name: str) -> dict[str, Any]:
-        path = self._directory / f"{name}{SAMPLE_SUFFIX}"
+        relative = self._files(name).sample
+        path = self._directory / relative
         if not path.is_file():
-            raise MailTemplateError(f"Template '{name}' has no {name}{SAMPLE_SUFFIX}.")
+            raise MailTemplateError(f"Template '{name}' has no {relative}.")
         try:
             sample = json.loads(path.read_text(encoding="utf-8"))
         except json.JSONDecodeError as exc:
-            raise MailTemplateError(f"{path.name} is not valid JSON: {exc}") from exc
+            raise MailTemplateError(f"{relative} is not valid JSON: {exc}") from exc
         if not isinstance(sample, dict):
-            raise MailTemplateError(f"{path.name} must hold a JSON object.")
+            raise MailTemplateError(f"{relative} must hold a JSON object.")
         return sample
 
+    def _files(self, name: str) -> _TemplateFiles:
+        if (self._directory / name).is_dir():
+            return _TemplateFiles(
+                subject=f"{name}/{FOLDER_SUBJECT}",
+                html=f"{name}/{FOLDER_HTML}",
+                text=f"{name}/{FOLDER_TEXT}",
+                sample=f"{name}/{FOLDER_SAMPLE}",
+            )
+        return _TemplateFiles(
+            subject=f"{name}{SUBJECT_SUFFIX}",
+            html=f"{name}{HTML_SUFFIX}",
+            text=f"{name}{TEXT_SUFFIX}",
+            sample=f"{name}{SAMPLE_SUFFIX}",
+        )
+
     def _inline_images(self, name: str, html: str | None) -> tuple[MailAttachment, ...]:
         if html is None:
             return ()

{persistence_kit-3.13.0 → persistence_kit-3.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "persistence-kit"
-version = "3.13.0"
+version = "3.14.0"
 description = "Reusable persistence and repository toolkit"
 authors = ["Andres Felipe Serrano Barrios <andresfserrano1@gmail.com>"]
 readme = "README.md"