plain.templates 0.1.0__py3-none-any.whl

plain/templates/CHANGELOG.md

@@ -0,0 +1,16 @@
+# plain-templates changelog
+
+## [0.1.0](https://github.com/dropseed/plain/releases/plain-templates@0.1.0) (2026-05-12)
+
+### What's changed
+
+- First release. `plain.templates` is now a separate package, extracted from `plain` core ([19b622a7ca](https://github.com/dropseed/plain/commit/19b622a7ca)). It owns:
+    - The Jinja2 engine, `DefaultEnvironment`, the `TEMPLATES_JINJA_ENVIRONMENT` setting
+    - `Template` and `TemplateFileMissing`
+    - `register_template_global`, `register_template_filter`, `register_template_extension`
+    - The template-rendering view bases: `TemplateView`, `FormView`, `DetailView`, `CreateView`, `UpdateView`, `DeleteView`, `ListView` at `plain.templates.views`
+    - The `{status_code}.html` error rendering wired through `plain` core's framework default exception handler (lazy import — degrades to plain text if this package isn't installed)
+
+### Upgrade instructions
+
+- Install the package and add it to `INSTALLED_PACKAGES` — see the [`plain` 0.143.0 release notes](../../../plain/plain/CHANGELOG.md) for the full migration.

plain/templates/README.md

@@ -0,0 +1,395 @@
+# plain.templates
+
+**Render HTML templates using Jinja2.**
+
+- [Overview](#overview)
+- [Template files](#template-files)
+- [Template-rendering views](#template-rendering-views)
+    - [TemplateView](#templateview)
+    - [FormView](#formview)
+    - [DetailView, CreateView, UpdateView, DeleteView, ListView](#object-views)
+- [Template context](#template-context)
+- [Built-in globals](#built-in-globals)
+- [Built-in filters](#built-in-filters)
+- [Custom globals and filters](#custom-globals-and-filters)
+- [Custom template extensions](#custom-template-extensions)
+- [Rendering templates manually](#rendering-templates-manually)
+- [Custom Jinja environment](#custom-jinja-environment)
+- [Forms](#forms)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
+
+Plain uses Jinja2 for template rendering. You can refer to the [Jinja documentation](https://jinja.palletsprojects.com/en/stable/) for all of the features available.
+
+Templates are typically used with [`TemplateView`](./views.py#TemplateView) or one of its subclasses (see [Template-rendering views](#template-rendering-views)).
+
+```python
+# app/views.py
+from plain.templates.views import TemplateView
+
+
+class ExampleView(TemplateView):
+    template_name = "example.html"
+
+    def get_template_context(self):
+        context = super().get_template_context()
+        context["message"] = "Hello, world!"
+        return context
+```
+
+```html
+<!-- app/templates/example.html -->
+{% extends "base.html" %}
+
+{% block content %}
+    <h1>{{ message }}</h1>
+{% endblock %}
+```
+
+## Template files
+
+Template files can live in two locations:
+
+1. **`app/templates/`** - Your app's templates (highest priority)
+2. **`{package}/templates/`** - Templates inside any installed package
+
+All template directories are merged together, so you can override templates from installed packages by creating a file with the same name in `app/templates/`.
+
+## Template-rendering views
+
+`plain.templates.views` ships the view classes that render templates. The base [`View`](../../../plain/plain/views/README.md) class lives in core `plain.views` and doesn't know about templates — install `plain.templates` to use any of these.
+
+### TemplateView
+
+[`TemplateView`](./views.py#TemplateView) renders a Jinja template:
+
+```python
+from plain.templates.views import TemplateView
+
+
+class ExampleView(TemplateView):
+    template_name = "example.html"
+
+    def get_template_context(self):
+        context = super().get_template_context()
+        context["message"] = "Hello, world!"
+        return context
+```
+
+For simple pages that don't need custom context, configure `TemplateView` directly in your URL routes:
+
+```python
+from plain.templates.views import TemplateView
+from plain.urls import path, Router
+
+
+class AppRouter(Router):
+    routes = [
+        path("/example/", TemplateView.as_view(template_name="example.html")),
+    ]
+```
+
+### FormView
+
+[`FormView`](./views.py#FormView) handles displaying and processing [forms](../../../plain/plain/forms/README.md). The form is automatically available in your template as `form`:
+
+```python
+from plain.templates.views import FormView
+from .forms import ExampleForm
+
+
+class ExampleView(FormView):
+    template_name = "example.html"
+    form_class = ExampleForm
+    success_url = "."
+
+    def form_valid(self, form):
+        return super().form_valid(form)
+```
+
+### Object views
+
+[`DetailView`](./views.py#DetailView), [`CreateView`](./views.py#CreateView), [`UpdateView`](./views.py#UpdateView), [`DeleteView`](./views.py#DeleteView), and [`ListView`](./views.py#ListView) provide standard CRUD scaffolding. Each requires you to implement `get_object()` or `get_objects()`:
+
+```python
+from plain.templates.views import DetailView
+
+
+class ExampleDetailView(DetailView):
+    template_name = "detail.html"
+
+    def get_object(self):
+        return MyObjectClass.query.get(
+            id=self.url_kwargs["id"],
+            user=self.request.user,
+        )
+```
+
+The single object is exposed in templates as `object`; list views expose `objects`. Set `context_object_name` for a more descriptive name.
+
+## Template context
+
+When using `TemplateView`, you pass data to templates by overriding `get_template_context()`:
+
+```python
+from plain.templates.views import TemplateView
+
+
+class ProductView(TemplateView):
+    template_name = "product.html"
+
+    def get_template_context(self):
+        context = super().get_template_context()
+        context["product"] = Product.objects.get(id=self.url_kwargs["id"])
+        context["related_products"] = Product.objects.filter(category=context["product"].category)[:5]
+        return context
+```
+
+The context is then available in your template:
+
+```html
+<h1>{{ product.name }}</h1>
+<ul>
+{% for item in related_products %}
+    <li>{{ item.name }}</li>
+{% endfor %}
+</ul>
+```
+
+## Built-in globals
+
+Plain provides several [global functions](./jinja/globals.py) available in all templates:
+
+| Global                       | Description                        |
+| ---------------------------- | ---------------------------------- |
+| `asset(path)`                | Returns the URL for a static asset |
+| `url(name, *args, **kwargs)` | Reverses a URL by name             |
+| `Paginator`                  | The Paginator class for pagination |
+| `now()`                      | Returns the current datetime       |
+| `timedelta`                  | The timedelta class for date math  |
+| `localtime(dt)`              | Converts a datetime to local time  |
+
+```html
+<link rel="stylesheet" href="{{ asset('css/style.css') }}">
+<a href="{{ url('product_detail', id=product.id) }}">View</a>
+<p>Generated at {{ now() }}</p>
+```
+
+## Built-in filters
+
+Plain includes several [filters](./jinja/filters.py) for common operations:
+
+| Filter                        | Description                          |
+| ----------------------------- | ------------------------------------ |
+| `strftime(format)`            | Formats a datetime                   |
+| `strptime(format)`            | Parses a string to datetime          |
+| `fromtimestamp(ts)`           | Creates datetime from timestamp      |
+| `fromisoformat(s)`            | Creates datetime from ISO string     |
+| `localtime(tz)`               | Converts to local timezone           |
+| `timeuntil`                   | Human-readable time until a date     |
+| `timesince`                   | Human-readable time since a date     |
+| `json_script(id)`             | Outputs JSON safely in a script tag  |
+| `islice(stop)`                | Slices iterables (useful for dicts)  |
+| `pluralize(singular, plural)` | Returns plural suffix based on count |
+
+```html
+<p>Posted {{ post.created_at|timesince }} ago</p>
+<p>{{ items|length }} item{{ items|length|pluralize }}</p>
+<p>{{ 5 }} ox{{ 5|pluralize("en") }}</p>
+{{ data|json_script("page-data") }}
+```
+
+## Custom globals and filters
+
+You can register your own globals and filters in `app/templates.py` (or `{package}/templates.py`). These files are automatically imported when the template environment loads.
+
+```python
+# app/templates.py
+from plain.templates import register_template_filter, register_template_global
+
+
+@register_template_filter
+def camel_case(value):
+    """Convert a string to CamelCase."""
+    return value.replace("_", " ").title().replace(" ", "")
+
+
+@register_template_global
+def app_version():
+    """Return the current app version."""
+    return "1.0.0"
+```
+
+Now you can use these in templates:
+
+```html
+<p>{{ "my_variable"|camel_case }}</p>  <!-- outputs: MyVariable -->
+<footer>Version {{ app_version() }}</footer>
+```
+
+You can also register non-callable values as globals by providing a name:
+
+```python
+from plain.templates import register_template_global
+
+register_template_global("1.0.0", name="APP_VERSION")
+```
+
+## Custom template extensions
+
+For more complex template features, you can create Jinja extensions. The [`InclusionTagExtension`](./jinja/extensions.py#InclusionTagExtension) base class makes it easy to create custom tags that render their own templates.
+
+```python
+# app/templates.py
+from plain.templates import register_template_extension
+from plain.templates.jinja.extensions import InclusionTagExtension
+from plain.runtime import settings
+
+
+@register_template_extension
+class AlertExtension(InclusionTagExtension):
+    tags = {"alert"}
+    template_name = "components/alert.html"
+
+    def get_context(self, context, *args, **kwargs):
+        return {
+            "message": args[0] if args else "",
+            "type": kwargs.get("type", "info"),
+        }
+```
+
+```html
+<!-- app/templates/components/alert.html -->
+<div class="alert alert-{{ type }}">{{ message }}</div>
+```
+
+```html
+<!-- Usage in any template -->
+{% alert "Something happened!" type="warning" %}
+```
+
+## Rendering templates manually
+
+You can render templates outside of views using the [`Template`](./core.py#Template) class.
+
+```python
+from plain.templates import Template
+
+html = Template("email/welcome.html").render({
+    "user_name": "Alice",
+    "activation_url": "https://example.com/activate/abc123",
+})
+```
+
+If the template file doesn't exist, a [`TemplateFileMissing`](./core.py#TemplateFileMissing) exception is raised.
+
+## Custom Jinja environment
+
+By default, Plain uses a [`DefaultEnvironment`](./jinja/environments.py#DefaultEnvironment) that configures Jinja2 with sensible defaults:
+
+- **Autoescaping** enabled for security
+- **StrictUndefined** so undefined variables raise errors
+- **Auto-reload** in debug mode
+- **Loop controls** extension (`break`, `continue`)
+- **Debug** extension
+
+You can customize the environment by creating your own class and pointing to it in settings:
+
+```python
+# app/jinja.py
+from plain.templates.jinja.environments import DefaultEnvironment
+
+
+class CustomEnvironment(DefaultEnvironment):
+    def __init__(self):
+        super().__init__()
+        # Add your customizations here
+        self.globals["CUSTOM_SETTING"] = "value"
+```
+
+```python
+# app/settings.py
+TEMPLATES_JINJA_ENVIRONMENT = "app.jinja.CustomEnvironment"
+```
+
+## FAQs
+
+#### Why am I getting "undefined variable" errors?
+
+Plain uses Jinja's `StrictUndefined` mode, which raises an error when you reference a variable that doesn't exist in the context. This helps catch typos and missing data early. Make sure you're passing all required variables in `get_template_context()`.
+
+#### Why does my template show an error about a callable?
+
+Plain's template environment prevents accidentally rendering callables (functions, methods) directly. If you see an error like "X is callable, did you forget parentheses?", you probably need to add `()` to call the function:
+
+```html
+<!-- Wrong -->
+{{ user.get_full_name }}
+
+<!-- Correct -->
+{{ user.get_full_name() }}
+```
+
+#### How do I use Jinja's loop controls?
+
+Plain enables the `loopcontrols` extension by default, so you can use `break` and `continue` in loops:
+
+```html
+{% for item in items %}
+    {% if item.skip %}
+        {% continue %}
+    {% endif %}
+    {% if item.stop %}
+        {% break %}
+    {% endif %}
+    <p>{{ item.name }}</p>
+{% endfor %}
+```
+
+#### Where can I learn more about Jinja2?
+
+The [Jinja2 documentation](https://jinja.palletsprojects.com/en/stable/) covers all the template syntax, including conditionals, loops, macros, and inheritance.
+
+## Forms
+
+Forms are rendered manually using the bound field attributes:
+
+```html
+<form method="post">
+    <div>
+        <label for="{{ form.email.html_id }}">Email</label>
+        <input
+            type="email"
+            name="{{ form.email.html_name }}"
+            id="{{ form.email.html_id }}"
+            value="{{ form.email.value }}"
+        >
+        {% for error in form.email.errors %}
+        <p>{{ error }}</p>
+        {% endfor %}
+    </div>
+    <button type="submit">Submit</button>
+</form>
+```
+
+Each bound field provides: `html_name`, `html_id`, `value`, `errors`, `field`, `initial`.
+
+## Installation
+
+Install the `plain.templates` package:
+
+```bash
+uv add plain.templates
+```
+
+Then add it to `INSTALLED_PACKAGES`:
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    "plain.templates",
+    # ...
+]
+```

plain/templates/__init__.py

@@ -0,0 +1,17 @@
+from .core import Template, TemplateFileMissing
+from .jinja import (
+    register_template_extension,
+    register_template_filter,
+    register_template_global,
+)
+
+__all__ = [
+    "Template",
+    "TemplateFileMissing",
+    # Technically these are jinja-specific,
+    # but expected to be used pretty frequently so
+    # the shorter import is handy.
+    "register_template_extension",
+    "register_template_filter",
+    "register_template_global",
+]

plain/templates/config.py

@@ -0,0 +1,6 @@
+from plain.packages import PackageConfig, register_config
+
+
+@register_config
+class Config(PackageConfig):
+    package_label = "plaintemplates"

plain/templates/core.py

@@ -0,0 +1,40 @@
+import jinja2
+from opentelemetry import trace
+from opentelemetry.semconv.attributes.code_attributes import (
+    CODE_FUNCTION_NAME,
+)
+
+from .jinja import environment
+
+tracer = trace.get_tracer("plain.templates")
+
+
+class TemplateFileMissing(Exception):
+    def __str__(self) -> str:
+        if self.args:
+            return f"Template file {self.args[0]} not found"
+        else:
+            return "Template file not found"
+
+
+class Template:
+    def __init__(self, filename: str) -> None:
+        self.filename = filename
+
+        try:
+            self._jinja_template = environment.get_template(filename)
+        except jinja2.TemplateNotFound:
+            raise TemplateFileMissing(filename)
+
+    def render(self, context: dict) -> str:
+        with tracer.start_as_current_span(
+            f"render {self.filename}",
+            kind=trace.SpanKind.INTERNAL,
+            attributes={
+                CODE_FUNCTION_NAME: f"{self.__class__.__module__}.{self.__class__.__qualname__}.render",
+                "template.filename": self.filename,
+                "template.engine": "jinja2",
+            },
+        ):
+            result = self._jinja_template.render(context)
+            return result

plain/templates/default_settings.py

@@ -0,0 +1,2 @@
+# Dotted path or callable returning a Jinja2 Environment used to render templates.
+TEMPLATES_JINJA_ENVIRONMENT: str = "plain.templates.jinja.DefaultEnvironment"

plain/templates/jinja/__init__.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from plain.packages import packages_registry
+from plain.runtime import settings
+from plain.utils.functional import LazyObject
+from plain.utils.module_loading import import_string
+
+from .environments import DefaultEnvironment, get_template_dirs
+
+
+class JinjaEnvironment(LazyObject):
+    def _setup(self) -> None:
+        environment_setting = settings.TEMPLATES_JINJA_ENVIRONMENT
+
+        if isinstance(environment_setting, str):
+            env = import_string(environment_setting)()
+        else:
+            env = environment_setting()
+
+        # We have to set _wrapped before we trigger the autoloading of "register" commands
+        self._wrapped = env
+
+        # Autoload template helpers using the registry method
+        packages_registry.autodiscover_modules("templates", include_app=True)
+
+
+environment = JinjaEnvironment()
+
+
+def register_template_extension(extension_class: type) -> type:
+    environment.add_extension(extension_class)
+    return extension_class
+
+
+def register_template_global(value: Any, name: str | None = None) -> Any:
+    """
+    Adds a global to the Jinja environment.
+
+    Can be used as a decorator on a function:
+
+            @register_template_global
+            def my_global():
+                return "Hello, world!"
+
+    Or as a function:
+
+            register_template_global("Hello, world!", name="my_global")
+    """
+    if callable(value):
+        environment.globals[name or value.__name__] = value
+    elif name:
+        environment.globals[name] = value
+    else:
+        raise ValueError("name must be provided if value is not callable")
+
+    return value
+
+
+def register_template_filter(
+    func: Callable[..., Any], name: str | None = None
+) -> Callable[..., Any]:
+    """Adds a filter to the Jinja environment."""
+    filter_name = name if name is not None else func.__name__  # ty: ignore[unresolved-attribute]
+    environment.filters[filter_name] = func
+    return func
+
+
+__all__ = [
+    "environment",
+    "DefaultEnvironment",
+    "get_template_dirs",
+    "register_template_extension",
+    "register_template_filter",
+    "register_template_global",
+]

plain/templates/jinja/environments.py

@@ -0,0 +1,64 @@
+import functools
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, StrictUndefined
+from jinja2.loaders import FileSystemLoader
+
+from plain.packages import packages_registry
+from plain.runtime import settings
+
+from .filters import default_filters
+from .globals import default_globals
+
+
+def _finalize_callable_error(obj: Any) -> Any:
+    """Prevent direct rendering of a callable (likely just forgotten ()) by raising a TypeError"""
+    if callable(obj):
+        raise TypeError(f"{obj} is callable, did you forget parentheses?")
+
+    # TODO find a way to prevent <object representation> from being rendered
+    # if obj.__class__.__str__ is object.__str__:
+    #     raise TypeError(f"{obj} does not have a __str__ method")
+
+    return obj
+
+
+def get_template_dirs() -> tuple[Path, ...]:
+    jinja_templates = Path(__file__).parent / "templates"
+    app_templates = settings.path.parent / "templates"
+    return (jinja_templates, app_templates) + _get_app_template_dirs()
+
+
+@functools.lru_cache
+def _get_app_template_dirs() -> tuple[Path, ...]:
+    """
+    Return an iterable of paths of directories to load app templates from.
+
+    dirname is the name of the subdirectory containing templates inside
+    installed applications.
+    """
+    dirname = "templates"
+    template_dirs = [
+        Path(package_config.path) / dirname
+        for package_config in packages_registry.get_package_configs()
+        if package_config.path and (Path(package_config.path) / dirname).is_dir()
+    ]
+    # Immutable return value because it will be cached and shared by callers.
+    return tuple(template_dirs)
+
+
+class DefaultEnvironment(Environment):
+    def __init__(self):
+        super().__init__(
+            loader=FileSystemLoader(get_template_dirs()),
+            autoescape=True,
+            auto_reload=settings.DEBUG,
+            undefined=StrictUndefined,
+            finalize=_finalize_callable_error,
+            extensions=["jinja2.ext.loopcontrols", "jinja2.ext.debug"],
+        )
+
+        # Load the top-level defaults
+        self.globals.update(default_globals)  # ty: ignore[no-matching-overload]
+        self.filters.update(default_filters)

plain/templates/jinja/extensions.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+from jinja2 import nodes
+from jinja2.ext import Extension
+from jinja2.runtime import Context
+
+
+class InclusionTagExtension(Extension):
+    """Intended to be subclassed"""
+
+    # tags = {'inclusion_tag'}
+    tags: set[str]
+    template_name: str
+
+    def parse(self, parser: Any) -> nodes.Node:
+        lineno = next(parser.stream).lineno
+        args: list[nodes.Expr] = [
+            nodes.DerivedContextReference(),
+        ]
+        kwargs = []
+        while parser.stream.current.type != "block_end":
+            if parser.stream.current.type == "name":
+                key = parser.stream.current.value
+                parser.stream.skip()
+                parser.stream.expect("assign")
+                value = parser.parse_expression()
+                kwargs.append(nodes.Keyword(key, value))
+            else:
+                args.append(parser.parse_expression())
+
+        call = self.call_method("_render", args=args, kwargs=kwargs, lineno=lineno)
+        return nodes.CallBlock(call, [], [], []).set_lineno(lineno)
+
+    def _render(self, context: Context, *args: Any, **kwargs: Any) -> str:
+        render_context = self.get_context(context, *args, **kwargs)
+        template = self.environment.get_template(self.template_name)
+        return template.render(render_context)
+
+    def get_context(
+        self, context: Context, *args: Any, **kwargs: Any
+    ) -> Context | dict[str, Any]:
+        raise NotImplementedError(
+            "You need to implement the `get_context` method in your subclass."
+        )