orionis.http.routes.router.Router

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 Router(IRouter): (source)

Constructor: Router(app)

View In Hierarchy

Undocumented

Static Method	`__groupMembers`	Validate and flatten membership without mutating any routes.
Method	`__addSingleRoute`	Create and register a single HTTP route.
Method	`__defaultRoutes`	Register default routes for common static paths.
Method	`__init__`	Initialise the Router and register default system routes.
Method	`_setKind`	Set the route group kind context for subsequent registrations.
Method	`auth`	Register the built-in web authentication routes.
Method	`delete`	Register a DELETE route.
Method	`export`	Export all registered routes and the fallback handler.
Method	`fallback`	Register the fallback handler for unmatched routes (HTTP 404).
Method	`get`	Register a GET route.
Method	`group`	Compose a group and return its flattened membership for nesting.
Method	`hub`	Register a Hub endpoint using a fixed JSON or MessagePack codec.
Method	`patch`	Register a PATCH route.
Method	`post`	Register a POST route.
Method	`put`	Register a PUT route.
Method	`query`	Register a QUERY route.
Method	`view`	Register a GET route that renders a template with no controller.
Method	`websocket`	Register a WebSocket connection handler independently of HTTP routes.
Constant	`_DEFAULT_PATHS`	Undocumented
Instance Variable	`__app`	Undocumented
Instance Variable	`__current_kind`	Undocumented
Instance Variable	`__fallback`	Undocumented
Instance Variable	`__replaceable_routes`	Undocumented
Instance Variable	`__routes`	Undocumented

Inherited from IRouter:

Class Variable __slots__ Undocumented

@staticmethod

def __groupMembers(routes: Sequence[FluentRoute | RouteGroup] | None) -> tuple[FluentRoute, ...]: (source) ¶

Validate and flatten membership without mutating any routes.

Parameters
routes:`Sequence[FluentRoute \| RouteGroup] \| None`	Value supplied for `routes`.

Returns
`tuple[FluentRoute, ...]`	Unique leaf routes in declaration order.

Raises
`ValueError`	If membership is empty or contains duplicate routes.
`TypeError`	If a member is neither a route nor a group.

def __addSingleRoute(self, method: str, path: str, action: RouteAction | None = None, *, view: str | None = None) -> FluentRoute: (source) ¶

Create and register a single HTTP route.

Parameters
method:`str`	HTTP method (e.g. `'GET'`, `'POST'`).
path:`str`	URL path for the route.
action:`RouteAction \| None, optional`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. If omitted or None, call `action(controller, handler)` on the returned route before exporting the router.
view:`str \| None, optional`	Template name rendered directly by the kernel, used instead of action for view-only routes.

Returns
`FluentRoute`	The registered FluentRoute instance.

def __defaultRoutes(self): (source) ¶

Registers GET handlers for favicon, robots.txt, and sitemap.xml using the DefaultResponses class.

Parameters
None

Returns
`None`	Default routes are registered on the instance; no value is returned.

def __init__(self, app: IApplication): (source) ¶

Initialise the Router and register default system routes.

Parameters
app:`IApplication`	The application instance.

Returns
`None`	State is stored on the instance; no value is returned.

def _setKind(self, kind: str): (source) ¶

Set the route group kind context for subsequent registrations.

All routes registered after this call will carry the given kind value ('web' or 'api') in their exported dict. The loader calls this before importing each route file so that the routes defined in that file are tagged accordingly.

Parameters
kind:`str`	Route group kind, either `'web'` or `'api'`.

Returns
`None`	Context is updated in place; no value is returned.

def auth(self, login_controller: type | None = None, register_controller: type | None = None, forgot_password_controller: type | None = None): (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.auth

Call once from a web route file. Each controller can be overridden independently; omitted controllers use the framework defaults. Login, registration and password recovery accept guests; email verification accepts anyone so a link opened from a signed-in browser still works; logout requires a session identity and accepts POST only. Session and CSRF middleware are supplied by the kernel's web pipeline.

Parameters
login_controller:`type \| None, optional`	Controller for login and logout.
register_controller:`type \| None, optional`	Controller for registration and email verification.
forgot_password_controller:`type \| None, optional`	Controller for forgot-password and password-reset routes.

Returns
`None`	Registers GET/POST login, sign-up, forgot-password and reset-password routes, GET email verification, and POST logout. The named routes include `login`, `register`, `forgot-password`, `password.reset`, `password.update`, `verify-email` and `logout`.

Raises
`ValueError`	If registration is attempted outside the web route context.

def delete(self, path: str, action: RouteAction | None = None) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.delete

Parameters
path:`str`	URL path for the route.
action:`RouteAction \| None, optional`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. If omitted or None, call `action(controller, handler)` on the returned route before exporting the router.

Returns
`FluentRoute`	The registered FluentRoute instance.

def export(self) -> dict: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.export

Export all registered routes and the fallback handler.

Returns

dict

A dictionary with two keys:

'routes': list of all registered routes as dicts.
'fallback': tuple (class_or_None, handler_or_callable).

Raises
`ValueError`	If a registered route still has no action or view.

def fallback(self, action: RouteAction): (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.fallback

Only one fallback may be registered; a second call raises FallbackRouteAlreadyRegisteredException.

Parameters
action:`RouteAction`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. Required because fallback registration does not return a fluent route builder.

Returns
`None`	The fallback is stored on the instance; no value is returned.

Raises
`FallbackRouteAlreadyRegisteredException`	If a fallback handler has already been registered.
`TypeError`	If the action is None or is not an accepted handler form.
`ValueError`	If a controller pair has an invalid length or names a missing method.

def get(self, path: str, action: RouteAction | None = None) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.get

Parameters
path:`str`	URL path for the route.
action:`RouteAction \| None, optional`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. If omitted or None, call `action(controller, handler)` on the returned route before exporting the router.

Returns
`FluentRoute`	The registered FluentRoute instance.

overrides orionis.http.routes.contracts.router.IRouter.group

Compose a group and return its flattened membership for nesting.

Parameters
prefix:`str \| None, optional`	Prefix prepended to every descendant path.
middleware:`MiddlewareInput \| None, optional`	Parent middleware executed before descendant middleware.
without_middleware:`MiddlewareInput \| None, optional`	Exclusions applied to the final compiled middleware stack.
routes:`Sequence[FluentRoute \| RouteGroup] \| None, optional`	Routes or groups already registered by inner expressions.
public:`bool \| None, optional`	Inherited stateless profile; explicit child choices take precedence.

Returns
`RouteGroup`	Already registered routes, usable as members of another group.

Raises
`ValueError`	If the group is empty, its context is invalid, or a route appears more than once. Validation completes before any route is changed.
`TypeError`	If membership is not a sequence of routes and groups.

def hub(self, path: str, hub: type[Hub], *, protocol: str = 'json') -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.hub

Parameters
path:`str`	Connection path supporting converted route parameters.
hub:`type[Hub]`	Hub class providing explicitly decorated remote methods.
protocol:`str, optional`	Realtime codec, either `json` (default) or `msgpack`.

Returns
`FluentRoute`	Connection route supporting names, groups and socket middleware.

Raises
`TypeError`	If hub is not a Hub subclass.
`ValueError`	If the protocol is unsupported.

def patch(self, path: str, action: RouteAction | None = None) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.patch

Parameters
path:`str`	URL path for the route.
action:`RouteAction \| None, optional`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. If omitted or None, call `action(controller, handler)` on the returned route before exporting the router.

Returns
`FluentRoute`	The registered FluentRoute instance.

def post(self, path: str, action: RouteAction | None = None) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.post

Parameters
path:`str`	URL path for the route.
action:`RouteAction \| None, optional`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. If omitted or None, call `action(controller, handler)` on the returned route before exporting the router.

Returns
`FluentRoute`	The registered FluentRoute instance.

def put(self, path: str, action: RouteAction | None = None) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.put

Parameters
path:`str`	URL path for the route.
action:`RouteAction \| None, optional`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. If omitted or None, call `action(controller, handler)` on the returned route before exporting the router.

Returns
`FluentRoute`	The registered FluentRoute instance.

def query(self, path: str, action: RouteAction | None = None) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.query

Parameters
path:`str`	URL path for the route.
action:`RouteAction \| None, optional`	Callable, invokable controller class (defining `__call__`), or `[ControllerClass, 'method_name']` list. If omitted or None, call `action(controller, handler)` on the returned route before exporting the router.

Returns
`FluentRoute`	The registered FluentRoute instance.

def view(self, path: str, view: str) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.view

Parameters
path:`str`	URL path for the route.
view:`str`	Template name in dot notation (e.g. `'welcome'`) or a relative path (e.g. `'pages/welcome.html'`).

Returns
`FluentRoute`	The registered FluentRoute instance.

Raises
`ValueError`	If `view` is not a non-empty string.

def websocket(self, path: str, action: RouteAction | None = None) -> FluentRoute: (source) ¶

overrides orionis.http.routes.contracts.router.IRouter.websocket

Parameters
path:`str`	Connection path, supporting the usual converted path parameters.
action:`RouteAction \| None, optional`	Function, controller action, or invokable controller.

Returns
`FluentRoute`	Route builder accepting WebSocketMiddleware and route groups.

_DEFAULT_PATHS = (source) ¶

Undocumented

Value

frozenset(set(['/favicon.ico', '/robots.txt', '/sitemap.xml']))

__app = (source) ¶

Undocumented

__current_kind: str = (source) ¶

Undocumented

__fallback: tuple[type | None, Callable | str | None] = (source) ¶

Undocumented

__replaceable_routes: dict[str, FluentRoute] = (source) ¶

Undocumented

__routes: dict[str, FluentRoute] = (source) ¶

Undocumented