sillo-framework 0.3.2.dev1__tar.gz → 1.0.0a1__tar.gz

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0a1}/CHANGELOG.md

@@ -7,6 +7,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0a1] - 2026-09-12
+
+The first alpha of 1.0 — **the context rewrite**. This is a breaking release
+with no compatibility shims. Install with
+`pip install --pre sillo-framework==1.0.0a1`.
+
+An alpha: the surface below is what 1.0 is expected to look like, but it is not
+frozen yet, and API may still change before `1.0.0`.
+
+### Added
+
+- **Host-scoped routers — `Router(host=...)`.** A router only answers requests whose `Host` header matches. Exact (`admin.example.com`) or a single-label wildcard (`*.example.com`). A request to another host falls through to the rest of the app.
+- **Version-scoped routers — `Router(version=...)`.** A router only answers requests carrying a matching `X-API-Version` header, or an `Accept` media type with a `version=<value>` parameter. Lets a `v1` and `v2` router share the same paths and be picked by the client.
+- **`Router(middleware=[...])`.** Register router middleware at construction — dispatch callables, `DefineMiddleware`, or `(cls, args, kwargs)` tuples — instead of a run of `router.use(...)` calls. First in the list is the outermost layer.
+- **`SilloApp(root_path=...)`.** A mount prefix a reverse proxy strips before forwarding. It is folded into `scope["root_path"]`, removed before route matching, and re-added by `ctx.url_for(...)` and the OpenAPI `servers` block, so generated links stay correct.
+- **`SilloApp(force_https=True)`.** Any plain-`http` request is answered with a 308 to the `https` URL. `X-Forwarded-Proto: https` from a proxy is honoured, so a TLS-terminating proxy in front of an `http` app does not loop.
+- **`SilloApp(trailing_slash=...)` / `Router(trailing_slash=...)`.** `"strict"` (default, `/x` ≠ `/x/`), `"redirect"` (308 to the registered form), or `"ignore"` (serve it in place).
+- **Declarative redirects — `app.redirect(path, to, *, status_code=307, ...)`** (and `Router.redirect`). Registers a redirect-only route, no handler. Placeholders shared by both sides are substituted (`app.redirect("/u/{id}", "/users/{id}")`); a mount prefix and the query string are carried across. Hidden from the schema.
+- **`app.print_routes()`** and `sillo.core.routing.{iter_routes, format_routes, print_routes}` — walk the router and every mount, fold prefixes in, and render `METHODS  PATH  handler  (name)` rows for a startup log or a REPL.
+- **New path converters**: `bool` (`true`/`1`/`yes`/`on` and their negatives, any case → real `bool`), `date` (`YYYY-MM-DD` → `datetime.date`), `datetime` (ISO 8601, `Z` accepted → `datetime.datetime`), `ulid` (26 Crockford base32 chars), `alpha` (`[A-Za-z]+`), `alnum` (`[A-Za-z0-9]+`).
+- **`priority=` on routes.** `@app.get(..., priority=10)` (also on `Route(...)`, `add_route(...)`, and `ws_route(...)`) sets an explicit match-ordering weight. Routes are tried in descending priority, then by path specificity, then registration order. Raise it to force a route ahead of an overlapping one; use a negative value to make a route a deliberate fallback.
+- **`SilloApp(route_order=...)` / `Router(route_order=...)`.** `"specificity"` (the new default) or `"registration"` to restore the historical first-registered, first-matched behavior for a whole application. Documented in [Routing → Route matching order](https://sillo.build/v1.0/guides/routing/#route-matching-order).
+- **`app.dependency_overrides`** and **`app.override(original, replacement)`.** Swap a `Depend(...)` callable for a test double, FastAPI-style. Matched by identity against the exact function passed to `Depend`, and reached through every nested dependency in the tree, not only the top-level one. `app.override(...)` is a context manager that restores the previous mapping (present or absent) on exit, including on exception; assign `app.dependency_overrides[original] = replacement` directly for a suite-wide swap that outlives a single `with` block.
+
+### Changed
+
+- **A handler takes one leading argument: the context.** `HttpContext` on an
+  HTTP route, `WebSocketContext` on a WebSocket route. Path parameters,
+  dependencies and validation markers follow it, bound by name as before:
+
+  ```python
+  from sillo import SilloApp, HttpContext, json
+
+  app = SilloApp()
+
+  @app.get("/users/{id:int}")
+  def show(ctx: HttpContext, id: int):
+      return json({"id": id})
+  ```
+
+  `BaseContext` carries `scope`, `headers`, `cookies`, `path_params`,
+  `query_params`, `state`, `user`, `client`, `app` and `url_for`.
+  `HttpContext` adds `method`, `await ctx.json`, `await ctx.body`,
+  `await ctx.form`, `ctx.files` and `ctx.validated_data`.
+
+- **Responses are functions, in `sillo.responses`**, every name re-exported
+  from `sillo` — bodies (`json`, `text`, `html`, `xml`, `raw`, `empty`), status
+  shorthands (`created`, `accepted`, `no_content`), redirects, files
+  (`file`, `download`), streaming (`stream`, `ndjson`, `sse`), pagination
+  (`paginate`, `apaginate`, which take `ctx` first) and `abort` / `not_found`,
+  which raise rather than return. Each builder returns a `BaseResponse`
+  subclass carrying the chainable half (`status`, `cache`, `set_header`,
+  `set_cookie`, …), each returning `self`. Import from the module when the file
+  also needs the stdlib `json`/`html` or the `file` builtin.
+
+- **WebSocket routes bind path parameters.** They were read from
+  `scope["path_params"]`, which the router never writes, so the keyword
+  arguments a handler declared were always empty. Note that the registration
+  name is `ws_route` / `add_ws_route`; there is no `@app.websocket(...)`.
+
+- **An unhandled request error logs a structured block, not a raw traceback.** `sillo.handlers.error_report` keeps only the frames in *your* code:
+
+  ```
+  💥 oops — KeyError: 'ABC-9'
+      request   GET /catalog/ABC-9
+      at        api/catalog.py:14   in show
+                → price = lookup(catalog, sku)
+      at        pricing/rules.py:2   in lookup
+                   1   def lookup(catalog, sku):
+               ›   2       price = catalog["items"][sku]["price"]
+                                   ^^^^^^^^^^^^^^^^^^^^^
+                   3       return price * 1.2
+      with      catalog={'items': {}}, sku='ABC-9'
+  ```
+
+  Each calling frame is one line; the frame it broke on gets a window of real source with the line marked `›` (bright, its neighbours dim) and a caret under the exact expression (Python 3.11+, single-line). `file:line` is cyan, the function bold. `with` lists the raising frame's own locals — scalars and small containers verbatim, a big one as `<dict len=N>`, a name that reads like a secret as `***`. `SILLO_TRACE` sets the depth — `off`, `app` (default while `debug` is on), `full` (append the raw traceback). Off a terminal or with `debug` off, nothing is rendered; one structured line goes to the logger instead. Every 500 also stopped logging two-to-three times — `sillo.core.error.handler` was creating a child logger with its own handler that still propagated to the parent's.
+- **Overlapping routes now match most-specific-first, not registration-first.** A literal segment beats a parameter at the same position, a narrow converter (`:int`, `:float`, `:uuid`) beats a plain string parameter, and both beat a `:path` catch-all — decided left to right. `@app.get("/users/{id}")` no longer shadows a `@app.get("/users/me")` registered after it. The ordering is computed once, lazily, on the first request after registration, so per-request dispatch is unchanged. Pass `route_order="registration"` to opt out.
+- **A 404 response no longer carries a traceback.** The stack of `raise NotFoundException` is the router's, not the caller's — it named internal framework paths and told a developer nothing about their own code. Debug mode still widens the *message* (the exception's `detail` instead of the generic sentence); it no longer adds a `traceback` field.
+- **The 404 and debug (500) HTML pages are restyled** to match Sillo's own terminal aesthetic — dark background, monospace, brand red (`#fc0345`) — instead of a light Arial page for 404s and a page whose `--error`/accent variable was, by mistake, green (`#02ba42`) rather than red for the debug page. Both pages, and two other spots on the debug page that bypassed the CSS variables with a hardcoded color, now flow from the same palette as the terminal error log.
+- **`SilloApp(debug=...)` now defaults to `False`.** It previously defaulted to `True`, so a project that never passed `debug` explicitly shipped with the full debug page — and a verbose terminal error log — on by default. An app that wants debug output in local development now has to say so.
+- **The terminal error trace no longer depends on `debug`.** It only ever prints to the server's own terminal — nothing in it reaches a client — so it now defaults on whenever `stderr` is an actual terminal, regardless of `debug`. Previously it rode on `debug`'s default, so the flip above would otherwise have silently taken the pretty trace away from local development along with the (correct) HTTP-facing change. `SILLO_TRACE` still overrides either way.
+
+### Removed
+
+- **`Request`, the `Response` manager and the `Responder` builder are gone**,
+  and nothing is shimmed. `sillo/core/http/request.py` no longer exists.
+- **The built-in admin panel is no longer part of the framework.** It is its
+  own package now — [`warder`](https://sillo.build/packages/warder/).
+- **`Depend(get_request=True)` / `Depend(get_context=True)`** — a dependency
+  takes the context as its first positional parameter instead.
+
+
 ## [0.3.2.dev1] - 2026-09-07
 
 A development pre-release for testing. Install with `pip install --pre sillo-framework==0.3.2.dev1`.

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sillo-framework
-Version: 0.3.2.dev1
+Version: 1.0.0a1
 Summary: Python with the pieces already in place: an async web framework whose ORM, auth, admin, queues, scheduler and WebSockets share one configuration model.
 Project-URL: Homepage, https://github.com/sillohq/core
 Project-URL: Repository, https://github.com/sillohq/core

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0a1}/pyproject.toml

@@ -8,9 +8,30 @@ sillo = "sillo.__main__:main"
 [tool.hatch.build.targets.wheel]
 packages = ["sillo"]
 
+# Without this the sdist is "everything git does not ignore", which on a working
+# checkout means docs/ (with node_modules), benchmarks/, and any .venv sitting
+# in the tree -- well over a gigabyte, and a hard build failure the moment one
+# of those virtualenvs holds an absolute symlink. List what ships instead.
+[tool.hatch.build.targets.sdist]
+include = [
+    "/sillo",
+    "/tests",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/LICENSE",
+    "/SECURITY.md",
+]
+exclude = [
+    "**/__pycache__",
+    "**/*.py[cod]",
+    "**/.pytest_cache",
+    "**/*.sqlite3",
+    "**/*.db",
+]
+
 [project]
 name = "sillo-framework"
-version = "0.3.2.dev1"
+version = "1.0.0a1"
 description = "Python with the pieces already in place: an async web framework whose ORM, auth, admin, queues, scheduler and WebSockets share one configuration model."
 authors = [
     {name = "Chidebele Dunamis", email = "techwithdunamix@gmail.com"}
@@ -344,7 +365,7 @@ ignore = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.3.2.dev1"
+version = "1.0.0a1"
 version_files = [
     "pyproject.toml:version",
     "sillo/__init__.py:__version__"

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0a1}/sillo/__init__.py

@@ -114,7 +114,7 @@ Common Patterns:
 
 from sillo.core.routing import Group, Route, Router, WebsocketRoute
 
-__version__: str = "0.3.2.dev1"
+__version__: str = "1.0.0a1"
 
 from sillo.core.dependencies import Depend
 

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0a1}/sillo/application.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from collections.abc import Awaitable, Callable, Sequence
+from collections.abc import Awaitable, Callable, Iterator, Sequence
+from contextlib import contextmanager
 from typing import (
     TYPE_CHECKING,
     Annotated,
@@ -192,6 +193,47 @@ lifespan_manager = Callable[
 ]
 
 
+def _request_scheme(scope: Scope) -> str:
+    """The effective scheme, trusting ``X-Forwarded-Proto`` when a proxy set it.
+
+    A TLS-terminating proxy forwards over plain ``http`` but records the
+    original scheme in the header; without honouring it, ``force_https`` would
+    redirect forever.
+    """
+    for key, value in scope.get("headers", []) or []:
+        if key.lower() == b"x-forwarded-proto":
+            return value.decode("latin-1").split(",", 1)[0].strip().lower()
+    return scope.get("scheme", "http")
+
+
+async def _https_redirect(scope: Scope, send: Send) -> None:
+    """Send a 308 to the ``https`` form of the current URL."""
+    host = ""
+    for key, value in scope.get("headers", []) or []:
+        if key.lower() == b"host":
+            host = value.decode("latin-1")
+            break
+    if not host:
+        server = scope.get("server") or ("localhost", None)
+        host = server[0] + (f":{server[1]}" if server[1] else "")
+    path = scope.get("root_path", "") + scope["path"]
+    query = scope.get("query_string", b"")
+    location = f"https://{host}{path}" + (
+        "?" + query.decode("latin-1") if query else ""
+    )
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 308,
+            "headers": [
+                (b"location", location.encode("latin-1")),
+                (b"content-length", b"0"),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": b""})
+
+
 class SilloApp:
     """
     Core application class for the sillo ASGI web framework.
@@ -229,9 +271,19 @@ class SilloApp:
         debug: Annotated[
             bool,
             Doc("""
-                    Whether to enable debug mode.
+                    Whether to enable debug mode: unhandled exceptions render
+                    the full debug page (or, for a 404, the exception's own
+                    detail) instead of a generic message, and the terminal
+                    error log shows the source window instead of a one-line
+                    summary.
+
+                    Off by default. A `SilloApp()` a developer forgets to
+                    flip back before deploying should fail closed — generic
+                    error pages and no internals on the wire — not leak a
+                    stack trace and a source listing to whoever finds the
+                    route that 500s. Turn it on for local development.
                     """),
-        ] = True,
+        ] = False,
         title: Annotated[
             str | None,
             Doc("""
@@ -364,6 +416,23 @@ class SilloApp:
                     their current behavior; recommended for new applications.
                 """),
         ] = False,
+        route_order: Annotated[
+            Literal["specificity", "registration"],
+            Doc("""
+                    How registered routes are ordered before matching.
+
+                    ``"specificity"`` (the default) sorts them so the most
+                    specific path always wins, whatever order they were
+                    registered in: a literal segment beats a parameter at the
+                    same position, so ``/users/me`` is matched before
+                    ``/users/{id}`` even when it is declared later. An explicit
+                    ``priority=`` on a route overrides the computed order.
+
+                    ``"registration"`` keeps the historical behavior — routes
+                    are tried in the order they were added, and an earlier
+                    dynamic route can shadow a later literal one.
+                """),
+        ] = "specificity",
         auth: Annotated[
             Sequence[AuthenticationBackend] | None,
             Doc("""
@@ -403,6 +472,36 @@ class SilloApp:
                     applications keep building; recommended for new ones.
                 """),
         ] = False,
+        root_path: Annotated[
+            str,
+            Doc("""
+                    A path prefix the application is mounted under, for when a
+                    reverse proxy strips it before forwarding (``/api`` on the
+                    proxy, the app sees ``/users``). It is prepended to
+                    whatever ``root_path`` the ASGI server set, removed before
+                    route matching, and added back by ``url_for`` and the
+                    OpenAPI ``servers`` block so generated links stay correct.
+                """),
+        ] = "",
+        force_https: Annotated[
+            bool,
+            Doc("""
+                    Answer any plain-``http`` request with a 308 redirect to
+                    the same URL over ``https``. ``X-Forwarded-Proto: https``
+                    from a trusted proxy is honoured, so a TLS-terminating
+                    proxy in front of an ``http`` app does not cause a loop.
+                    Off by default.
+                """),
+        ] = False,
+        trailing_slash: Annotated[
+            Literal["strict", "redirect", "ignore"],
+            Doc("""
+                    How to treat a path that matches only once its trailing
+                    slash is toggled. ``"strict"`` (default) keeps ``/x`` and
+                    ``/x/`` distinct. ``"redirect"`` sends a 308 to the
+                    registered form. ``"ignore"`` serves it in place.
+                """),
+        ] = "strict",
     ) -> None:
         """
         Initialize the sillo application with all core subsystems.
@@ -472,6 +571,12 @@ class SilloApp:
         self._debug = debug
         self.dependencies = dependencies or []
         self.custom_encoders: dict[type, Callable[[Any], Any]] = {}
+        #: Test doubles for ``Depend(...)`` callables, keyed by the original
+        #: function. ``sillo.core.dependencies.base._resolve_override`` reads
+        #: this by identity every time it is about to run a dependency, so
+        #: assigning here takes effect on the very next request — nothing to
+        #: rebuild. Prefer :meth:`override` for automatic cleanup.
+        self.dependency_overrides: dict[Callable[..., Any], Callable[..., Any]] = {}
 
         self.http_middleware: list[Middleware] = []
         self.startup_handlers: list[Callable[[], Awaitable[None]]] = []
@@ -480,6 +585,8 @@ class SilloApp:
 
         self.route_class = route_class
         self.strict_validation = strict_validation
+        self._root_path = root_path.rstrip("/")
+        self._force_https = force_https
         # Serialized OpenAPI document per mount prefix, built once.
         self._openapi_documents: dict[str, str] = {}
         self.app = Router(
@@ -487,6 +594,8 @@ class SilloApp:
             dependencies=self.dependencies,
             route_class=self.route_class,
             strict_validation=strict_validation,
+            route_order=route_order,
+            trailing_slash=trailing_slash,
         )
         self.exceptions_handler = ExceptionMiddleware()
         self.router = self.app
@@ -1184,6 +1293,65 @@ class SilloApp:
         CUSTOM_ENCODERS[type_] = encoder
         register_encoder(type_, encoder)
 
+    @contextmanager
+    def override(
+        self,
+        original: Callable[..., Any],
+        replacement: Callable[..., Any],
+    ) -> Iterator[None]:
+        """Swap a ``Depend(...)`` callable for a test double, then restore it.
+
+        A handler written as ``async def me(ctx, db=Depend(get_db))`` cannot
+        be tested without a real database unless something stands in for
+        ``get_db``. This is that something:
+
+            async def fake_db(ctx):
+                return FakeSession()
+
+            with app.override(get_db, fake_db):
+                response = client.get("/me")
+
+        The swap is by identity — ``original`` must be the exact function
+        object passed to `Depend`, not a copy or a re-import under another
+        name — and the replacement is looked up on every dependency in the
+        tree, not only the top-level one, so overriding a shared dependency
+        (`get_db`) reaches every route and every nested `Depend(...)` that
+        uses it. The replacement must match what it replaces in shape: a
+        generator dependency needs a generator override, an async one an
+        async override, since the resolver was built from the original's
+        signature and does not re-inspect the double.
+
+        For a suite-wide swap that should not need a `with` block in every
+        test, assign `app.dependency_overrides[original] = replacement`
+        directly and clear it in teardown — this context manager is the
+        same dict, scoped.
+
+        Args:
+            original: The dependency callable to replace, exactly as passed
+                to `Depend(...)`.
+            replacement: The callable to run in its place for the duration
+                of the block.
+
+        Yields:
+            None. Requests made inside the block see `replacement`; the
+            previous mapping (present or absent) is restored on exit even if
+            the block raises.
+        """
+        had_previous = original in self.dependency_overrides
+        # Fall back to `replacement` itself when there was nothing to save —
+        # `had_previous` gates whether it's ever read, so the fallback value
+        # is never actually used, but it keeps `previous` typed as a plain
+        # callable instead of `Callable | None`.
+        previous = self.dependency_overrides.get(original, replacement)
+        self.dependency_overrides[original] = replacement
+        try:
+            yield
+        finally:
+            if had_previous:
+                self.dependency_overrides[original] = previous
+            else:
+                self.dependency_overrides.pop(original, None)
+
     def add_ws_route(
         self,
         route: Annotated[
@@ -1193,6 +1361,7 @@ class SilloApp:
         | None = None,
         path: str | None = None,
         handler: WsHandlerType | None = None,
+        priority: int = 0,
     ) -> None:
         """
         Adds a WebSocket route to the application.
@@ -1225,7 +1394,7 @@ class SilloApp:
                 "path and handler are required when 'route' is not provided."
             )
 
-        self.router.add_ws_route(WebsocketRoute(path, handler))
+        self.router.add_ws_route(WebsocketRoute(path, handler, priority=priority))
 
     def add_command(self, command: type[Command]) -> type[Command]:
         """Register a console command on this application.
@@ -1459,7 +1628,25 @@ class SilloApp:
 
         if scope["type"] == "lifespan":
             await self.handle_lifespan(receive, send)
-        elif scope["type"] in ["http", "websocket"]:
+            return
+
+        if scope["type"] in ("http", "websocket"):
+            if self._root_path:
+                scope["root_path"] = self._root_path + scope.get("root_path", "")
+                # If the proxy forwarded the prefix in the path (it did not
+                # strip it itself), move it into root_path so mounts and route
+                # matching see the tail. A proxy that already stripped it
+                # leaves `path` not starting with the prefix, and this is a
+                # no-op.
+                if scope["path"].startswith(self._root_path):
+                    scope["path"] = scope["path"][len(self._root_path) :] or "/"
+            if (
+                self._force_https
+                and scope["type"] == "http"
+                and _request_scheme(scope) == "http"
+            ):
+                await _https_redirect(scope, send)
+                return
             await self.handle_request(scope, receive, send)
 
     def get(
@@ -3025,6 +3212,41 @@ class SilloApp:
         """
         return self.router.get_all_routes()
 
+    def print_routes(self, *, file: Any | None = None) -> None:
+        """Print every registered route as an aligned table.
+
+        Walks the router and all mounted sub-routers and writes
+        ``METHODS  PATH  handler  (name)`` rows to ``file`` (stdout by
+        default). Handy from a startup hook or a REPL.
+        """
+        self.router.print_routes(file=file)
+
+    def redirect(
+        self,
+        path: str,
+        to: str,
+        *,
+        status_code: int = 307,
+        name: str | None = None,
+        methods: Sequence[str] = ("GET",),
+        include_query: bool = True,
+    ) -> None:
+        """Register a redirect-only route — no handler to write.
+
+        ``app.redirect("/docs", "/docs/latest")``. Placeholders shared by both
+        sides are substituted (``app.redirect("/u/{id}", "/users/{id}")``).
+        The default 307 preserves the method; use ``301``/``308`` for a
+        permanent move. See :meth:`Router.redirect`.
+        """
+        self.router.redirect(
+            path,
+            to,
+            status_code=status_code,
+            name=name,
+            methods=methods,
+            include_query=include_query,
+        )
+
     def ws_route(
         self,
         path: Annotated[
@@ -3043,6 +3265,13 @@ class SilloApp:
                     await websocket.send("Welcome to the chat!")
             """),
         ] = None,
+        priority: Annotated[
+            int,
+            Doc(
+                "Match-ordering weight. Tried in descending priority, then by "
+                "path specificity, then registration order. Defaults to 0."
+            ),
+        ] = 0,
     ):
         """
         Register a WebSocket route with the application.
@@ -3051,6 +3280,7 @@ class SilloApp:
             path (str): URL path pattern for the WebSocket route.
             handler (Callable): Async handler function for WebSocket connections.
                 Example: async def chat_handler(websocket, path): pass
+            priority (int): Match-ordering weight for the route. Defaults to 0.
 
         Returns:
             Callable: A decorator to register the WebSocket route.
@@ -3058,6 +3288,7 @@ class SilloApp:
         return self.router.ws_route(
             path=path,
             handler=handler,
+            priority=priority,
         )
 
     def __str__(self) -> str:

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0a1}/sillo/core/converters.py

@@ -5,6 +5,7 @@ Implemented from Starlette.
 
 from __future__ import annotations
 
+import datetime as _datetime
 import math
 import re
 import typing
@@ -516,6 +517,116 @@ class SlugConvertor(Convertor[str]):
         return value
 
 
+class BoolConvertor(Convertor[bool]):
+    """Converter for boolean path parameters.
+
+    Matches the words a URL commonly carries for a flag —
+    ``true``/``false``, ``1``/``0``, ``yes``/``no``, ``on``/``off`` — in any
+    case, and hands the handler a real ``bool``. ``to_string`` normalises back
+    to ``"true"`` / ``"false"``.
+    """
+
+    regex = "(?i:true|false|1|0|yes|no|on|off)"
+
+    _TRUE = frozenset({"true", "1", "yes", "on"})
+
+    def convert(self, value: str) -> bool:
+        return value.lower() in self._TRUE
+
+    def to_string(self, value: bool) -> str:
+        return "true" if value else "false"
+
+
+class DateConvertor(Convertor[_datetime.date]):
+    """Converter for ISO 8601 calendar dates, ``YYYY-MM-DD``.
+
+    ``/reports/{day:date}`` binds ``day`` as a ``datetime.date``. A
+    syntactically valid but impossible date (``2026-02-30``) matches the regex
+    but raises ``ValueError`` in ``convert``, which the router surfaces the
+    same way it does a bad ``int``.
+    """
+
+    regex = r"[0-9]{4}-[0-9]{2}-[0-9]{2}"
+
+    def convert(self, value: str) -> _datetime.date:
+        return _datetime.date.fromisoformat(value)
+
+    def to_string(self, value: _datetime.date) -> str:
+        return value.isoformat()
+
+
+class DateTimeConvertor(Convertor[_datetime.datetime]):
+    """Converter for ISO 8601 timestamps.
+
+    Accepts ``2026-09-10T13:45:00``, an optional fractional second, and an
+    optional ``Z`` or ``±HH:MM`` offset. ``Z`` is rewritten to ``+00:00``
+    before parsing so it works on Python 3.10 as well.
+    """
+
+    regex = (
+        r"[0-9]{4}-[0-9]{2}-[0-9]{2}[T ][0-9]{2}:[0-9]{2}(:[0-9]{2})?"
+        r"(\.[0-9]+)?(Z|[+-][0-9]{2}:[0-9]{2})?"
+    )
+
+    def convert(self, value: str) -> _datetime.datetime:
+        return _datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+    def to_string(self, value: _datetime.datetime) -> str:
+        return value.isoformat()
+
+
+class ULIDConvertor(Convertor[str]):
+    """Converter for ULIDs — 26 Crockford base32 characters.
+
+    Kept as a validated ``str`` rather than a bespoke type, so it drops into a
+    handler and a database column without a conversion either side. Matching is
+    case-insensitive; ``to_string`` upper-cases, which is the canonical form.
+    """
+
+    regex = r"[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}"
+
+    def convert(self, value: str) -> str:
+        return value.upper()
+
+    def to_string(self, value: str) -> str:
+        value = str(value)
+        if not re.fullmatch(self.regex, value):
+            raise ValueError(f"Invalid ULID: {value}")
+        return value.upper()
+
+
+class AlphaConvertor(Convertor[str]):
+    """Converter for a run of ASCII letters, ``[A-Za-z]+`` — no digits, no
+    separators. Narrower than ``str``, so ``/tags/{name:alpha}`` will not
+    swallow ``/tags/2026``."""
+
+    regex = "[A-Za-z]+"
+
+    def convert(self, value: str) -> str:
+        return value
+
+    def to_string(self, value: str) -> str:
+        value = str(value)
+        assert value.isalpha(), "Must be ASCII letters only"
+        return value
+
+
+class AlnumConvertor(Convertor[str]):
+    """Converter for a run of ASCII letters and digits, ``[A-Za-z0-9]+`` — no
+    hyphens, dots or spaces. The right fit for reference codes and short
+    handles that are looser than a slug but still one opaque token."""
+
+    regex = "[A-Za-z0-9]+"
+
+    def convert(self, value: str) -> str:
+        return value
+
+    def to_string(self, value: str) -> str:
+        value = str(value)
+        assert value.isalnum(), "Must be ASCII letters and digits only"
+        return value
+
+
 CONVERTOR_TYPES: dict[str, Convertor[typing.Any]] = {
     "str": StringConvertor(),
     "path": PathConvertor(),
@@ -523,6 +634,12 @@ CONVERTOR_TYPES: dict[str, Convertor[typing.Any]] = {
     "float": FloatConvertor(),
     "uuid": UUIDConvertor(),
     "slug": SlugConvertor(),
+    "bool": BoolConvertor(),
+    "date": DateConvertor(),
+    "datetime": DateTimeConvertor(),
+    "ulid": ULIDConvertor(),
+    "alpha": AlphaConvertor(),
+    "alnum": AlnumConvertor(),
 }
 """Default registry of built-in URL path converter instances.