Module

pages.types

Data models for filesystem-based page routing.

Immutable frozen dataclasses representing discovered layouts, context providers, and page routes. Built once at app startup during discovery.

4Classes

Classes

LayoutInfo 3 ▼
A layout template discovered in the filesystem. Each ``_layout.html`` declares a shell with a ``{%…

A layout template discovered in the filesystem.

Each_layout.html declares a shell with a {% block content %} slot and a{# target: element_id #}comment declaring which DOM element it owns.

Attributes

Name Type Description
template_name str

Template name for kida (relative to pages root).
target str

DOM element ID this layout renders into."body" for the root layout, "app-content"for nested.
depth int

Nesting depth (0 = root).
LayoutChain 2 ▼
Ordered sequence of layouts from root (outermost) to deepest. The chain determines rendering depth…

Ordered sequence of layouts from root (outermost) to deepest.

The chain determines rendering depth based onHX-Target:

  • Full page: render all layouts nested
  • HX-Target: #app-content: find the layout that owns app-content, render from the next layout down
  • Fragment: render just the targeted block

Attributes

Name Type Description
layouts tuple[LayoutInfo, ...] —

Methods

find_start_index_for_target 1 int | None ▼
Find the layout index to start rendering from for a given HX-Target. Each layo…
def find_start_index_for_target(self, htmx_target: str | None) -> int | None

Find the layout index to start rendering from for a given HX-Target.

Each layout declares{# target: element_id #}— the DOM element it renders into. WhenHX-Targetmatches a layout's target, we render from that layout onward (it produces the content that fills the targeted element).

Returns the index of the matched layout, orNoneif the target doesn't match any layout (treat as fragment).

Parameters
Name Type Description
htmx_target —
Returns
int | None
ContextProvider 3 ▼
A ``_context.py`` file's context function. Each provider is an async or sync function that receive…

A_context.pyfile's context function.

Each provider is an async or sync function that receives path parameters and returns a dict of context variables.

Attributes

Name Type Description
module_path str

Filesystem path to the_context.pyfile.
func Callable[..., dict[str, Any] | Awaitable[dict[str, Any]]]

Thecontext()callable from the module.
depth int

Nesting depth (0 = root).
PageRoute 7 ▼
A discovered page route with its layout chain and context providers. Built during filesystem disco…

A discovered page route with its layout chain and context providers.

Built during filesystem discovery. Used bymount_pages()to register routes with the chirp app.

Attributes

Name Type Description
url_path str

URL pattern (e.g.,/doc/{doc_id}).
handler Callable[..., Any]

The route handler callable.
methods frozenset[str]

HTTP methods (e.g.,frozenset({"GET"})).
layout_chain LayoutChain

The sequence of layouts wrapping this route.
context_providers tuple[ContextProvider, ...]

Context functions to run, ordered root-first.
template_name str | None

Template to render (for page routes with templates).
name str | None

Optional route name.