routes

The Router that maps URLs to handler functions.

Defines URL normalization helpers (normalize_url, clean_url) and the Router class, which stores registered routes with their introspected signatures and prepares handler arguments by running the parameter pipeline (collect, normalize, bind, convert, diagnose) over each incoming request.

Router() dataclass

Map URL paths to route handler functions and prepare request arguments.

Attributes:

Name	Type	Description
routes	dict[str, Callable]	Dictionary mapping normalized URL strings to callable handlers.
route_functions	dict[str, Callable]	Dictionary mapping cleaned function-style names to the same handlers, used for name-based lookup in get_route.
signatures	dict[str, RouteSignatureSpec]	Dictionary mapping normalized URL strings to RouteSignatureSpec data.

add_route(url, func)

Register a route handler for the given URL.

Parameters:

Name	Type	Description	Default
url	str	Route URL path.	required
func	Callable	Handler function to call for requests to this URL.	required

Returns:

Type	Description
dict[str, Any]	A dict with the registered "url" and the handler's "signature" rendered as a string.

build_argument_representation(signature, args, kwargs)

Generate a string representation of function call arguments.

Parameters:

Name	Type	Description	Default
signature	RouteSignatureSpec	Introspection data for the target function.	required
args	list[Any]	Positional arguments list.	required
kwargs	dict[str, Any]	Keyword arguments dictionary.	required

Returns:

Name	Type	Description
str	str	Function signature string like "func(arg1, kwarg=val2)".

clear()

Remove all registered routes and signatures.

get_route(url)

Retrieve the handler function for a given URL.

Parameters:

Name	Type	Description	Default
url	str	Route URL path to look up.	required

Returns:

Type	Description
Callable | None	Optional[Callable]: Handler function or None if not found.

get_signature(request)

Retrieve function signature metadata for a request URL.

Parameters:

Name	Type	Description	Default
request	Request	Request with URL to look up.	required

Returns:

Name	Type	Description
RouteSignatureSpec	RouteSignatureSpec	Signature metadata for the route.

Raises:

Type	Description
ValueError	If no signature is registered for the URL.

has_route(url)

Check whether a route exists for the given URL.

Parameters:

Name	Type	Description	Default
url	str	Route URL path to check.	required

Returns:

Name	Type	Description
bool	bool	True if route exists, False otherwise.

prepare_arguments(request, current_state, configuration, extra_dependencies)

Prepare positional and keyword arguments for route invocation.

Runs the deterministic five-stage parameter pipeline:

1. Collect: build one payload (with per-key source provenance) from the event detail, component arguments, form fields, and framework metadata.
2. Normalize: apply component-declared aliases.
3. Bind: match payload values to the route signature, understanding defaults, injected dependencies (state, configuration), and var-keyword parameters.
4. Convert: strictly convert explicitly typed parameters through the shared converter registry; pass untyped parameters through raw.
5. Diagnose: raise on missing required parameters and failed conversions; warn on unused and colliding payload keys.

Parameters:

Name	Type	Description	Default
request	Request	Incoming client request with form data.	required
current_state	SiteState	Current application state (injected if expected).	required
configuration	ClientServerConfiguration	Server configuration context.	required
extra_dependencies	dict[str, Any]	Framework values injected by parameter name.	required

Returns:

Type	Description
tuple[list[Any], dict[str, Any], str, tuple[dict, ...]]	Tuple of (args list, kwargs dict, representation string, per-parameter provenance dicts for the debug panel).

Raises:

Type	Description
ParameterBindingError	If required parameters are missing or values cannot be converted to the annotated types.

preprocess_button_press(request, kwargs)

Extract button metadata from the request.

Reads button_pressed from the Request object (set by the client). Falls back to extracting from kwargs for backward compatibility with older clients (e.g., the TypeScript/Skulpt bridge).

Parameters:

Name	Type	Description	Default
request	Request	The incoming request with button_pressed field.	required
kwargs	dict[str, Any]	Form data dict (modified to remove button key if present as fallback).	required

Returns:

Name	Type	Description
str	str	Button namespace/identifier, or empty string if no button.

report_diagnostics(request, diagnostics)

Log warning diagnostics and raise if any errors were produced.

Parameters:

Name	Type	Description	Default
request	Request	Associated request for error context.	required
diagnostics	tuple[RouteDiagnostic, ...]	Diagnostics collected across the pipeline stages.	required

Raises:

Type	Description
ParameterBindingError	If any error-severity diagnostics exist.

reset()

Reset router state. Note that this does not remove routes or signatures, because those are meant to survive server resets.

Currently, this method is a no-op.

clean_url(url)

Turns a URL into a heavily normalized form for matching against route function names, instead of explicit URLs.

The following transformations are applied: - Strips leading and trailing whitespace. - Strips leading and trailing slashes. - Internal slashes are converted to underscores. - Single dots are ignored. - Double dots delete the previous path segment, if any. - Non-valid characters are removed (only alphanumeric characters and underscores are kept).

normalize_url(url)

Turns a URL into a normalized form for consistent route matching.

This function performs the following transformations: - Strips leading and trailing whitespace. - Strips trailing slashes. - Prepends "/" if the URL is non-empty and does not already start with "/". - Converts empty URLs to "/index". - Single dots are ignored - Double dots delete the previous path segment, if any.