types - Chirp

LayoutPreset 8 ▼

Named defaults for filesystem layout metadata. Presets let apps and extensions encode a convention…

Named defaults for filesystem layout metadata.

Presets let apps and extensions encode a conventional shell shape once and keep_layout.htmlfocused on route-tree intent. Explicit comments in the layout always override preset defaults.

Attributes

Name	Type	Description
`name`	`str`	—
`target`	`str \| None`	—
`domain_name`	`str \| None`	—
`shell_name`	`str \| None`	—
`swap_scope_name`	`str \| None`	—
`outlet_target_id`	`str \| None`	—
`frame_targets`	`frozenset[str] \| None`	—
`outlet_mode`	`OutletSwapMode \| None`	—

RouteMeta 7 ▼

Route metadata from ``_meta.py``. All fields optional. Static META or meta() callable provides val…

Route metadata from_meta.py.

All fields optional. Static META or meta() callable provides values.

Attributes

Name	Type	Description
`title`	`str \| None`	—
`section`	`str \| None`	—
`breadcrumb_label`	`str \| None`	—
`shell_mode`	`str \| None`	—
`auth`	`str \| None`	—
`cache`	`str \| None`	—
`tags`	`tuple[str, ...]`	—

TabItem 5 ▼

A tab item for section navigation (Chirp ``Section`` + chirp-ui route tabs). Optional fields match…

A tab item for section navigation (ChirpSection+ chirp-ui route tabs).

Optional fields match the dict shape consumed byrender_route_tabs/ tab_is_active in chirp-ui: matchcontrols active state for nested URLs. SeeSHELL-TABS-CONTRACT.mdin chirp-ui for the full shell to route-tabs data flow.

Attributes

Name	Type	Description
`label`	`str`	—
`href`	`str`	—
`icon`	`str \| None`	—
`badge`	`str \| None`	—
`match`	`TabMatchMode`	—

ActionInfo 2 ▼

A named action from ``_actions.py``.

A named action from_actions.py.

Attributes

Name	Type	Description
`name`	`str`	—
`func`	`Callable[..., Any]`	—

Section 6 ▼

A named section with tab items and breadcrumb prefix. Register via ``app.register_section()`` befo…

A named section with tab items and breadcrumb prefix.

Register viaapp.register_section() before mount_pages(); tab items flow to chirp-uirender_route_tabs through resolve_section_context.

Attributes

Name	Type	Description
`id`	`str`	—
`label`	`str`	—
`tab_items`	`tuple[TabItem, ...]`	—
`breadcrumb_prefix`	`tuple[dict[str, str], ...]`	—
`active_prefixes`	`tuple[str, ...]`	—

Methods

is_active 1 bool ▼

Return True if *path* matches any of this section's active prefixes.

def is_active(self, path: str) -> bool

Parameters

Name	Type	Description
`path`	`—`

Returns

bool

LayoutInfo 9 ▼

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.

Optional comments (see filesystem routing docs) declare navigation and swap metadata for boosted navigation helpers:

{# domain: name #}— author-facing navigation domain boundary.
{# shell: name #}— this layout introduces a shell boundary.
{# swap_scope: name #} — symbolic scope (e.g. shell, page).
{# outlet: element_id #}— primary navigation outlet for this level (defaults to target when omitted).
{# outlet_mode: compose | replace #}— how boosted swaps targeting {# outlet: #} relate to layout composition (default compose).
{# frames: id1, id2 #}— optional frame ids (immutable chrome).

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).
`shell_name`	`str \| None`	Optional shell boundary label introduced by this layout. Descendant routes inherit the full shell path from ancestor layouts. Shells describe persistent UI boundaries; they only imply navigation intent when no explicit domain metadata is declared.
`swap_scope_name`	`str \| None`	Optional symbolic scope for`resolve_navigation_swap`.
`outlet_target_id`	`str \| None`	Optional primary outlet id for this layout level.
`frame_targets`	`frozenset[str] \| None`	Optional ids treated as non-swapped frame for validation.
`outlet_mode`	`OutletSwapMode`	`compose` (re-run layout shell for the fragment response) vs `replace` (skip the matched outer layout while still rendering any descendant layouts below it; use for scroll/marketing shells where the outlet wraps the primary `{% block content %}`region).
`domain_name`	`str \| None`	Optional navigation domain label introduced by this layout. When any layout in the chain declares a domain, navigation helpers use domain ancestry instead of inferring intent from shell ancestry.

LayoutChain 11 ▼

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

domain_layers 0 tuple[tuple[str, int], .… ▼

Return ``(domain_name, layout_index)`` for explicit domain boundaries.

property

def domain_layers(self) -> tuple[tuple[str, int], ...]

Returns

tuple[tuple[str, int], ...]

domain_path 0 tuple[str, ...] ▼

Return the explicit navigation-domain ancestry for this route.

property

def domain_path(self) -> tuple[str, ...]

Returns

tuple[str, ...]

shell_layers 0 tuple[tuple[str, int], .… ▼

Return ``(shell_name, layout_index)`` for each declared shell boundary.

property

def shell_layers(self) -> tuple[tuple[str, int], ...]

Returns

tuple[tuple[str, int], ...]

shell_path 0 tuple[str, ...] ▼

Return the inherited shell ancestry for this route. The path is derived from b…

property

def shell_path(self) -> tuple[str, ...]

Return the inherited shell ancestry for this route.

The path is derived from boundary layouts that declare {# shell: name #}. Layouts without a shell annotation participate in composition but do not introduce a new shell boundary.

Returns

tuple[str, ...]

navigation_domain_layers 0 tuple[tuple[str, int], .… ▼

Return the ancestry used for route-aware navigation decisions. Explicit ``{# d…

property

def navigation_domain_layers(self) -> tuple[tuple[str, int], ...]

Return the ancestry used for route-aware navigation decisions.

Explicit{# domain: #}annotations win. When no layout in the chain declares a domain, fall back to legacy shell ancestry for backward compatibility.

Returns

tuple[tuple[str, int], ...]

navigation_domain_path 0 tuple[str, ...] ▼

Return the effective navigation-domain path for this route.

property

def navigation_domain_path(self) -> tuple[str, ...]

Returns

tuple[str, ...]

layout_index_for_shell_depth 1 int | None ▼

Return the layout index for the Nth shell boundary, or ``None``.

def layout_index_for_shell_depth(self, shell_depth: int) -> int | None

Parameters

Name	Type	Description
`shell_depth`	`—`

Returns

int | None

layout_index_for_navigation_depth 1 int | None ▼

Return the layout index for the Nth navigation-domain boundary.

def layout_index_for_navigation_depth(self, navigation_depth: int) -> int | None

Parameters

Name	Type	Description
`navigation_depth`	`—`

Returns

int | None

start_index_for_htmx_target 2 int | None ▼

Return the layout start index for a boosted navigation target. ``omit_outer_la…

def start_index_for_htmx_target(self, htmx_target: str | None, *, omit_outer_layout_targets: frozenset[str] = frozenset()) -> int | None

Return the layout start index for a boosted navigation target.

omit_outer_layout_targetscontains target ids whose registered fragment config wants to skip the matched outer layout while still rendering any descendant shells.

Parameters

Name	Type	Description
`htmx_target`	`—`
`omit_outer_layout_targets`	`—`	Default:`frozenset()`

Returns

int | None

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).

Matches{# target: element_id #}— the DOM node the layout renders into — and{# outlet: element_id #}— the primary boosted-navigation outlet (e.g.mainfor app shells with hx-select="#page-content").

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.py`file.
`func`	`Callable[..., dict[str, Any] \| Awaitable[dict[str, Any]]]`	The`context()`callable from the module.
`depth`	`int`	Nesting depth (0 = root).

PageRoute 12 ▼

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.
`meta`	`RouteMeta \| None`	—
`meta_provider`	`MetaProvider \| None`	—
`actions`	`tuple[ActionInfo, ...]`	—
`viewmodel_provider`	`Callable[..., Any] \| None`	—
`kind`	`RouteKind`	—

PageHandlerFinding 4 ▼

A diagnostic finding from page-handler discovery. Emitted when a ``page.py`` file either has no re…

A diagnostic finding from page-handler discovery.

Emitted when apage.pyfile either has no recognized HTTP method handler (kind="missing") or defines a function whose name looks like a handler attempt but isn't recognized (kind="typo").

Surfaced toapp.check() as page_handlerscontract issues; the severity mapping (ERROR for missing, WARNING for typo) is applied there, not here.

Attributes

Name	Type	Description
`kind`	`PageHandlerFindingKind`	`"missing"` or `"typo"`.
`file`	`str`	Filesystem path to the`page.py`that produced the finding.
`url_path`	`str`	URL pattern the`page.py`would have served.
`function_name`	`str \| None`	For`kind="typo"`, the mis-named function; `None`for missing.

`pages.types`

Classes

Attributes

Attributes

Attributes

Attributes

Attributes

Methods

Parameters

Returns

Attributes

Attributes

Methods

Returns

Returns

Returns

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Attributes

Attributes

Attributes