Module

pages.resolve

Page handler argument resolution and result upgrade.

Extracts the parameter-resolution and Page-to-LayoutPage logic from thepage_wrapper closure in App._register_page_handlerinto standalone, testable functions.

Resolution priority for each handler parameter:

  1. request— the Request object (by name or annotation)
  2. Path parameters — from the URL match, with type coercion
  3. Cascade context — from_context.pyproviders
  4. Service providers — registered viaapp.provide()
  5. Extractable dataclasses — from query (GET) or body (POST)
5Functions

Functions

_invoke_provider_factory 3 Any ▼
Call a service provider factory, injecting request/cascade_ctx if requested.
def _invoke_provider_factory(factory: Callable[..., Any], request: Request, cascade_ctx: dict[str, Any]) -> Any
Parameters
Name Type Description
factory Callable[..., Any]
request Request
cascade_ctx dict[str, Any]
Returns
Any
_warn_if_page_root_missing 1 None ▼
Warn about common mounted-pages fragment roots that drop page wrappers.
def _warn_if_page_root_missing(result: Any) -> None
Parameters
Name Type Description
result Any
resolve_kwargs 4 dict[str, Any] ▼
Build keyword arguments for a page handler from request context. Inspects *han…
async
async def resolve_kwargs(handler: Callable[..., Any], request: Request, cascade_ctx: dict[str, Any], service_providers: dict[type, Callable[..., Any]]) -> dict[str, Any]

Build keyword arguments for a page handler from request context.

Inspects handler's signature and resolves each parameter from the available sources in priority order. For non-GET methods, pre-reads the request body when the handler expects an extractable dataclass.

Parameters
Name Type Description
handler Callable[..., Any]

The user-defined page handler function.
request Request

The current HTTP request.
cascade_ctx dict[str, Any]

Merged context from_context.pyproviders.
service_providers dict[type, Callable[..., Any]]

Type-keyed factories fromapp.provide().
Returns
dict[str, Any]
upgrade_result 5 Any ▼
Upgrade a Page result to a LayoutPage with layout chain metadata. If *result* …
def upgrade_result(result: Any, cascade_ctx: dict[str, Any], layout_chain: LayoutChain | None, context_providers: tuple[ContextProvider, ...], request: Request | None = None) -> Any

Upgrade a Page result to a LayoutPage with layout chain metadata.

If result is aPage, merges cascade context with the page's own context and wraps it in aLayoutPagefor layout composition. If result is aSuspenseand layout_chain has layouts, wraps it in aLayoutSuspenseso the shell is composed with layouts. All other return types pass through unchanged.

Parameters
Name Type Description
result Any

The handler's return value.
cascade_ctx dict[str, Any]

Merged context from_context.pyproviders.
layout_chain LayoutChain | None

The layout chain for this page route.
context_providers tuple[ContextProvider, ...]

The context providers for this page route.
request Request | None

The current request (for LayoutSuspense fragment detection).

Default:None
Returns
Any
_merge_result_context 2 dict[str, Any] ▼
Merge page result context with cascade context, preserving shell semantics.
def _merge_result_context(cascade_ctx: dict[str, Any], result_ctx: dict[str, Any]) -> dict[str, Any]
Parameters
Name Type Description
cascade_ctx dict[str, Any]
result_ctx dict[str, Any]
Returns
dict[str, Any]