orionis.http.routes.route_compiler.RouteCompiler

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 RouteCompiler(IRouteCompiler): (source)

View In Hierarchy

Undocumented

Static Method	`__buildAction`	Resolve the handler type and build the action descriptor for a route.
Static Method	`__buildPathRegex`	Compile a route path with placeholders into a regex and converters.
Static Method	`__routeMetrics`	Compute the segment count and specificity score for a route path.
Static Method	`__routeSignature`	Build a collision-detection key for a dynamic route.
Static Method	`compilePath`	Determine whether a path is static or dynamic and compile its regex.
Method	`__compileRoute`	Compile a single raw route dict into a `CompiledRoute`.
Method	`compile`	Compile a list of raw route dicts into a ready-to-dispatch structure.

@staticmethod

def __buildAction(route: dict) -> tuple[RouteType, dict]: (source) ¶

Resolve the handler type and build the action descriptor for a route.

Parameters
route:`dict`	Raw route dictionary from the router export.

Returns
`tuple[RouteType, dict]`	A tuple of the resolved `RouteType` and an action descriptor dict containing the information needed to dispatch the request.

Raises
`TypeError`	If an invokable class does not define `__call__`.

@staticmethod

def __buildPathRegex(path: str) -> tuple[re.Pattern, dict[str, Callable]]: (source) ¶

Compile a route path with placeholders into a regex and converters.

Parameters
path:`str`	Route path containing placeholders, e.g. `'/user/{id:int}'`.

Returns
`tuple[re.Pattern, dict[str, Callable]]`	Compiled regex pattern and a dict mapping parameter names to their converter callables.

Raises
`ValueError`	If an unknown parameter type is encountered in the path.

@staticmethod

def __routeMetrics(path: str) -> tuple[int, int]: (source) ¶

Compute the segment count and specificity score for a route path.

Higher scores are more specific and should be matched first. The formula weights static segments heavily so that /users/me (score 20) always beats /users/{id} (score 9).

Parameters
path:`str`	The route path, e.g. `'/users/{id}/settings'`.

Returns
`tuple[int, int]`	`(segment_count, priority_score)` where the score is `static_segments * 10 - dynamic_segments`.

@staticmethod

def __routeSignature(method: str, regex: re.Pattern) -> str: (source) ¶

Build a collision-detection key for a dynamic route.

Two routes collide when they match the same set of URLs regardless of parameter names, e.g. /users/{id} and /users/{name} both produce ^/users/(?P<param>[^/]+)$.

The key normalises every named capture group to the fixed placeholder param and prefixes with the HTTP method:

GET:^/users/(?P<param>[^/]+)$

Parameters
method:`str`	HTTP method in uppercase.
regex:`re.Pattern`	Compiled route regex.

Returns
`str`	Normalised signature string.

@staticmethod

def compilePath(path: str) -> tuple[bool, re.Pattern | None, dict[str, Callable]]: (source) ¶

overrides orionis.http.routes.contracts.route_compiler.IRouteCompiler.compilePath

Determine whether a path is static or dynamic and compile its regex.

This method is intentionally public so that RouteCache can call it during cache deserialisation to reconstruct regex and converters without ever persisting callable objects.

Parameters
path:`str`	The route path, e.g. `'/users/{id:int}'`.

Returns
`tuple[bool, re.Pattern \| None, dict[str, Callable]]`	`(is_static, regex, converters)` — `regex` and `converters` are `None` / empty for static paths.

def __compileRoute(self, route: dict, app_middleware: list[type] | None = None) -> tuple[bool, CompiledRoute]: (source) ¶

Compile a single raw route dict into a CompiledRoute.

Parameters
route:`dict`	Raw route dictionary from the router export.
app_middleware:`list[type] \| None`	Value supplied for `app_middleware`.

Returns
`tuple[bool, CompiledRoute]`	`(is_static, compiled_route)`.

def compile(self, routes: list[dict], fallback: tuple | None, app_middleware: list[type] | None = None) -> tuple[dict[str, dict], tuple | None]: (source) ¶

overrides orionis.http.routes.contracts.route_compiler.IRouteCompiler.compile

Compile a list of raw route dicts into a ready-to-dispatch structure.

Parameters
routes:`list[dict]`	Raw route dicts as returned by `Router.export()["routes"]`.
fallback:`tuple \| None`	Raw fallback tuple from `Router.export()["fallback"]`.
app_middleware:`list[type] \| None, optional`	Global middleware classes to prepend to every route's middleware stack before route-specific middleware is applied.

Returns
`tuple[dict[str, dict], tuple \| None]`	A pair `(compiled_routes, fallback)` where `compiled_routes` maps each HTTP method to `{"static": {path: CompiledRoute}, "dynamic": [CompiledRoute, ...]}`. Dynamic lists are sorted descending by `priority_score` so more-specific patterns are matched first.

Raises
`ValueError`	If two dynamic routes produce the same structural URL pattern (collision).
`TypeError`	If an invokable class does not define `__call__`.