ORIONIS API REFERENCE

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.

class documentation

Build route definitions through chainable routing options.

Method __init__ Initialize a FluentRoute instance.
Method _hub Set the Hub class and its fixed connection codec.
Method _kind Set the kind of the route (e.g., 'web', 'api').
Method action Set the controller class and handler for the route.
Method export Export a complete route configuration as a plain dictionary.
Method inheritGroup Apply validated group context during registration.
Method middleware Add middleware to the route.
Method name Set the name for the route.
Method prefix Prepend a path segment to the route's current path.
Method public Select a stateless route without automatic session or identity setup.
Method withOutMiddleware Exclude one or more middleware classes from the route.
Constant _ALLOWED_METHODS Allowed methods used by FluentRoute.
Instance Variable __callable_handler Direct callable selected as the route action.
Instance Variable __class Controller class selected to handle the route.
Instance Variable __handler Callable or method selected to handle the registered operation.
Instance Variable __hub Realtime hub class attached to the route.
Instance Variable __hub_protocol Wire protocol selected for the realtime hub route.
Instance Variable __id Identifier used to correlate or locate this protocol or storage record.
Instance Variable __kind Kind identifier: web.
Instance Variable __method HTTP method (e.g., 'GET', 'POST').
Instance Variable __middleware Middleware applied around the route handler.
Instance Variable __name Name identifying this declaration within its containing registry.
Instance Variable __path Route path.
Instance Variable __public Whether the route is marked for public access.
Instance Variable __view Template name rendered directly by the kernel. When given, the route carries no Python handler and action is not parsed.
Instance Variable __without_middleware Without middleware produced by set.
Property id Return the unique identifier of the route.
Property path Return the current canonical path, including inherited prefixes.
def __init__(self, method: str, path: str, action: RouteAction | None = None, *, view: str | None = None): (source)

Initialize a FluentRoute instance.

Parameters
method:strHTTP method (e.g., 'GET', 'POST').
path:strRoute path.
action:orionis.http.routes.types.RouteAction | None, optional

Action to execute. Three forms are accepted:

  • Invokable controller - bare class that defines __call__:

    FluentRoute("GET", "/", UserController)
    
  • Controller + method - two-element list:

    FluentRoute("GET", "/", [UserController, "index"])
    
  • Callable - plain function or coroutine function:

    FluentRoute("GET", "/", my_view)
    

Ignored when view is provided. If omitted or None, set the controller and method with action() before exporting.

view:str | None, optionalTemplate name rendered directly by the kernel. When given, the route carries no Python handler and action is not parsed.
Returns
NoneThe instance is initialized; no value is returned.
Raises
TypeErrorIf method or path is not a string, or a supplied action is invalid.
ValueErrorIf method is unsupported, view is invalid, or a controller pair has an invalid length or names a missing method.
def _hub(self, hub: type[Hub], protocol: str) -> Self: (source)

Set the Hub class and its fixed connection codec.

Parameters
hub:type[orionis.realtime.Hub]Concrete Hub subclass resolved through the application container.
protocol:strRealtime codec name: json or msgpack.
Returns
typing.SelfThis connection route with an explicit Hub action.
Raises
TypeErrorIf the class does not inherit from Hub.
ValueErrorIf the route is HTTP or the codec is unsupported.
def _kind(self, kind: str) -> Self: (source)

Set the kind of the route (e.g., 'web', 'api').

Parameters
kind:strThe kind to set for the route.
Returns
typing.SelfThis FluentRoute instance for method chaining.
def action(self, controller: type, handler: str) -> Self: (source)

Set the controller class and handler for the route.

Parameters
controller:typeController class to associate with the route.
handler:strName of the handler method.
Returns
typing.SelfThis FluentRoute instance for method chaining.
def export(self) -> dict: (source)

Export a complete route configuration as a plain dictionary.

Returns
dictDictionary with keys: id, method, path, class, handler, callable_handler, view, name, middleware, without_middleware, kind, public, protocol, hub, and hub_protocol.
Raises
ValueErrorIf the route has neither a view nor an assigned action.
def inheritGroup(self, prefix: str, middleware: tuple[type[BaseMiddleware], ...], without_middleware: frozenset[type[BaseMiddleware]], *, public: bool | None = None) -> Self: (source)

Apply validated group context during registration.

Parameters
prefix:strCanonical prefix without a trailing slash, or an empty string.
middleware:tuple[type[orionis.http.BaseMiddleware], ...]Parent middleware, in declaration order.
without_middleware:frozenset[type[orionis.http.BaseMiddleware]]Exclusions inherited by the route.
public:bool | None, optionalParent profile applied only when the route has no explicit profile.
Returns
typing.SelfThis route with the parent context prepended.
def middleware(self, *middleware: MiddlewareInput) -> Self: (source)

Add middleware to the route.

Parameters
*middleware:orionis.http.routes.types.MiddlewareInputOne or more middleware classes (not instances) to attach. Classes may be passed individually or wrapped in a list, tuple or set.
Returns
typing.SelfThis FluentRoute instance for method chaining.
def name(self, name: str) -> Self: (source)

Set the name for the route.

Parameters
name:strName to assign to the route.
Returns
typing.SelfThis FluentRoute instance for method chaining.
def prefix(self, prefix: str) -> Self: (source)

Prepend a path segment to the route's current path.

Parameters
prefix:strThe path prefix to prepend.
Returns
typing.SelfThis FluentRoute instance for method chaining.
def public(self, *, enabled: bool = True) -> Self: (source)

Select a stateless route without automatic session or identity setup.

Global security, CORS, rate limits, and explicitly attached middleware still run. Web session, CSRF, and automatic identity resolution do not. Use this profile only for endpoints that do not use cookie credentials.

Parameters
enabled:bool, optionalWhether to opt out of the default web or API context middleware. False explicitly retains that context inside a public group.
Returns
typing.SelfThis route with the requested execution profile.
Raises
TypeErrorIf enabled is not a boolean.
def withOutMiddleware(self, *middleware: MiddlewareInput) -> Self: (source)

Exclude one or more middleware classes from the route.

Parameters
*middleware:orionis.http.routes.types.MiddlewareInputOne or more middleware classes to exclude from this route. Classes may be passed individually or wrapped in a list, tuple or set.
Returns
typing.SelfThis FluentRoute instance for method chaining.
_ALLOWED_METHODS: frozenset[str] = (source)

Allowed methods used by FluentRoute.

Value
frozenset(set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'QUERY', 'WEBSOCKET']))
__callable_handler: Callable | None = (source)

Direct callable selected as the route action.

Controller class selected to handle the route.

__handler: str | None = (source)

Callable or method selected to handle the registered operation.

__hub: type[Hub] | None = (source)

Realtime hub class attached to the route.

__hub_protocol: str | None = (source)

Wire protocol selected for the realtime hub route.

Identifier used to correlate or locate this protocol or storage record.

Kind identifier: web.

__method: str = (source)

HTTP method (e.g., 'GET', 'POST').

__middleware: list[type[BaseMiddleware]] = (source)

Middleware applied around the route handler.

Name identifying this declaration within its containing registry.

Route path.

__public: bool | None = (source)

Whether the route is marked for public access.

Template name rendered directly by the kernel. When given, the route carries no Python handler and action is not parsed.

__without_middleware: set[type[BaseMiddleware]] = (source)

Without middleware produced by set.

Return the unique identifier of the route.

Returns
strThe unique identifier of the route.

Return the current canonical path, including inherited prefixes.

Returns
strThe current canonical path, including inherited prefixes.