orionis.http.routes.route_resolver.RouteResolver

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

Explore modules View classes

class documentation

class RouteResolver(IRouteResolver): (source)

Constructor: RouteResolver(routes, hot_cache_size, fallback)

View In Hierarchy

Resolve compiled routes using static maps and ordered dynamic buckets.

Method	`__init__`	Build lookup tables and the bounded FIFO result cache.
Method	`__raiseForUnmatchedPath`	Distinguish an unknown path from a path registered for another method.
Method	`__resolveDynamic`	Resolve dynamic candidates and cache a successful conversion.
Method	`__storeCache`	Cache a dynamic result, evicting the oldest entry at capacity.
Method	`allRoutes`	Return a fresh list of all unique compiled routes.
Method	`fallback`	Return the configured fallback handler metadata.
Method	`invalidateCache`	Clear all dynamic route results and their FIFO eviction order.
Method	`options`	Return the sorted HTTP methods whose routes match a path.
Method	`resolve`	Resolve a request method and path using prebuilt dispatch metadata.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_cache_max`	Undocumented
Instance Variable	`_cache_order`	Undocumented
Instance Variable	`_fallback`	Undocumented
Instance Variable	`_global_static`	Undocumented
Instance Variable	`_routes`	Undocumented
Instance Variable	`_tables`	Undocumented

def __init__(self, routes: dict[str, dict], hot_cache_size: int = 512, fallback: tuple | None = None): (source) ¶

Build lookup tables and the bounded FIFO result cache.

Parameters
routes:`dict[str, dict]`	Compiler output grouped by method and static/dynamic paths.
hot_cache_size:`int, optional`	Maximum dynamic results cached across all methods; zero disables caching. Defaults to 512.
fallback:`tuple \| None, optional`	Fallback handler metadata. None or `(None, None)` disables the fallback. Defaults to None.

Returns
`None`	Initialize route tables, the route inventory, and the FIFO cache.

Raises
`TypeError`	If the cache capacity is a boolean or not an integer.
`ValueError`	If the cache capacity is negative.

def __raiseForUnmatchedPath(self, method: str, path: str, depth: int) -> Never: (source) ¶

Distinguish an unknown path from a path registered for another method.

Parameters
method:`str`	Canonical request method that did not match.
path:`str`	Normalized request path.
depth:`int`	Number of path separators, or zero for the root path.

Returns
`Never`	Always raise a routing exception; never return a value.

Raises
`MethodNotAllowed`	If another method has a static or regex match for the path.
`RouteNotFound`	If no method has a static or regex match for the path.

def __resolveDynamic(self, path: str, depth: int, table: DepthTable, method: str, method_cache: dict[str, ResolvedRoute] | None) -> ResolvedRoute | None: (source) ¶

Resolve dynamic candidates and cache a successful conversion.

Parameters
path:`str`	Normalized request path.
depth:`int`	Number of path separators, or zero for the root path.
table:`DepthTable`	Dynamic route buckets for the request method.
method:`str`	Canonical request method used as part of the cache key.
method_cache:`dict[str, ResolvedRoute] \| None`	Per-method result cache, or None when caching is disabled.

Returns
`ResolvedRoute \| None`	First matching route with valid parameter conversions, or None if no candidate succeeds.

Raises
`RouteNotFound`	If a combined match lacks its identifying route marker.

def __storeCache(self, cache: dict[str, ResolvedRoute], method: str, path: str, result: ResolvedRoute): (source) ¶

Cache a dynamic result, evicting the oldest entry at capacity.

Parameters
cache:`dict[str, ResolvedRoute]`	Cache belonging to the request method.
method:`str`	Canonical request method.
path:`str`	Normalized request path.
result:`ResolvedRoute`	Immutable route resolution to retain.

Returns
`None`	Store the result and append its method/path key to the FIFO queue.

def allRoutes(self) -> list[CompiledRoute]: (source) ¶

overrides orionis.http.routes.contracts.route_resolver.IRouteResolver.allRoutes

Return a fresh list of all unique compiled routes.

Returns
`list[CompiledRoute]`	Routes deduplicated by identity in their original table traversal order. The returned list shares the compiled route objects.

def fallback(self) -> tuple | None: (source) ¶

overrides orionis.http.routes.contracts.route_resolver.IRouteResolver.fallback

Return the configured fallback handler metadata.

Returns
`tuple \| None`	Registered handler tuple, or None when no fallback is configured.

def invalidateCache(self): (source) ¶

overrides orionis.http.routes.contracts.route_resolver.IRouteResolver.invalidateCache

Clear all dynamic route results and their FIFO eviction order.

Returns
`None`	Empty per-method caches and the shared queue, preserving route tables.

def options(self, path: str) -> list[str]: (source) ¶

overrides orionis.http.routes.contracts.route_resolver.IRouteResolver.options

Return the sorted HTTP methods whose routes match a path.

Inspect path patterns without converting parameters.

Parameters
path:`str`	Request path to normalize before checking registered methods.

Returns
`list[str]`	Matching methods, adding HEAD for GET and OPTIONS for any match. Return GET, HEAD, and OPTIONS for an unmatched path with a fallback, or an empty list when no fallback is configured.

def resolve(self, method: str, path: str) -> ResolvedRoute: (source) ¶

overrides orionis.http.routes.contracts.route_resolver.IRouteResolver.resolve

Resolve a request method and path using prebuilt dispatch metadata.

Parameters
method:`str`	HTTP method, matched case-insensitively; HEAD uses the GET table. `WEBSOCKET` selects the isolated connection route table.
path:`str`	Request path to normalize before lookup.

Returns
`ResolvedRoute`	Matched route and immutable, converted parameters. Cached results may be reused.

Raises
`RouteNotFound`	If no route can be resolved and no other method matches the path.
`MethodNotAllowed`	If no HTTP route is resolved and another HTTP method matches.

__slots__: tuple[str, ...] = (source) ¶

Undocumented

_cache_max = (source) ¶

Undocumented

_cache_order: deque[tuple[str, str]] = (source) ¶

Undocumented

_fallback = (source) ¶

Undocumented

_global_static = (source) ¶

Undocumented

_routes = (source) ¶

Undocumented

_tables: dict = (source) ¶

Undocumented