Web integration

One framework-neutral route: either a handler or nested children.

A child's full path is the parent's path followed by the child's (plain concatenation; end a parent path with /). {name} segments in the path become keyword arguments of the handler.

handler_async optionally carries an async def twin of handler (same signature and behavior). Adapters that run an event loop (ASGI) serve the route through the twin, awaiting it natively, while the plain handler stays what the sync hosts (WSGI, sync Django) mount and run. Only routes that need both worlds carry it; a route table meant solely for ASGI can simply pass an async def function as handler.

Example::

URLRoute("cache/{class_id}.{script_type}", handler=serve_script, name="citry_cached_script")
URLRoute("ext/", children=[URLRoute("my_ext/status", handler=status)])

path: str

handler: Callable[..., RouteResponse | Awaitable[RouteResponse]] | None

handler_async: Callable[..., Awaitable[RouteResponse]] | None

children: tuple[URLRoute, ...]

name: str | None

methods: tuple[str, ...]

extra: dict[str, Any]

A framework-neutral view of one HTTP request, passed to route handlers.

Each web adapter (citry.contrib.asgi, citry.contrib.wsgi, the Django patterns, ...) builds this from its host's request, so a handler reads the same fields no matter which framework serves it. Anything host-specific stays reachable through native.

Attributes

• method str - The HTTP method, uppercase (`"GET"`, `"POST"`, ...).
• path str - The full URL path of the request, including the prefix the route table is mounted under (e.g. `"/citry/citry.js"`).
• query Mapping[str, tuple[str, ...]] - The query-string parameters. Each key maps to all values it was sent with, in order, so repeated keys are preserved.
• headers RouteHeaders - The HTTP request headers; lookups ignore case.
• body bytes - The raw request body. Empty for bodyless methods such as GET.
• content_type str - The `Content-Type` header value, or `""` when the request names none.
• native Any - The untouched host request object: the ASGI scope, the WSGI environ, or Django's `HttpRequest`.

method: str

path: str

query: Mapping[str, tuple[str, ...]]

headers: RouteHeaders

body: bytes

content_type: str

native: Any

What a route handler returns; adapters translate it to the host's response type.

Attributes

• content str | bytes - The response body, as text or raw bytes.
• content_type str - The `Content-Type` header value to send.
• status int - The HTTP status code.
• headers tuple[tuple[str, str], ...] - Extra response headers, as `(name, value)` pairs; adapters send them in addition to `Content-Type`. A name may repeat (e.g. two `Set-Cookie` lines): the ASGI and WSGI adapters send every pair, while the Django adapter raises `ValueError` on a repeated name, because Django's response object holds one value per header name.

content: str | bytes

content_type: str

status: int

headers: tuple[tuple[str, str], ...]

body: bytes

A read-only mapping of HTTP header names to values; lookups ignore case.

Built from (name, value) pairs. Iteration yields the names lowercased, and a header sent multiple times has its values joined with ", " (the HTTP rule for repeatable headers).

Example

headers = RouteHeaders([("Content-Type", "application/json")])
headers["content-type"]  # "application/json"
headers["CONTENT-TYPE"]  # "application/json"