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.

5Functions

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.
_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_context_provider 2 ContextProvider | None ▼
Load a context() function from a _context.py file. Returns None if the module …
def _load_context_provider(context_file: Path, depth: int) -> ContextProvider | None

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

Returns None if the module doesn't export acontextfunction.

Parameters
Name Type Description
context_file Path
depth int
Returns
ContextProvider | None
_process_route_file 6 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]) -> 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]