plain 0.68.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,3 +1,8 @@
+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
@@ -7,7 +12,7 @@ from .environments import DefaultEnvironment, get_template_dirs
 
 
 class JinjaEnvironment(LazyObject):
-    def _setup(self):
+    def _setup(self) -> None:
         environment_setting = settings.TEMPLATES_JINJA_ENVIRONMENT
 
         if isinstance(environment_setting, str):
@@ -25,12 +30,12 @@ class JinjaEnvironment(LazyObject):
 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.
 
@@ -54,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,

plain/test/README.md

@@ -1,42 +1,204 @@
-# Test
+# plain.test
 
-**Testing utilities for Plain.**
+**Testing utilities for making HTTP requests and inspecting responses.**
 
 - [Overview](#overview)
+- [Making requests](#making-requests)
+    - [GET requests](#get-requests)
+    - [POST requests](#post-requests)
+    - [Other HTTP methods](#other-http-methods)
+    - [Following redirects](#following-redirects)
+    - [Custom headers](#custom-headers)
+- [Inspecting responses](#inspecting-responses)
+    - [JSON responses](#json-responses)
+    - [Response attributes](#response-attributes)
+- [Authentication](#authentication)
+- [Sessions](#sessions)
+- [RequestFactory](#requestfactory)
+- [FAQs](#faqs)
+    - [What is the difference between Client and RequestFactory?](#what-is-the-difference-between-client-and-requestfactory)
+    - [How do I test file uploads?](#how-do-i-test-file-uploads)
+    - [How do I disable exception raising?](#how-do-i-disable-exception-raising)
+- [Installation](#installation)
 
 ## Overview
 
-This module provides the [`Client`](client.py#Client) and [`RequestFactory`](client.py#RequestFactory) classes to facilitate testing requests and responses.
+You can test your Plain views using the [`Client`](./client.py#Client) class. It simulates HTTP requests and returns responses, allowing you to verify status codes, content, and behavior without running a real server.
 
 ```python
 from plain.test import Client
 
 
-def test_client_example():
+def test_homepage():
     client = Client()
-
-    # Getting responses
     response = client.get("/")
     assert response.status_code == 200
+```
 
-    # Modifying sessions
-    client.session["example"] = "value"
-    assert client.session["example"] == "value"
+The client maintains cookies and session state across requests, so you can test multi-step flows like login and logout.
 
-    # Logging in
-    user = User.query.first()
-    client.force_login(user)
-    response = client.get("/protected/")
-    assert response.status_code == 200
+## Making requests
+
+### GET requests
+
+Pass query parameters using the `data` argument.
+
+```python
+response = client.get("/search/", data={"q": "hello"})
+```
+
+### POST requests
+
+Send form data by default.
+
+```python
+response = client.post("/submit/", data={"name": "Alice", "email": "alice@example.com"})
+```
+
+Send JSON by setting the content type.
+
+```python
+response = client.post(
+    "/api/users/",
+    data={"name": "Alice"},
+    content_type="application/json",
+)
+```
+
+### Other HTTP methods
+
+The client supports all standard HTTP methods: `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, and `trace`.
+
+```python
+response = client.put("/api/users/1/", data={"name": "Bob"}, content_type="application/json")
+response = client.patch("/api/users/1/", data={"name": "Bob"}, content_type="application/json")
+response = client.delete("/api/users/1/")
+```
+
+### Following redirects
+
+Set `follow=True` to automatically follow redirect responses.
+
+```python
+response = client.get("/old-url/", follow=True)
+assert response.status_code == 200  # Final destination
+assert response.redirect_chain == [("/new-url/", 302)]
+```
+
+### Custom headers
+
+Pass headers using the `headers` argument.
+
+```python
+response = client.get("/api/", headers={"Authorization": "Bearer token123"})
+```
+
+You can also set default headers when creating the client.
+
+```python
+client = Client(headers={"Accept-Language": "en-US"})
+```
+
+## Inspecting responses
+
+### JSON responses
+
+Parse JSON response content using the `json()` method.
+
+```python
+response = client.get("/api/users/")
+data = response.json()
+assert data["users"][0]["name"] == "Alice"
+```
+
+### Response attributes
+
+The [`ClientResponse`](./client.py#ClientResponse) wrapper provides access to:
+
+- `status_code` - HTTP status code (200, 404, etc.)
+- `content` - Response body as bytes
+- `headers` - Response headers
+- `cookies` - Cookies set by the response
+- `wsgi_request` - The original request object
+- `resolver_match` - URL resolver match information
+- `redirect_chain` - List of redirects when using `follow=True`
+
+## Authentication
+
+You can log in a user without going through the login flow using `force_login`. This requires `plain.auth` to be installed.
+
+```python
+user = User.objects.get(username="alice")
+client.force_login(user)
+response = client.get("/dashboard/")
+assert response.status_code == 200
+```
+
+Log out using the `logout` method.
+
+```python
+client.logout()
+response = client.get("/dashboard/")
+assert response.status_code == 302  # Redirected to login
+```
+
+## Sessions
+
+Access session data using the `session` property. This requires `plain.sessions` to be installed.
+
+```python
+client.session["cart_id"] = "abc123"
+response = client.get("/cart/")
+assert "abc123" in response.content.decode()
+```
+
+## RequestFactory
 
-    # Logging out
-    client.logout()
-    response = client.get("/protected/")
-    assert response.status_code == 302
+Use [`RequestFactory`](./client.py#RequestFactory) to create request objects directly without going through the WSGI handler. This is useful for testing views in isolation.
 
-def test_request_factory_example():
-    request = RequestFactory().get("/")
-    assert request.method == "GET"
+```python
+from plain.test import RequestFactory
+
+rf = RequestFactory()
+request = rf.get("/hello/")
+response = my_view(request)
+assert response.status_code == 200
+```
+
+The factory supports the same HTTP methods as the client: `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, and `trace`.
+
+## FAQs
+
+#### What is the difference between Client and RequestFactory?
+
+The `Client` executes requests through the full middleware stack and maintains state (cookies, sessions) between requests. Use it for integration tests.
+
+The `RequestFactory` creates request objects without executing them. Use it for unit testing individual views in isolation.
+
+#### How do I test file uploads?
+
+Pass file-like objects in the `data` dictionary.
+
+```python
+from io import BytesIO
+
+file = BytesIO(b"file contents")
+file.name = "test.txt"
+response = client.post("/upload/", data={"file": file})
+```
+
+#### How do I disable exception raising?
+
+By default, the client raises exceptions that occur during request processing. Set `raise_request_exception=False` to capture them on the response instead.
+
+```python
+client = Client(raise_request_exception=False)
+response = client.get("/broken/")
+assert response.status_code == 500
 ```
 
-More complete testing utilities are provided by the [`plain.pytest`](/plain-pytest/README.md) package. The [`plain.models`](/plain-models/README.md) package also provides pytest fixtures for database testing.
+## Installation
+
+The `plain.test` module is included with the `plain` package. No additional installation is required.
+
+For additional testing utilities like pytest fixtures and browser testing, see [`plain.pytest`](/plain-pytest/README.md).