plain 0.66.0__py3-none-any.whl → 0.101.2__py3-none-any.whl

plain/templates/README.md

@@ -1,19 +1,27 @@
 # Templates
 
-**Render HTML templates using Jinja.**
+**Render HTML templates using Jinja2.**
 
 - [Overview](#overview)
 - [Template files](#template-files)
-- [Extending Jinja](#extending-jinja)
+- [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)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-Plain uses Jinja2 for template rendering. You can refer to the [Jinja documentation](https://jinja.palletsprojects.com/en/stable/api/) for all of the features available.
+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.
 
-In general, templates are used in combination with `TemplateView` or a more specific subclass of it.
+Templates are typically used with `TemplateView` or one of its subclasses.
 
 ```python
+# app/views.py
 from plain.views import TemplateView
 
 
@@ -27,7 +35,7 @@ class ExampleView(TemplateView):
 ```
 
 ```html
-<!-- example.html -->
+<!-- app/templates/example.html -->
 {% extends "base.html" %}
 
 {% block content %}
@@ -37,50 +45,233 @@ class ExampleView(TemplateView):
 
 ## Template files
 
-Template files can be located in either a root `app/templates`,
-or the `<pkg>/templates` directory of any installed package.
+Template files can live in two locations:
 
-All template directories are "merged" together, allowing you to override templates from other packages. The `app/templates` will take priority, followed by `INSTALLED_PACKAGES` in the order they are defined.
+1. **`app/templates/`** - Your app's templates (highest priority)
+2. **`{package}/templates/`** - Templates inside any installed package
 
-## Extending Jinja
+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/`.
 
-Plain includes a set of default [global variables](./jinja/globals.py) and [filters](./jinja/filters.py). You can register additional extensions, globals, or filters either in a package or in your app. Typically this will be in `app/templates.py` or `<pkg>/templates.py`, which are automatically imported.
+## Template context
+
+When using `TemplateView`, you pass data to templates by overriding `get_template_context()`.
+
+```python
+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_extension
-from plain.templates.jinja.extensions import InclusionTagExtension
-from plain.runtime import settings
+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 HTMXJSExtension(InclusionTagExtension):
-    tags = {"htmx_js"}
-    template_name = "htmx/js.html"
+class AlertExtension(InclusionTagExtension):
+    tags = {"alert"}
+    template_name = "components/alert.html"
 
     def get_context(self, context, *args, **kwargs):
         return {
-            "DEBUG": settings.DEBUG,
-            "extensions": kwargs.get("extensions", []),
+            "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
 
-Templates can also be rendered manually using the [`Template` class](./core.py#Template).
+You can render templates outside of views using the [`Template`](./core.py#Template) class.
 
 ```python
 from plain.templates import Template
 
-comment_body = Template("comment.md").render({"message": "Hello, world!",})
+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.
+
+## Installation
+
+The `plain.templates` module is included with Plain by default. No additional installation is required.

plain/templates/jinja/__init__.py

@@ -1,5 +1,7 @@
-import importlib.util
-from importlib import import_module
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
 
 from plain.packages import packages_registry
 from plain.runtime import settings
@@ -10,11 +12,7 @@ from .environments import DefaultEnvironment, get_template_dirs
 
 
 class JinjaEnvironment(LazyObject):
-    def __init__(self, *args, **kwargs):
-        self.__dict__["_imported_modules"] = set()
-        super().__init__(*args, **kwargs)
-
-    def _setup(self):
+    def _setup(self) -> None:
         environment_setting = settings.TEMPLATES_JINJA_ENVIRONMENT
 
         if isinstance(environment_setting, str):
@@ -25,33 +23,19 @@ class JinjaEnvironment(LazyObject):
         # We have to set _wrapped before we trigger the autoloading of "register" commands
         self._wrapped = env
 
-        for package_config in packages_registry.get_package_configs():
-            # Autoload template helpers if the package provides a ``templates`` module
-            import_name = f"{package_config.name}.templates"
-            if import_name in self._imported_modules:
-                continue
-            if importlib.util.find_spec(import_name) is None:
-                continue
-            import_module(import_name)
-            self._imported_modules.add(import_name)
-
-        # Autoload template helpers from the local ``app`` package if present
-        import_name = "app.templates"
-        if import_name not in self._imported_modules:
-            if importlib.util.find_spec(import_name) is not None:
-                import_module(import_name)
-                self._imported_modules.add(import_name)
+        # Autoload template helpers using the registry method
+        packages_registry.autodiscover_modules("templates", include_app=True)
 
 
 environment = JinjaEnvironment()
 
 
-def register_template_extension(extension_class):
+def register_template_extension(extension_class: type) -> type:
     environment.add_extension(extension_class)
     return extension_class
 
 
-def register_template_global(value, name=None):
+def register_template_global(value: Any, name: str | None = None) -> Any:
     """
     Adds a global to the Jinja environment.
 
@@ -75,9 +59,12 @@ def register_template_global(value, name=None):
     return value
 
 
-def register_template_filter(func, name=None):
+def register_template_filter(
+    func: Callable[..., Any], name: str | None = None
+) -> Callable[..., Any]:
     """Adds a filter to the Jinja environment."""
-    environment.filters[name or func.__name__] = func
+    filter_name = name if name is not None else func.__name__  # type: ignore[attr-defined]
+    environment.filters[filter_name] = func
     return func
 
 

plain/templates/jinja/environments.py

@@ -1,5 +1,6 @@
 import functools
 from pathlib import Path
+from typing import Any
 
 from jinja2 import Environment, StrictUndefined
 from jinja2.loaders import FileSystemLoader
@@ -11,7 +12,7 @@ from .filters import default_filters
 from .globals import default_globals
 
 
-def finalize_callable_error(obj):
+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?")
@@ -23,14 +24,14 @@ def finalize_callable_error(obj):
     return obj
 
 
-def get_template_dirs():
+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():
+def _get_app_template_dirs() -> tuple[Path, ...]:
     """
     Return an iterable of paths of directories to load app templates from.
 
@@ -54,7 +55,7 @@ class DefaultEnvironment(Environment):
             autoescape=True,
             auto_reload=settings.DEBUG,
             undefined=StrictUndefined,
-            finalize=finalize_callable_error,
+            finalize=_finalize_callable_error,
             extensions=["jinja2.ext.loopcontrols", "jinja2.ext.debug"],
         )
 

plain/templates/jinja/extensions.py

@@ -1,5 +1,10 @@
+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):
@@ -9,7 +14,7 @@ class InclusionTagExtension(Extension):
     tags: set[str]
     template_name: str
 
-    def parse(self, parser):
+    def parse(self, parser: Any) -> nodes.Node:
         lineno = next(parser.stream).lineno
         args = [
             nodes.DerivedContextReference(),
@@ -28,12 +33,14 @@ class InclusionTagExtension(Extension):
         call = self.call_method("_render", args=args, kwargs=kwargs, lineno=lineno)
         return nodes.CallBlock(call, [], [], []).set_lineno(lineno)
 
-    def _render(self, context, *args, **kwargs):
-        context = self.get_context(context, *args, **kwargs)
+    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(context)
+        return template.render(render_context)
 
-    def get_context(self, context, *args, **kwargs):
+    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."
         )

plain/templates/jinja/filters.py

@@ -1,12 +1,17 @@
+from __future__ import annotations
+
 import datetime
 from itertools import islice
+from typing import Any
 
 from plain.utils.html import json_script
 from plain.utils.timesince import timesince, timeuntil
 from plain.utils.timezone import localtime
 
 
-def localtime_filter(value, timezone=None):
+def localtime_filter(
+    value: datetime.datetime | None, timezone: Any = None
+) -> datetime.datetime:
     """Converts a datetime to local time in a template."""
     if not value:
         # Without this, we get the current localtime
@@ -15,7 +20,7 @@ def localtime_filter(value, timezone=None):
     return localtime(value, timezone)
 
 
-def pluralize_filter(value, singular="", plural="s"):
+def pluralize_filter(value: Any, singular: str = "", plural: str = "s") -> str:
     """Returns plural suffix based on the value count.
 
     Usage:

plain/templates/jinja/globals.py

@@ -5,7 +5,7 @@ from plain.urls import reverse
 from plain.utils import timezone
 
 
-def asset(url_path):
+def _asset(url_path: str) -> str:
     # An explicit callable we can control, but also delay the import of asset.urls->views->templates
     # for circular import reasons
     from plain.assets.urls import get_asset_url
@@ -14,7 +14,7 @@ def asset(url_path):
 
 
 default_globals = {
-    "asset": asset,
+    "asset": _asset,
     "url": reverse,
     "Paginator": Paginator,
     "now": timezone.now,