Router core

wybthon.router_core¶

router_core ¶

Core, browser-agnostic path matching and route resolution helpers.

This module is the algorithmic heart of Wybthon's router. It compiles route patterns to regular expressions, matches them against a pathname, and resolves the most specific match. Because it has no browser dependencies, it can be used in tests, in tooling, and on the server side.

Public surface:

RouteSpec: minimal dataclass used to describe routes for pure-Python tests.
resolve: resolve a pathname to the best matching route and params.

RouteSpec `dataclass` ¶

RouteSpec(path: str, children: Optional[List['RouteSpec']] = None)

Minimal route spec used for pure-Python resolution in tests and tools.

Attributes:

Name	Type	Description
`path`	`str`	Route pattern (e.g. `"/users/:id"`).
`children`	`Optional[List['RouteSpec']]`	Optional nested routes whose paths are joined with this route's `path`.

resolve ¶

resolve(routes: List[Any], pathname: str, base_path: str = '') -> Optional[Tuple[Any, Dict[str, Any]]]

Resolve a pathname to the best matching route and params.

The router prefers the most specific (longest) match and honors a base_path prefix when provided.

Parameters:

Name	Type	Description	Default
`routes`	`List[Any]`	Flat or nested route specs (any object exposing `path` and optional `children`).	required
`pathname`	`str`	The current URL pathname.	required
`base_path`	`str`	Optional base path stripped from `pathname` before matching. When `pathname` does not start with `base_path`, the function returns `None`.	`''`

Returns:

Type	Description
`Optional[Tuple[Any, Dict[str, Any]]]`	A tuple `(route, payload)` where `payload` contains a
`Optional[Tuple[Any, Dict[str, Any]]]`	`"params"` dict, or `None` when no route matches.

What's in this module¶

router_core contains the browser-agnostic path matching engine used by wybthon.router. It exposes:

RouteSpec: a normalized route description used internally by Route.
resolve: match a path against a list of route specs and return the matched chain plus extracted params.

You don't usually call this module directly. Write Route declarations and let Router resolve them. Use router_core if you need to test routing logic outside a browser environment or build custom navigation tooling.

Path patterns¶

Pattern	Matches	Notes
`/users`	`/users`	Static segment.
`/users/:id`	`/users/42`	`:id` becomes a string param.
`/files/*splat`	`/files/a/b/c`	Splat captures the remainder as a single string.
`/(public\|private)`	`/public` or `/private`	Alternation works in the underlying regex.

Param values are URL-decoded before being passed to components.