Module

pages.discovery

Filesystem route discovery for the pages/ directory.

Walks the pages directory tree and discovers:

  • _layout.htmlfiles as layout templates
  • _context.pyfiles as context providers
  • .pyroute files as handler modules

Directory names wrapped in{braces}become path parameters. page.py maps to the directory URL; other .pyfiles append their stem to the path.

Modeled on Bengal's ContentDiscovery but for routes instead of content.

14Functions

Functions

default_route_name 1 str ▼
Derive a dotted default route name from a URL path. Parameter braces are strip…
def default_route_name(url_path: str) -> str

Derive a dotted default route name from a URL path.

Parameter braces are stripped and the param name is kept bare:

/contacts/{contact_id} → "contacts.contact_id". Typed params drop the type:/{id:int} → "id". The root path/ becomes "index"so every route has a non-empty name.

Parameters
Name Type Description
url_path str
Returns
str
discover_pages 2 list[PageRoute] ▼
Walk a pages directory and discover all routes.
def discover_pages(pages_dir: str | Path, *, layout_presets: Mapping[str, LayoutPreset] | None = None) -> list[PageRoute]
Parameters
Name Type Description
pages_dir str | Path

Path to thepages/directory.
layout_presets Mapping[str, LayoutPreset] | None Default:None
Returns
list[PageRoute]
discover_pages_with_findings 2 tuple[list[PageRoute], l… ▼
Walk a pages directory and discover routes plus handler-discovery findings. Sa…
def discover_pages_with_findings(pages_dir: str | Path, *, layout_presets: Mapping[str, LayoutPreset] | None = None) -> tuple[list[PageRoute], list[PageHandlerFinding]]

Walk a pages directory and discover routes plus handler-discovery findings.

Same asdiscover_pages() but also returns a list of PageHandlerFinding objects describing page.pyfiles that have no recognised handler or define handler-shaped typos. Findings are consumed by thepage_handlerscontract check.

Parameters
Name Type Description
pages_dir str | Path
layout_presets Mapping[str, LayoutPreset] | None Default:None
Returns
tuple[list[PageRoute], list[PageHandlerFinding]]
_walk_directory 9 None ▼
Recursively walk a directory, discovering routes and layouts.
def _walk_directory(directory: Path, root: Path, *, url_parts: list[str], layouts: list[LayoutInfo], context_providers: list[ContextProvider], depth: int, routes: list[PageRoute], findings: list[PageHandlerFinding], layout_presets: Mapping[str, LayoutPreset]) -> None
Parameters
Name Type Description
directory Path

Current directory being walked.
root Path

Root pages directory (for computing template paths).
url_parts list[str]

URL path segments accumulated so far.
layouts list[LayoutInfo]

Layout chain accumulated from parent directories.
context_providers list[ContextProvider]

Context providers from parent directories.
depth int

Current nesting depth.
routes list[PageRoute]

Accumulator for discovered routes.
findings list[PageHandlerFinding]
layout_presets Mapping[str, LayoutPreset]
_infer_route_kind 2 RouteKind ▼
Infer route kind from file combination. Informational only.
def _infer_route_kind(*, has_template: bool, is_param_dir: bool) -> RouteKind
Parameters
Name Type Description
has_template bool
is_param_dir bool
Returns
RouteKind
_parse_layout_metadata 2 dict[str, Any] ▼
Read ``{# target #}`` and optional shell scope comments from a layout. Support…
def _parse_layout_metadata(layout_file: Path, *, layout_presets: Mapping[str, LayoutPreset]) -> dict[str, Any]

Read{# target #}and optional shell scope comments from a layout.

Supported annotations::

{# preset: preset_name #}
{# target: element_id #}
{# domain: navigation_domain #}
{# shell: shell_name #}
{# swap_scope: symbolic_name #}
{# outlet: element_id #}
{# outlet_mode: compose | replace #}
{# frames: id1, id2 #}
Parameters
Name Type Description
layout_file Path
layout_presets Mapping[str, LayoutPreset]
Returns
dict[str, Any]
_resolve_layout_preset 3 LayoutPreset | None ▼
Resolve a named layout preset or raise for unknown names.
def _resolve_layout_preset(layout_file: Path, preset_name: str | None, layout_presets: Mapping[str, LayoutPreset]) -> LayoutPreset | None
Parameters
Name Type Description
layout_file Path
preset_name str | None
layout_presets Mapping[str, LayoutPreset]
Returns
LayoutPreset | None
_normalize_outlet_mode 1 OutletSwapMode ▼
Normalize ``{# outlet_mode: #}`` token to a known mode.
def _normalize_outlet_mode(raw: str | OutletSwapMode | None) -> OutletSwapMode
Parameters
Name Type Description
raw str | OutletSwapMode | None
Returns
OutletSwapMode
_load_viewmodel 2 Any ▼
Load viewmodel() function from _viewmodel.py.
def _load_viewmodel(viewmodel_file: Path, root: Path) -> Any
Parameters
Name Type Description
viewmodel_file Path
root Path
Returns
Any
_load_actions 2 tuple[ActionInfo, ...] ▼
Load @action decorated functions from _actions.py.
def _load_actions(actions_file: Path, root: Path) -> tuple[ActionInfo, ...]
Parameters
Name Type Description
actions_file Path
root Path
Returns
tuple[ActionInfo, ...]
_load_meta 2 tuple[RouteMeta | None, … ▼
Load RouteMeta from a _meta.py file. Checks for META constant first, then meta…
def _load_meta(meta_file: Path, root: Path) -> tuple[RouteMeta | None, Any]

Load RouteMeta from a _meta.py file.

Checks for META constant first, then meta() callable. Returns (meta, meta_provider) — one will be set, the other None. Raises ValueError if _meta.py has neither META nor meta().

Parameters
Name Type Description
meta_file Path
root Path
Returns
tuple[RouteMeta | None, Any]
_dict_to_route_meta 1 RouteMeta ▼
Convert dict to RouteMeta, filling only provided keys.
def _dict_to_route_meta(d: dict[str, Any]) -> RouteMeta
Parameters
Name Type Description
d dict[str, Any]
Returns
RouteMeta
_load_context_provider 3 ContextProvider | None ▼
Load a context() function from a _context.py file. Uses path-based module name…
def _load_context_provider(context_file: Path, root: Path, depth: int) -> ContextProvider | None

Load a context() function from a _context.py file.

Uses path-based module names (_chirp_ctx_collections, etc.) so sibling directories do not overwrite each other in sys.modules.

Returns None if the module doesn't export acontextfunction.

Parameters
Name Type Description
context_file Path
root Path
depth int
Returns
ContextProvider | None
_process_route_file 11 None ▼
Load a route .py file and extract handler functions. ``page.py`` maps to the d…
def _process_route_file(file: Path, root: Path, *, url_parts: list[str], layout_chain: LayoutChain, context_providers: tuple[ContextProvider, ...], routes: list[PageRoute], findings: list[PageHandlerFinding], route_meta: RouteMeta | None = None, meta_provider: Any = None, actions: tuple[ActionInfo, ...] = (), viewmodel_provider: Any = None) -> None

Load a route .py file and extract handler functions.

page.pymaps to the directory URL. Other files append their stem to the URL path.

Handler functions are named after HTTP methods:get, post, etc.

Parameters
Name Type Description
file Path
root Path
url_parts list[str]
layout_chain LayoutChain
context_providers tuple[ContextProvider, ...]
routes list[PageRoute]
findings list[PageHandlerFinding]
route_meta RouteMeta | None Default:None
meta_provider Any Default:None
actions tuple[ActionInfo, ...] Default:()
viewmodel_provider Any Default:None