plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/test/encoding.py

@@ -1,12 +1,15 @@
+from __future__ import annotations
+
 import mimetypes
 import os
+from typing import Any
 
 from plain.runtime import settings
 from plain.utils.encoding import force_bytes
 from plain.utils.itercompat import is_iterable
 
 
-def encode_multipart(boundary, data):
+def encode_multipart(boundary: str, data: dict[str, Any]) -> bytes:
     """
     Encode multipart POST data from a dictionary of form values.
 
@@ -14,13 +17,13 @@ def encode_multipart(boundary, data):
     as content. If the value is a file, the contents of the file will be sent
     as an application/octet-stream; otherwise, str(value) will be sent.
     """
-    lines = []
+    lines: list[bytes] = []
 
-    def to_bytes(s):
+    def to_bytes(s: str) -> bytes:
         return force_bytes(s, settings.DEFAULT_CHARSET)
 
     # Not by any means perfect, but good enough for our purposes.
-    def is_file(thing):
+    def is_file(thing: Any) -> bool:
         return hasattr(thing, "read") and callable(thing.read)
 
     # Each bit of the multipart form data could be either a form value or a
@@ -68,8 +71,8 @@ def encode_multipart(boundary, data):
     return b"\r\n".join(lines)
 
 
-def encode_file(boundary, key, file):
-    def to_bytes(s):
+def encode_file(boundary: str, key: str, file: Any) -> list[bytes]:
+    def to_bytes(s: str) -> bytes:
         return force_bytes(s, settings.DEFAULT_CHARSET)
 
     # file.name might not be a string. For example, it's an int for

plain/test/exceptions.py

@@ -1,7 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+
 class RedirectCycleError(Exception):
     """The test client has been asked to follow a redirect loop."""
 
-    def __init__(self, message, last_response):
+    def __init__(self, message: str, last_response: Any) -> None:
         super().__init__(message)
         self.last_response = last_response
-        self.redirect_chain = last_response.redirect_chain
+        self.redirect_chain: list[tuple[str, int]] = last_response.redirect_chain

plain/urls/README.md

@@ -1,27 +1,68 @@
 # URLs
 
-**Route requests to views.**
+**Route incoming requests to views based on URL patterns.**
 
 - [Overview](#overview)
+- [Defining paths](#defining-paths)
+- [Including sub-routers](#including-sub-routers)
+- [Path converters](#path-converters)
+    - [Built-in converters](#built-in-converters)
+    - [Custom converters](#custom-converters)
 - [Reversing URLs](#reversing-urls)
-- [URL args and kwargs](#url-args-and-kwargs)
-- [Package routers](#package-routers)
+    - [In templates](#in-templates)
+    - [In Python code](#in-python-code)
+    - [Lazy reverse](#lazy-reverse)
+- [Regex patterns](#regex-patterns)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-URLs are typically the "entrypoint" to your app. Virtually all request handling up to this point happens behind the scenes, and then you decide how to route specific URL patterns to your views.
+You define URL routing by creating a `Router` class with a list of URL patterns. Each pattern maps a URL path to a view.
 
-The `URLS_ROUTER` is the primary router that handles all incoming requests. It is defined in your `app/settings.py` file. This will typically point to a `Router` class in your `app.urls` module.
+```python
+# app/urls.py
+from plain.urls import Router, path
+from . import views
+
+
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        path("", views.HomeView),
+        path("about/", views.AboutView, name="about"),
+        path("contact/", views.ContactView, name="contact"),
+    ]
+```
+
+The `URLS_ROUTER` setting in your `app/settings.py` tells Plain which router handles incoming requests:
 
 ```python
 # app/settings.py
 URLS_ROUTER = "app.urls.AppRouter"
 ```
 
-The root router often has an empty namespace (`""`) and some combination of individual paths and sub-routers.
+When a request comes in, Plain matches the URL against your patterns in order and calls the corresponding view.
+
+## Defining paths
+
+Use `path()` to map a URL pattern to a view class:
+
+```python
+path("about/", views.AboutView, name="about")
+```
+
+The `name` parameter is optional but required if you want to reverse the URL later. You can pass the view class directly (Plain calls `as_view()` for you) or call `as_view()` yourself to pass arguments:
+
+```python
+path("dashboard/", views.DashboardView.as_view(template_name="custom.html"), name="dashboard")
+```
+
+## Including sub-routers
+
+Use `include()` to nest routers under a URL prefix. This keeps your URL configuration modular.
 
 ```python
-# app/urls.py
 from plain.urls import Router, path, include
 from plain.admin.urls import AdminRouter
 from . import views
@@ -31,127 +72,170 @@ class AppRouter(Router):
     namespace = ""
     urls = [
         include("admin/", AdminRouter),
-        path("about/", views.AboutView, name="about"),  # A named URL
-        path("", views.HomeView),  # An unnamed URL
+        include("api/", ApiRouter),
+        path("", views.HomeView),
     ]
 ```
 
-## Reversing URLs
+Each included router has its own `namespace` that prefixes URL names. For example, if `AdminRouter` has `namespace = "admin"` and a URL named `"dashboard"`, you reverse it as `"admin:dashboard"`.
 
-In templates, you will use the `{{ url("<url name>") }}` function to look up full URLs by name.
+You can also include a list of patterns directly without creating a separate router class:
 
-```html
-<a href="{{ url('about') }}">About</a>
+```python
+include("api/", [
+    path("users/", views.UsersAPIView, name="users"),
+    path("posts/", views.PostsAPIView, name="posts"),
+])
 ```
 
-And the same can be done in Python code with the `reverse` (or `reverse_lazy`) function.
+## Path converters
 
-```python
-from plain.urls import reverse
+Capture dynamic segments from URLs using angle bracket syntax:
 
-url = reverse("about")
+```python
+path("user/<int:user_id>/", views.UserView, name="user")
+path("post/<slug:post_slug>/", views.PostView, name="post")
 ```
 
-A URL path has to include a `name` attribute if you want to reverse it. The router's `namespace` will be used as a prefix to the URL name.
+Captured values are available in your view as `self.url_kwargs`:
 
 ```python
-from plain.urls import reverse
+class UserView(View):
+    def get(self):
+        user_id = self.url_kwargs["user_id"]  # Already converted to int
+        # ...
+```
+
+### Built-in converters
 
-url = reverse("admin:dashboard")
+| Converter | Matches                                                 | Python type |
+| --------- | ------------------------------------------------------- | ----------- |
+| `str`     | Any non-empty string excluding `/` (default)            | `str`       |
+| `int`     | Zero or positive integers                               | `int`       |
+| `slug`    | ASCII letters, numbers, hyphens, underscores            | `str`       |
+| `uuid`    | UUID format like `075194d3-6885-417e-a8a8-6c931e272f00` | `uuid.UUID` |
+| `path`    | Any non-empty string including `/`                      | `str`       |
+
+When no converter is specified, `str` is used:
+
+```python
+path("search/<query>/", views.SearchView)  # Same as <str:query>
 ```
 
-## URL args and kwargs
+### Custom converters
 
-URL patterns can include arguments and keyword arguments.
+You can register your own converters using [`register_converter()`](./converters.py#register_converter). A converter class needs a `regex` attribute and `to_python()` / `to_url()` methods:
 
 ```python
-# app/urls.py
-from plain.urls import Router, path
-from . import views
+from plain.urls import register_converter
 
 
-class AppRouter(Router):
-    namespace = ""
-    urls = [
-        path("user/<int:user_id>/", views.UserView, name="user"),
-        path("search/<str:query>/", views.SearchView, name="search"),
-    ]
+class YearConverter:
+    regex = "[0-9]{4}"
+
+    def to_python(self, value):
+        return int(value)
+
+    def to_url(self, value):
+        return str(value)
+
+
+register_converter(YearConverter, "year")
 ```
 
-These will be accessible inside the view as `self.url_args` and `self.url_kwargs`.
+Then use it in your patterns:
 
 ```python
-# app/views.py
-from plain.views import View
+path("archive/<year:year>/", views.ArchiveView, name="archive")
+```
 
+## Reversing URLs
 
-class SearchView(View):
-    def get(self):
-        query = self.url_kwargs["query"]
-        print(f"Searching for {query}")
-        # ...
+### In templates
+
+Use the `url()` function to generate URLs by name:
+
+```html
+<a href="{{ url('about') }}">About</a>
+<a href="{{ url('user', user_id=42) }}">User Profile</a>
+<a href="{{ url('admin:dashboard') }}">Admin Dashboard</a>
 ```
 
-To reverse a URL with args or kwargs, simply pass them in the `reverse` function.
+### In Python code
+
+Use `reverse()` to generate URLs programmatically:
 
 ```python
 from plain.urls import reverse
 
-url = reverse("search", query="example")
+url = reverse("about")  # "/about/"
+url = reverse("user", user_id=42)  # "/user/42/"
+url = reverse("admin:dashboard")  # "/admin/dashboard/"
 ```
 
-There are a handful of built-in [converters](converters.py#DEFAULT_CONVERTERS) that can be used in URL patterns.
+If the URL name does not exist or the arguments do not match, `reverse()` raises [`NoReverseMatch`](./exceptions.py#NoReverseMatch).
+
+### Lazy reverse
+
+Use `reverse_lazy()` when you need a URL at module load time (such as in class attributes or default arguments):
 
 ```python
-from plain.urls import Router, path
-from . import views
+from plain.urls import reverse_lazy
 
 
-class AppRouter(Router):
-    namespace = ""
-    urls = [
-        path("user/<int:user_id>/", views.UserView, name="user"),
-        path("search/<str:query>/", views.SearchView, name="search"),
-        path("post/<slug:post_slug>/", views.PostView, name="post"),
-        path("document/<uuid:uuid>/", views.DocumentView, name="document"),
-        path("path/<path:subpath>/", views.PathView, name="path"),
-    ]
+class MyView(View):
+    success_url = reverse_lazy("home")
 ```
 
-## Package routers
+The URL is not resolved until it is actually used as a string.
+
+## Regex patterns
 
-Installed packages will often provide a URL router to include in your root URL router.
+For complex matching that path converters cannot handle, you can use regular expressions:
 
 ```python
-# plain/assets/urls.py
-from plain.urls import Router, path
-from .views import AssetView
+import re
+from plain.urls import path
 
+path(re.compile(r"^articles/(?P<year>[0-9]{4})/$"), views.ArticleView, name="article")
+```
 
-class AssetsRouter(Router):
-    """
-    The router for serving static assets.
+Named groups become keyword arguments. Unnamed groups become positional arguments accessible via `self.url_args`.
 
-    Include this router in your app router if you are serving assets yourself.
-    """
+## FAQs
 
-    namespace = "assets"
-    urls = [
-        path("<path:path>", AssetView, name="asset"),
-    ]
-```
+#### Why does my URL pattern need a trailing slash?
+
+By default, Plain's `APPEND_SLASH` setting redirects URLs without a trailing slash to URLs with one. Define your patterns with trailing slashes to match this behavior. If you prefer URLs without trailing slashes, set `APPEND_SLASH = False` in your settings.
+
+#### How do I debug URL routing issues?
+
+Check that your URL patterns are in the correct order. Plain matches patterns top to bottom and uses the first match. More specific patterns should come before general ones.
+
+#### Can I access URL arguments as positional args instead of kwargs?
 
-Import the package's router and `include` it at any path you choose.
+If you use regex patterns with unnamed groups (no `?P<name>`), values are passed as positional arguments in `self.url_args`. Named groups always populate `self.url_kwargs`.
+
+## Installation
+
+The `plain.urls` module is included with Plain by default. No additional installation is required.
+
+To set up URL routing, create a router in `app/urls.py` and point to it in your settings:
 
 ```python
-from plain.urls import include, Router
-from plain.assets.urls import AssetsRouter
+# app/settings.py
+URLS_ROUTER = "app.urls.AppRouter"
+```
+
+```python
+# app/urls.py
+from plain.urls import Router, path
+from . import views
 
 
 class AppRouter(Router):
     namespace = ""
     urls = [
-        include("assets/", AssetsRouter),
-        # Your other URLs here...
+        path("", views.HomeView),
     ]
 ```

plain/urls/converters.py

@@ -1,34 +1,37 @@
+from __future__ import annotations
+
 import functools
 import uuid
+from typing import Any
 
 
 class IntConverter:
     regex = "[0-9]+"
 
-    def to_python(self, value):
+    def to_python(self, value: str) -> int:
         return int(value)
 
-    def to_url(self, value):
+    def to_url(self, value: int) -> str:
         return str(value)
 
 
 class StringConverter:
     regex = "[^/]+"
 
-    def to_python(self, value):
+    def to_python(self, value: str) -> str:
         return value
 
-    def to_url(self, value):
+    def to_url(self, value: str) -> str:
         return value
 
 
 class UUIDConverter:
     regex = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
 
-    def to_python(self, value):
+    def to_python(self, value: str) -> uuid.UUID:
         return uuid.UUID(value)
 
-    def to_url(self, value):
+    def to_url(self, value: uuid.UUID) -> str:
         return str(value)
 
 
@@ -40,7 +43,7 @@ class PathConverter(StringConverter):
     regex = ".+"
 
 
-DEFAULT_CONVERTERS = {
+_DEFAULT_CONVERTERS = {
     "int": IntConverter(),
     "path": PathConverter(),
     "slug": SlugConverter(),
@@ -49,18 +52,18 @@ DEFAULT_CONVERTERS = {
 }
 
 
-REGISTERED_CONVERTERS = {}
+_REGISTERED_CONVERTERS: dict[str, Any] = {}
 
 
-def register_converter(converter, type_name):
-    REGISTERED_CONVERTERS[type_name] = converter()
-    get_converters.cache_clear()
+def register_converter(converter: type, type_name: str) -> None:
+    _REGISTERED_CONVERTERS[type_name] = converter()
+    _get_converters.cache_clear()
 
 
 @functools.cache
-def get_converters():
-    return {**DEFAULT_CONVERTERS, **REGISTERED_CONVERTERS}
+def _get_converters() -> dict[str, Any]:
+    return {**_DEFAULT_CONVERTERS, **_REGISTERED_CONVERTERS}
 
 
-def get_converter(raw_converter):
-    return get_converters()[raw_converter]
+def _get_converter(raw_converter: str) -> Any:
+    return _get_converters()[raw_converter]

plain/urls/exceptions.py

@@ -1,7 +1,7 @@
-from plain.http import Http404
+from plain.http import NotFoundError404
 
 
-class Resolver404(Http404):
+class Resolver404(NotFoundError404):
     pass
 
 

plain/urls/patterns.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 import re
 import string
+from typing import Any
 
 from plain.exceptions import ImproperlyConfigured
 from plain.internal import internalcode
@@ -7,12 +10,16 @@ from plain.preflight import PreflightResult
 from plain.runtime import settings
 from plain.utils.regex_helper import _lazy_re_compile
 
-from .converters import get_converter
+from .converters import _get_converter
 
 
 @internalcode
 class CheckURLMixin:
-    def describe(self):
+    # Expected to be set by subclasses
+    regex: re.Pattern[str]
+    name: str | None
+
+    def describe(self) -> str:
         """
         Format the URL pattern for display in warning messages.
         """
@@ -21,7 +28,7 @@ class CheckURLMixin:
             description += f" [name='{self.name}']"
         return description
 
-    def _check_pattern_startswith_slash(self):
+    def _check_pattern_startswith_slash(self) -> list[PreflightResult]:
         """
         Check that the pattern does not begin with a forward slash.
         """
@@ -44,14 +51,14 @@ class CheckURLMixin:
 
 
 class RegexPattern(CheckURLMixin):
-    def __init__(self, regex, name=None, is_endpoint=False):
+    def __init__(self, regex: str, name: str | None = None, is_endpoint: bool = False):
         self._regex = regex
         self._is_endpoint = is_endpoint
         self.name = name
-        self.converters = {}
+        self.converters: dict[str, Any] = {}
         self.regex = self._compile(str(regex))
 
-    def match(self, path):
+    def match(self, path: str) -> tuple[str, tuple[Any, ...], dict[str, Any]] | None:
         match = (
             self.regex.fullmatch(path)
             if self._is_endpoint and self.regex.pattern.endswith("$")
@@ -67,14 +74,14 @@ class RegexPattern(CheckURLMixin):
             return path[match.end() :], args, kwargs
         return None
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = []
         warnings.extend(self._check_pattern_startswith_slash())
         if not self._is_endpoint:
             warnings.extend(self._check_include_trailing_dollar())
         return warnings
 
-    def _check_include_trailing_dollar(self):
+    def _check_include_trailing_dollar(self) -> list[PreflightResult]:
         regex_pattern = self.regex.pattern
         if regex_pattern.endswith("$") and not regex_pattern.endswith(r"\$"):
             return [
@@ -87,7 +94,7 @@ class RegexPattern(CheckURLMixin):
         else:
             return []
 
-    def _compile(self, regex):
+    def _compile(self, regex: str) -> re.Pattern[str]:
         """Compile and return the given regular expression."""
         try:
             return re.compile(regex)
@@ -96,7 +103,7 @@ class RegexPattern(CheckURLMixin):
                 f'"{regex}" is not a valid regular expression: {e}'
             ) from e
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self._regex)
 
 
@@ -105,7 +112,9 @@ _PATH_PARAMETER_COMPONENT_RE = _lazy_re_compile(
 )
 
 
-def _route_to_regex(route, is_endpoint=False):
+def _route_to_regex(
+    route: str, is_endpoint: bool = False
+) -> tuple[str, dict[str, Any]]:
     """
     Convert a path pattern into a regular expression. Return the regular
     expression and a dictionary mapping the capture names to the converters.
@@ -138,7 +147,7 @@ def _route_to_regex(route, is_endpoint=False):
             # If a converter isn't specified, the default is `str`.
             raw_converter = "str"
         try:
-            converter = get_converter(raw_converter)
+            converter = _get_converter(raw_converter)
         except KeyError as e:
             raise ImproperlyConfigured(
                 f"URL route {original_route!r} uses invalid converter {raw_converter!r}."
@@ -151,14 +160,14 @@ def _route_to_regex(route, is_endpoint=False):
 
 
 class RoutePattern(CheckURLMixin):
-    def __init__(self, route, name=None, is_endpoint=False):
+    def __init__(self, route: str, name: str | None = None, is_endpoint: bool = False):
         self._route = route
         self._is_endpoint = is_endpoint
         self.name = name
         self.converters = _route_to_regex(str(route), is_endpoint)[1]
         self.regex = self._compile(str(route))
 
-    def match(self, path):
+    def match(self, path: str) -> tuple[str, tuple[()], dict[str, Any]] | None:
         match = self.regex.search(path)
         if match:
             # RoutePattern doesn't allow non-named groups so args are ignored.
@@ -172,7 +181,7 @@ class RoutePattern(CheckURLMixin):
             return path[match.end() :], (), kwargs
         return None
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = self._check_pattern_startswith_slash()
         route = self._route
         if "(?P<" in route or route.startswith("^") or route.endswith("$"):
@@ -187,28 +196,34 @@ class RoutePattern(CheckURLMixin):
             )
         return warnings
 
-    def _compile(self, route):
+    def _compile(self, route: str) -> re.Pattern[str]:
         return re.compile(_route_to_regex(route, self._is_endpoint)[0])
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self._route)
 
 
 class URLPattern:
-    def __init__(self, *, pattern, view, name=None):
+    def __init__(
+        self,
+        *,
+        pattern: RegexPattern | RoutePattern,
+        view: Any,
+        name: str | None = None,
+    ):
         self.pattern = pattern
         self.view = view
         self.name = name
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__} {self.pattern.describe()}>"
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = self._check_pattern_name()
         warnings.extend(self.pattern.preflight())
         return warnings
 
-    def _check_pattern_name(self):
+    def _check_pattern_name(self) -> list[PreflightResult]:
         """
         Check that the pattern name does not contain a colon.
         """
@@ -223,7 +238,7 @@ class URLPattern:
         else:
             return []
 
-    def resolve(self, path):
+    def resolve(self, path: str) -> Any:
         match = self.pattern.match(path)
         if match:
             new_path, args, captured_kwargs = match
@@ -236,3 +251,4 @@ class URLPattern:
                 url_name=self.pattern.name,
                 route=str(self.pattern),
             )
+        return None