Skip to content

Route URLs

Source: ui/route_url.py

Utilities for parsing, constructing, and comparing application routes and their query parameters. Used by Navigation API and the router.

Parse, build, and compare application route URLs.

route_path 

route_path(route: str | None) -> str

Extract the path component of a route URL.

Parameters:

Name Type Description Default
route str | None

Route URL, or None to use the root route.

 required

Returns:

Type Description
str

The URL path component.
Source code in src/learning_app/ui/route_url.py 
 6
 7
 8
 9
10
11
12
13
14
15
def route_path(route: str | None) -> str:
    """Extract the path component of a route URL.

    Args:
        route: Route URL, or ``None`` to use the root route.

    Returns:
        The URL path component.
    """
    return urlparse(route or "/").path

route_params 

route_params(route: str | None) -> dict[str, str]

Decode the first value of each route query parameter.

Parameters:

Name Type Description Default
route str | None

Route URL to parse. None is treated as an empty URL.

 required

Returns:

Type Description
dict[str, str]

A mapping of query parameter names to decoded string values.
Source code in src/learning_app/ui/route_url.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def route_params(route: str | None) -> dict[str, str]:
    """Decode the first value of each route query parameter.

    Args:
        route: Route URL to parse. ``None`` is treated as an empty URL.

    Returns:
        A mapping of query parameter names to decoded string values.
    """
    parsed = urlparse(route or "")
    if not parsed.query:
        return {}
    return {
        key: unquote(values[0])
        for key, values in parse_qs(parsed.query, keep_blank_values=True).items()
        if values
    }

build_route 

build_route(path: str, **params: object) -> str

Build a route URL from a path and optional query parameters.

Parameters:

Name Type Description Default
path str

Route path to preserve as the URL base.

 required
**params object

Query parameter values. None values are omitted and all other values are converted to strings.

 {}

Returns:

Type Description
str

The path, followed by an encoded query string when parameters remain.
Source code in src/learning_app/ui/route_url.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def build_route(path: str, **params: object) -> str:
    """Build a route URL from a path and optional query parameters.

    Args:
        path: Route path to preserve as the URL base.
        **params: Query parameter values. ``None`` values are omitted and all
            other values are converted to strings.

    Returns:
        The path, followed by an encoded query string when parameters remain.
    """
    query_params = {key: str(value) for key, value in params.items() if value is not None}
    if not query_params:
        return path
    return f"{path}?{urlencode(query_params, quote_via=quote)}"

routes_match 

routes_match(left: str | None, right: str | None) -> bool

Compare two routes by path and decoded query parameters.

Raw string equality is accepted first. Otherwise the paths and decoded query maps are compared so browser history URLs that differ only in percent-encoding (e.g. C%3A vs C:) still match stacked views.

Parameters:

Name Type Description Default
left str | None

First route, with None treated as an empty string.

 required
right str | None

Second route, with None treated as an empty string.

 required

Returns:

Type Description
bool

True when both routes refer to the same path and parameters.
Source code in src/learning_app/ui/route_url.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def routes_match(left: str | None, right: str | None) -> bool:
    """Compare two routes by path and decoded query parameters.

    Raw string equality is accepted first. Otherwise the paths and decoded
    query maps are compared so browser history URLs that differ only in
    percent-encoding (e.g. ``C%3A`` vs ``C:``) still match stacked views.

    Args:
        left: First route, with ``None`` treated as an empty string.
        right: Second route, with ``None`` treated as an empty string.

    Returns:
        ``True`` when both routes refer to the same path and parameters.
    """
    left_route = left or ""
    right_route = right or ""
    if left_route == right_route:
        return True
    return route_path(left_route) == route_path(right_route) and route_params(left_route) == route_params(right_route)