vintasend-managed-templates 3.0.0__tar.gz

vintasend_managed_templates-3.0.0/PKG-INFO

@@ -0,0 +1,556 @@
+Metadata-Version: 2.4
+Name: vintasend-managed-templates
+Version: 3.0.0
+Summary: Starting point for a new vintasend-* implementation package: one TODO stub per seam, ready to clone.
+License-Expression: MIT
+Author: Hugo Bessa
+Author-email: hugo@vinta.com.br
+Requires-Python: >=3.10,<3.15
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: typing-extensions (>=4.10.0)
+Requires-Dist: vintasend (==3.0.0)
+Description-Content-Type: text/markdown
+
+# vintasend-managed-templates
+
+Database-backed notification templates for
+[vintasend](https://github.com/vintasoftware/vintasend): versioning, a
+draft/active/inactive/archived lifecycle with an audit trail, tags, and filtering — all on top of
+a storage seam you (or a ready-made package) implement.
+
+A regular vintasend template renderer reads templates from wherever its engine looks, which is
+usually files on disk. That means every copy change is a deploy. This package moves the templates
+into a data store so someone who is not a developer can edit them, keeps every edit as a new
+version, and lets you publish a version deliberately instead of the moment it is saved.
+
+It is storage-agnostic on its own — it defines the interface, not the database. Pair it with a
+manager backend such as
+[vintasend-django-templates-manager](https://github.com/vintasoftware/vintasend-django-templates-manager/),
+or implement `BaseTemplateManagerBackend` yourself.
+
+## Install
+
+```bash
+poetry add vintasend-managed-templates
+# or
+pip install vintasend-managed-templates
+```
+
+Python 3.10–3.14. The only dependencies are `vintasend` itself and `typing-extensions`.
+
+## The pieces
+
+| Piece | What it is |
+|---|---|
+| `BaseTemplateManagerBackend` | The storage seam. An ABC covering template CRUD, versions, status history, tags, filtering, and pagination. |
+| `ManagedTemplateService` | The API you call. Wraps a backend and a renderer with version resolution, status-transition rules, filter validation, and tag normalization. |
+| `ManagedTemplateEmailRenderer` / `ManagedTemplateSMSRenderer` | A vintasend template renderer that wraps *another* renderer and feeds it a stored template instead of a template path. |
+| `composition.TemplateComposer` | Resolves template inheritance and inclusion against the store, before the engine runs. |
+| `tags.slugify_tag` / `next_available_slug` | The shared slug rules, so every backend derives the same slug from the same text. |
+| `dataclasses`, `constants`, `filters`, `exceptions` | The wire types: `ManagedTemplate`, `ManagedTemplateTag`, the two status enums, the filter TypedDicts, and the error hierarchy. |
+
+Everything here is synchronous. There is no AsyncIO twin, because the seams it composes
+(`BaseTemplateManagerBackend` and vintasend's template renderer seam) are both synchronous.
+
+## Quick start
+
+```python
+from vintasend_managed_templates.dataclasses import ManagedTemplateCreateInput
+from vintasend_managed_templates.managed_template_renderer import ManagedTemplateEmailRenderer
+from vintasend_managed_templates.managed_template_service import ManagedTemplateService
+
+manager_backend = MyTemplateManagerBackend()          # any BaseTemplateManagerBackend
+renderer = ManagedTemplateEmailRenderer(
+    manager_backend,
+    inner_renderer,                                    # any vintasend email renderer
+)
+service = ManagedTemplateService(manager_backend, renderer)
+
+template = service.create_template(
+    ManagedTemplateCreateInput(
+        name="Welcome email",
+        description="Sent right after signup",
+        key="welcome",                                 # what notifications reference
+        template_managed_backend="django",             # which manager backend stores it
+        template_body="<p>Hi {{ name }}, welcome!</p>",
+        template_subject="Welcome aboard",
+        template_preheader=None,
+        tenant=None,
+        tags=["onboarding", "Black Friday"],
+    )
+)
+
+service.activate("welcome", changed_by="hugo@example.com")
+```
+
+To send through it, hand the wrapping renderer to your adapter and set the notification's
+`body_template` to the template **key** instead of a path:
+
+```python
+from vintasend.services.notification_service import NotificationService
+
+notification_service = NotificationService(
+    notification_adapters=[MyEmailAdapter(template_renderer=renderer, backend=notification_backend)],
+    notification_backend=notification_backend,
+)
+
+notification_service.create_notification(
+    user_id=user.id,
+    notification_type="EMAIL",
+    title="Welcome",
+    body_template="welcome",   # a managed template key, not a file path
+    context_name="welcome_context",
+    context_kwargs={"user_id": user.id},
+    send_after=None,
+    subject_template="",
+    preheader_template="",
+)
+```
+
+Pass the renderer as a live instance rather than as a dotted import string: it takes a backend and
+an inner renderer as constructor arguments, which a string path cannot supply.
+
+Nothing else about creating or sending notifications changes.
+
+### What the inner renderer has to do
+
+`ManagedTemplateRenderer` looks the template up, builds an `EmailTemplateContent` (or a
+`TemplateContent` for SMS) out of the stored strings, and calls the inner renderer's
+`render_from_template_content`. So the inner renderer receives **template source in the
+`body_template` field**, where it normally expects a name a loader can resolve.
+
+Renderers that resolve names through a loader — `JinjaTemplatedEmailRenderer`,
+`DjangoTemplatedEmailRenderer` — need a loader that will accept source. For Jinja that is one
+line:
+
+```python
+from jinja2 import Environment, FunctionLoader
+from vintasend_jinja.services.notification_template_renderers.jinja_templated_email_renderer import (
+    JinjaTemplatedEmailRenderer,
+)
+
+inner_renderer = JinjaTemplatedEmailRenderer(Environment(loader=FunctionLoader(lambda source: source)))
+```
+
+A renderer written to compile source directly needs no such setup.
+
+## Composition: bases, blocks and includes
+
+A file-based renderer gets composition for free. Django's `{% extends %}` and Jinja's
+`{% include %}` hand a *name* to a loader, and a loader reads files — so the header, the footer and
+the wrapper every email shares live in one file that every other file points at.
+
+Managed templates are not files. They reach the engine as source, so a loader has nothing to
+resolve and those tags have nothing to load. Without composition the shared chrome would have to be
+pasted into every row in the store, and changing the footer would mean editing all of them.
+
+This package resolves its own set of tags **before** the engine sees anything. What the engine
+receives is one flat string with no `managed_*` tag left in it; its own syntax is untouched.
+
+```python
+service.create_template(ManagedTemplateCreateInput(
+    name="Base email", description="The wrapper every email uses", key="base-email",
+    template_managed_backend="django",
+    template_body=(
+        "<html>\n"
+        "  <body>\n"
+        "    {% managed_block header %}<h1>Acme</h1>{% managed_endblock %}\n"
+        "    {% managed_children %}\n"
+        "    {% managed_include \"footer\" %}\n"
+        "  </body>\n"
+        "</html>"
+    ),
+    template_subject="[Acme] {% managed_children %}",
+    template_preheader=None, tenant=None,
+))
+
+service.create_template(ManagedTemplateCreateInput(
+    name="Welcome email", description="Sent right after signup", key="welcome",
+    template_managed_backend="django",
+    template_body=(
+        "{% managed_extends \"base-email\" %}\n"
+        "{% managed_block header %}<h1>Welcome!</h1>{% managed_endblock %}\n"
+        "<p>Hi {{ name }}, welcome aboard.</p>"
+    ),
+    template_subject="{% managed_extends \"base-email\" %}Welcome aboard",
+    template_preheader=None, tenant=None,
+))
+```
+
+`welcome` now renders inside the base, with its own header and the shared footer, and its subject
+comes out as `[Acme] Welcome aboard`. `{{ name }}` is never looked at — the context is the engine's
+business.
+
+### The tags
+
+| Tag | What it does |
+|---|---|
+| `{% managed_extends "key" %}` | This template is a child of `key`. At most one per template, never inside a block. Pin the parent with `version=2`. |
+| `{% managed_children %}` | In a base: where the child's content goes. Rendered with no child, the hole is simply empty. |
+| `{% managed_block name %}…{% managed_endblock %}` | A named region a child may replace. Unreplaced, it renders what it was declared with. Blocks may nest. |
+| `{% managed_super %}` | Inside a child's block: the content it is overriding. Chains through as many levels of inheritance as there are. |
+| `{% managed_include "key" %}` | Splice another template in here. It is composed in full first, so an include may itself extend and include. Pins the same way: `version=7`. |
+
+Everything a child writes **outside** a block is its children content, and it lands in the base's
+`{% managed_children %}`. So a child can both fill the hole and override named regions — which is
+the one difference from Django, where content outside a block in a child template is discarded.
+
+The `managed_` prefix is reserved: an unknown `{% managed_something %}` is an error rather than
+text passed through, so a typo surfaces at edit time instead of shipping. Change the prefix by
+handing the renderer or the service its own composer:
+
+```python
+from vintasend_managed_templates.composition import TemplateComposer
+
+composer = TemplateComposer.from_backend(manager_backend, tag_prefix="tpl_")
+renderer = ManagedTemplateEmailRenderer(manager_backend, inner_renderer, composer=composer)
+```
+
+### One field at a time
+
+A template carries three sources — body, subject and preheader — and each composes against the
+**same field** of the template it references. A child's body extends the base's body; its subject
+extends the base's subject. So a base can define a subject prefix and a body wrapper at once, and
+neither leaks into the other. A field the base leaves empty composes to nothing rather than to an
+error.
+
+### Whitespace
+
+A structural tag (`extends`, `block`, `endblock`) alone on its line is taken out *with* the line,
+so a layout written across several lines does not compose into one padded with blank ones. The
+placeholder tags (`children`, `include`, `super`) are never line-trimmed: what replaces them lands
+exactly where the tag stood, indentation and all.
+
+### Abstract templates
+
+A template is *abstract* when it declares a `{% managed_children %}` hole, or declares blocks
+without extending anything — a layout meant to be built on rather than sent. That is a fact about
+the source, so it follows the template as it is edited: a template becomes abstract the moment
+someone writes the hole into it and stops being abstract the moment they take it out.
+
+**The check** recomputes from the source every time, which makes it the authority:
+
+```python
+service.is_abstract(base)      # True
+service.is_abstract(welcome)   # False
+```
+
+**The flag** is that same answer, denormalized onto the template so it can be queried:
+
+```python
+base.is_abstract                                          # True -- stored, not recomputed
+service.get_filtered_templates({"is_abstract": False})    # every sendable template
+```
+
+Filtering is the reason the flag exists. Without it, a picker that has to leave the bases out would
+read and parse every row in the store to draw one page. Nobody writes the flag — there is no field
+for it on either write input — because a stored copy that disagreed with the source would be a lie
+a filter goes on repeating. It is a **backend's job to derive it on every write** with
+`composition.is_abstract`; see [Implementing a manager backend](#implementing-a-manager-backend).
+
+Reach for the check when the flag cannot be trusted: a template edited in memory since it was read,
+or one written before its backend maintained the column.
+
+Composing an abstract template directly is allowed and gives you the layout with an empty hole.
+Neither the check nor the flag refuses anything — keeping bases out of a picker is the host's call.
+
+### Versions
+
+A reference with no version resolves the same way any other read does: to whatever version that key
+currently is. Pin it when a template must keep composing against an exact parent — re-rendering an
+old notification resolves the child's version explicitly, but its unpinned bases still resolve to
+today's.
+
+`version=N` is the only spelling, on both tags that take a reference:
+
+```
+{% managed_extends "base-email" version=2 %}
+{% managed_include "footer" version=7 %}
+```
+
+Nothing inside the quoted key is interpreted, so a key is only ever a key — a template genuinely
+named `base-email[v2]` is referenced exactly as written, with no escaping and no special case.
+
+### Checking a template before it ships
+
+Composition failures are this package's, not the engine's, so nothing downstream can report them.
+Catch them where someone can still fix them:
+
+```python
+service.validate_composition(template)     # raises exactly what rendering would have
+service.get_composed_template("welcome")   # what the engine will actually receive
+service.get_template_references(template)  # the bases and fragments it names, unresolved
+```
+
+| Exception | Raised when |
+|---|---|
+| `ManagedTemplateCompositionSyntaxError` | A tag is malformed, unknown, or unbalanced |
+| `ManagedTemplateCompositionReferenceError` | A base or fragment does not exist (also a `ManagedTemplateNotFoundError`) |
+| `ManagedTemplateCompositionCycleError` | The references loop |
+| `ManagedTemplateCompositionDepthError` | The chain runs past the composer's `max_depth` (25 by default) |
+
+All four subclass `ManagedTemplateCompositionError`.
+
+### Turning it off
+
+Composition is on by default. A store that predates it and holds `managed_`-prefixed text meant to
+reach the engine verbatim can opt out:
+
+```python
+renderer = ManagedTemplateEmailRenderer(manager_backend, inner_renderer, compose_templates=False)
+service = ManagedTemplateService(manager_backend, renderer, compose_templates=False)
+```
+
+Reads are never composed either way: `get_template` hands back exactly what is stored, which is
+what an editing UI needs. `get_composed_template` is the explicit way to ask for the assembled form.
+
+## Templates and versions
+
+Templates are **versioned, never edited in place**. `update_template` copies the latest version
+forward, applies the non-`None` fields of the input, and returns the new version — so a published
+version's body can never change under a notification that already referenced it.
+
+```python
+from vintasend_managed_templates.dataclasses import ManagedTemplateUpdateInput
+
+service.update_template("welcome", ManagedTemplateUpdateInput(
+    name=None,                       # None leaves the field as the previous version had it
+    description=None,
+    template_body="<p>Hi {{ name }}, welcome aboard!</p>",
+    template_subject=None,
+    template_preheader=None,
+    tags=None,                       # None carries tags forward; [] clears them
+))
+
+service.get_template("welcome")            # latest version
+service.get_template("welcome", version=1) # a specific one
+service.get_template_versions("welcome")   # every version, newest first
+```
+
+`version=None` means "the latest version of this key" everywhere in the service — reads, status
+changes, tagging, and rendering — so callers only deal with version numbers when they actually
+want a specific one.
+
+## Statuses
+
+A version moves through `DRAFT → ACTIVE → INACTIVE → ARCHIVED`, and every move is written to the
+backend's audit trail:
+
+```python
+service.activate("welcome", changed_by="hugo@example.com")
+service.deactivate("welcome")
+service.archive("welcome", version=1)
+service.get_status_history("welcome")      # newest change first
+service.can_transition_to(template, ManagedTemplateStatus.ACTIVE)
+```
+
+The default transition table:
+
+| From | May move to |
+|---|---|
+| `DRAFT` | `ACTIVE`, `ARCHIVED` |
+| `ACTIVE` | `INACTIVE`, `ARCHIVED` |
+| `INACTIVE` | `ACTIVE`, `ARCHIVED` |
+| `ARCHIVED` | — terminal |
+
+Anything else raises `ManagedTemplateStatusTransitionError`. Setting a version to the status it
+already holds is a no-op: no history entry, no error. Override `ALLOWED_STATUS_TRANSITIONS` on a
+subclass for a different lifecycle, or pass `validate_status_transitions=False` to leave the
+ordering entirely to your application.
+
+Two things the service deliberately does *not* decide for you:
+
+* **A key may have several `ACTIVE` versions at once.** Activating one does not deactivate the
+  others; choosing which active version wins at render time is the host's call.
+* **`changed_by` is passed through untouched, `None` included.** Attribution is never required.
+
+## Tags
+
+Tags are many-to-many with template *versions* and are identified by a slug derived from the text
+someone typed. Slugging lives in `vintasend_managed_templates.tags` rather than in a backend, so a
+Django store and a SQLAlchemy store agree on what `Promoção` slugs to. Every call that takes a slug
+also accepts the original text.
+
+```python
+service.add_template_tags("welcome", ["Black Friday"])   # creates the tag if it is new
+service.remove_template_tags("welcome", ["black-friday"])
+service.set_template_tags("welcome", ["onboarding"])     # replaces; [] clears
+service.get_templates_by_tags(["onboarding", "email"], match_all=False)
+service.get_active_tags()                                # what a tag picker should show
+```
+
+Retagging **edits the version in place** instead of creating one. Tags are how a template is
+found, not part of what it renders, so relabelling for findability does not spawn a version and
+drop it back to `DRAFT`.
+
+Archiving a tag (`archive_tag` / `restore_tag`) takes it out of the pickers but keeps every link:
+filtering by an archived tag still returns the templates carrying it. `delete_tag` is the
+irreversible one — it removes the label from the templates too.
+
+Text with nothing sluggable in it (`"  "`, `"!!!"`) raises `ManagedTemplateInvalidTagError` at the
+call site, rather than becoming a tag no filter can ever name.
+
+## Filtering and pagination
+
+Filters are plain dicts, typed by the TypedDicts in `filters.py`, and compose with `and` / `or` /
+`not`:
+
+```python
+service.get_filtered_templates({
+    "and": [
+        {"status": {"lookup": "in", "value": [ManagedTemplateStatus.ACTIVE]}},
+        {"name": {"lookup": "includes", "value": "welcome", "case_sensitive": False}},
+        {"includes_any_of_tags": ["onboarding", "transactional"]},
+        {"created_at_range": {"from": datetime(2026, 1, 1)}},
+    ]
+})
+
+service.get_paginated_filtered_templates(filters, page=1, page_size=20)  # page is 1-indexed
+```
+
+Fields: `name`, `description`, `key`, `version`, `template_managed_backend`, `status`,
+`created_at_range`, `updated_at_range`, `includes_all_tags`, `includes_any_of_tags`,
+`most_recent_active_version`. String lookups are `exact` / `starts_with` / `ends_with` /
+`includes`; numeric ones are `gt` / `gte` / `lt` / `lte`.
+
+### One row per key: `most_recent_active_version`
+
+The store holds a row per *version*, so an unfiltered read shows a template once for every
+version it has ever had. `most_recent_active_version` collapses that to one row per key — the
+highest-numbered `ACTIVE` or `DRAFT` version, which is what is live plus the draft on its way to
+replacing it. A key whose versions are all `INACTIVE` or `ARCHIVED` has no current version and
+drops out.
+
+```python
+service.get_all_templates()                          # one row per key — the current version
+service.get_all_templates(include_all_versions=True) # every version of every key
+service.get_paginated_templates(page=1, page_size=20)              # same default
+service.get_filtered_templates({"most_recent_active_version": True})  # the filter itself
+```
+
+**The two listing methods apply it by default**; pass `include_all_versions=True` for the raw
+read. `get_filtered_templates` and `get_paginated_filtered_templates` do *not* add it — a filter
+means what it says — so name the field yourself when a filtered listing should be one row per key
+too. `False` is the exact complement (every other row, retired keys included), the same set
+`{"not": {"most_recent_active_version": True}}` returns.
+
+Unlike every other field, this one is answered against the whole key rather than against the row
+being tested, so a backend evaluates it with a subquery over the key's other versions.
+
+`validate_filter` runs before every filtered read and raises `ManagedTemplateInvalidFilterError`
+for a typo'd field name, an `and`/`or` that is not a non-empty list, a logical group with sibling
+keys, a tag filter given as a bare string (which would otherwise be iterated character by
+character and silently match nothing), or a non-boolean `most_recent_active_version` (the string
+`"false"` is truthy, so it would ask for exactly what the caller meant to switch off). Lookup
+*values* stay the backend's authority.
+
+The empty-collection rules follow Python's own `all()` / `any()`: an empty `includes_all_tags`
+constrains nothing, an empty `includes_any_of_tags` matches nothing.
+
+## Rendering a specific version
+
+Which version of a template a notification renders is decided in this order:
+
+1. an explicit `version=` argument to `service.render()`,
+2. the notification's own `requested_template_version`,
+3. whatever version the backend considers current.
+
+```python
+service.render(notification, context)                 # the notification's pin, or the latest
+service.render(notification, context, version=3)      # preview v3 regardless of the pin
+service.render_template(notification, template, context)   # a template already in hand
+```
+
+The argument is for rendering a version the notification is *not* pinned to -- previewing an
+unpublished draft, or reproducing what an old notification looked like. Leave it off and you get
+what a real send would produce.
+
+### Pinning a notification to a version
+
+`ManagedTemplateRenderer` reads `requested_template_version` off the notification, so a
+notification recorded against v3 renders v3 however many versions follow. That field is
+vintasend's, not this package's -- see
+[Template Version Pinning](https://github.com/vintasoftware/vintasend#template-version-pinning)
+-- and this package is what makes it mean anything:
+
+```python
+notification_service.create_notification(
+    ...,
+    body_template="welcome",           # the template key
+    requested_template_version=3,      # render v3, now and forever
+)
+
+# Or pin to whatever version is current at this moment, without naming it:
+notification_service.create_notification(..., pin_template_versions=True)
+
+# The same, as the default for every call on the service:
+notification_service = NotificationService(..., pin_template_versions=True)
+```
+
+With `pin_template_versions=True`, the service asks this package's renderer for the current
+version through `get_latest_template_version()`, which resolves it the same way `get_template(key)`
+does. A key with nothing behind it answers `None` and the notification is created unpinned, rather
+than failing the creation over a template that may well exist by the time it is sent.
+
+Whichever version renders is reported back on the send input as `template_version`, so vintasend
+can store it as `used_template_version`. For an unpinned notification that is the only record of
+which version went out, since the template has moved on by the time anyone asks.
+
+## Implementing a manager backend
+
+Subclass `BaseTemplateManagerBackend` and implement every abstract method. It splits into four
+groups:
+
+* **Versions** — `create_template`, `get_template`, `update_template`, `delete_template`
+* **Statuses** — `create_template_status_update`, `get_template_status_history`
+* **Tags** — `get_or_create_tags`, `create_tag`, `get_tag`, `update_tag`, `set_tag_status`,
+  `delete_tag`, `get_tags`, `get_template_tags`, `set_template_tags`
+* **Queries** — `get_all_templates`, `get_templates_by_status`, `get_filtered_templates`,
+  `get_paginated_templates`, `get_paginated_filtered_templates`
+
+What a backend owns, beyond storage: assigning version numbers, deriving tag slugs with
+`slugify_tag` and keeping them unique with `next_available_slug`, deriving `is_abstract` with
+`composition.is_abstract` on every write that touches a source, and translating the filter dicts
+into its own query language.
+
+`is_abstract` is the one easy to miss, because no method is named for it. It is a denormalization
+of the template's own source, kept so the `is_abstract` filter can be a column lookup instead of a
+full-store parse, and neither write input carries it. A backend that never sets it reports every
+template as concrete and that filter quietly stops working.
+
+`tests/fakes.py` in this repo has `InMemoryTemplateManagerBackend`, a complete, dependency-free
+implementation of the seam — the shortest readable reference for what each method owes its caller.
+The suite drives it end to end rather than mocking it, so it is a real implementation, not a stub.
+
+### Exceptions
+
+All of them subclass `ManagedTemplateError`:
+
+| Exception | Raised when |
+|---|---|
+| `ManagedTemplateNotFoundError` | The key, or that version of it, does not exist |
+| `ManagedTemplateInvalidFilterError` | A filter is malformed or names an unknown field |
+| `ManagedTemplateStatusTransitionError` | The status move is not allowed from the current status |
+| `ManagedTemplateChangeUserNotFoundError` | An update names a `changed_by` user that does not exist |
+| `ManagedTemplateTagNotFoundError` | No tag has that slug |
+| `ManagedTemplateTagAlreadyExistsError` | `create_tag` collides with an existing slug |
+| `ManagedTemplateInvalidTagError` | A tag's text has nothing that can be slugified |
+| `ManagedTemplateCompositionError` | A template could not be assembled -- see [Composition](#composition-bases-blocks-and-includes) for its four subclasses |
+
+## Development
+
+```bash
+poetry install
+poetry run pytest          # coverage is on by default and fails the run below 90%
+poetry run ruff check
+poetry run mypy
+poetry run tox             # the full 3.10–3.14 matrix
+```
+
+The suite runs fully offline against the in-memory backend — no database, no services.
+