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.

10Functions

Functions

discover_pages 1 list[PageRoute] ▼
Walk a pages directory and discover all routes.
def discover_pages(pages_dir: str | Path) -> list[PageRoute]
Parameters
Name Type Description
pages_dir str | Path

Path to thepages/directory.
Returns
list[PageRoute]
_walk_directory 7 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]) -> 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.
_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_target 1 str ▼
Extract the target element ID from a layout template. Looks for ``{# target: e…
def _parse_layout_target(layout_file: Path) -> str

Extract the target element ID from a layout template.

Looks for{# target: element_id #}in the template. Defaults to"body"if not found.

Parameters
Name Type Description
layout_file Path
Returns
str
_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 10 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], 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]
route_meta RouteMeta | None Default:None
meta_provider Any Default:None
actions tuple[ActionInfo, ...] Default:()
viewmodel_provider Any Default:None