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

Undocumented

Async Method __asgiResponse Send ASGI HTTP response through transport adapter.
Async Method __bodyLengthResponse Reject invalid framing and declared oversized bodies before reading.
Async Method __callFallback Invoke the registered fallback handler and return its response.
Async Method __callHandler Dispatch the request to the pre-resolved route handler.
Async Method __callWebSocketHandler Invoke a preloaded connection handler through the scoped container.
Method __defaultMiddleware Initialize default HTTP middleware stack.
Async Method __globalMiddleware Execute global middleware and serve packaged default-page assets.
Async Method __handleException Translate a caught exception into an HTTP response.
Async Method __handleWebSocket Dispatch a bounded connection inside a dedicated lifetime scope.
Method __init__ Initialize the HTTP kernel with application and failure handler.
Async Method __preloadEndpointPolicy Bind one validated policy instance to a static HTTP endpoint.
Async Method __preloadHandlers Import route handlers and prepare their dependency metadata at boot time.
Async Method __preloadMiddleware Pre-build middleware instances for all routes at boot time.
Async Method __processRequest Build the HTTP response for this request.
Async Method __processWebSocket Validate a handshake and run its connection middleware and handler.
Async Method __requestLayer Execute route-level middleware for the resolved route.
Async Method __routeLayer Establish the web or API context before running route middleware.
Method __routeResolve Initialize route resolver with loaded routes.
Async Method __rsgiResponse Send an RSGI HTTP response through the transport adapter.
Async Method __shutdownWebSockets Cancel connection lifetimes within the existing shutdown lifecycle.
Method __websocketOriginAllowed Check browser origins before allowing an application handshake.
Async Method __webTerminal Run the route pipeline and translate validation failures for the web.
Async Method boot Boot the HTTP kernel by initializing all core components.
Method disconnectPaths Expose compiled endpoint opt-ins to the application transport wrapper.
Async Method handleASGI Handle an incoming ASGI HTTP request end-to-end.
Async Method handleRSGI Handle an incoming RSGI HTTP request end-to-end.
Class Variable __slots__ Undocumented
Instance Variable __api_middleware Undocumented
Instance Variable __app Undocumented
Instance Variable __asgi_adapter Undocumented
Instance Variable __body_limits Undocumented
Instance Variable __boot Undocumented
Instance Variable __catch Undocumented
Instance Variable __cls_dispatch Undocumented
Instance Variable __cors Undocumented
Instance Variable __default_responses Undocumented
Instance Variable __endpoint_policies Undocumented
Instance Variable __fallback Undocumented
Instance Variable __fn_dispatch Undocumented
Instance Variable __health_path Undocumented
Instance Variable __hub_dispatch Undocumented
Instance Variable __middleware_cache Undocumented
Instance Variable __printer_enabled Undocumented
Instance Variable __proxies Undocumented
Instance Variable __rate_limit Undocumented
Instance Variable __rate_limit_enabled Undocumented
Instance Variable __request_printer Undocumented
Instance Variable __request_slots Undocumented
Instance Variable __routes Undocumented
Instance Variable __rsgi_adapter Undocumented
Instance Variable __security Undocumented
Instance Variable __under_maintenance Undocumented
Instance Variable __view_dispatch Undocumented
Instance Variable __web_middleware Undocumented
Instance Variable __websocket_config Undocumented
Instance Variable __websocket_slots Undocumented
Instance Variable __websocket_tasks Undocumented
async def __asgiResponse(self, adapter: TransportAdapter, response: Response, receive: object, send: object, policy: IHttpEndpointPolicy | None = None): (source)

Send ASGI HTTP response through transport adapter.

Apply CORS post-processing headers, log request details, and send the response back to the client via ASGI protocol adapter.

Parameters
adapter:TransportAdapterTransport adapter encapsulating the HTTP request.
response:ResponseHTTP response object to send to client.
receive:objectASGI receive callable for reading request body.
send:objectASGI send callable for sending response.
policy:IHttpEndpointPolicy | NoneValue supplied for policy.
Returns
NoneUndocumented
async def __bodyLengthResponse(self, adapter: TransportAdapter) -> Response | None: (source)

Reject invalid framing and declared oversized bodies before reading.

Parameters
adapter:TransportAdapterIncoming transport metadata.
Returns
Response | NoneA 400 or 413 response for rejected framing, otherwise None. Stream byte counting remains authoritative when length is absent or false.
async def __callFallback(self, fallback: tuple) -> Response: (source)

Invoke the registered fallback handler and return its response.

Parameters
fallback:tuplePair of (handler_class_or_callable, method_name_or_function).
Returns
ResponseHTTP response produced by the fallback handler.
Raises
TypeErrorIf the fallback does not return a Response object.
async def __callHandler(self, resolved_route: ResolvedRoute, request: Request) -> Response: (source)

Dispatch the request to the pre-resolved route handler.

Uses boot-time dispatch tables keyed by route object identity, eliminating per-request module imports and attribute lookups.

Parameters
resolved_route:ResolvedRouteResolved route descriptor with handler reference and path params.
request:RequestRequest-local parameters, including middleware changes.
Returns
ResponseHTTP response produced by the handler.
Raises
TypeErrorIf the handler does not return a Response, dict, or msgspec.Struct.
async def __callWebSocketHandler(self, resolved_route: ResolvedRoute, socket: WebSocket): (source)

Invoke a preloaded connection handler through the scoped container.

Parameters
resolved_route:ResolvedRouteCompiled route with converted parameters.
socket:WebSocketScoped connection injected into application handlers.
Returns
NoneRun the handler for the lifetime of the connection.
Raises
TypeErrorIf the handler returns an HTTP response or another value.
def __defaultMiddleware(self, http_config: dict, default_responses: IDefaultResponses, *, under_maintenance: bool = False): (source)

Initialize default HTTP middleware stack.

Configure and instantiate the default middleware chain including proxies, security, CORS, and rate limiting middleware.

Parameters
http_config:dictHTTP configuration dictionary with middleware settings.
default_responses:IDefaultResponsesDefault response handler for middleware rejections.
under_maintenance:boolValue supplied for under_maintenance.
Returns
NoneUndocumented
async def __globalMiddleware(self, adapter: TransportAdapter) -> Response | None: (source)

Execute global middleware and serve packaged default-page assets.

Process request through middleware pipeline: proxies detection, security validation, and CORS negotiation. Framework assets remain available during maintenance and after rate-limit rejections.

Parameters
adapter:TransportAdapterTransport adapter encapsulating the HTTP request.
Returns
Response | NoneHTTP response if middleware rejects request, None if request passes all middleware checks.
async def __handleException(self, exc: Exception, request: object, policy: IHttpEndpointPolicy | None = None) -> Response: (source)

Translate a caught exception into an HTTP response.

Parameters
exc:ExceptionThe exception raised during request processing.
request:objectCurrent request object (may be the raw transport adapter for pre-routing errors).
policy:IHttpEndpointPolicy | NoneValue supplied for policy.
Returns
ResponseAppropriate HTTP response for the given exception type.
async def __handleWebSocket(self, interface: Interface, adapter: TransportAdapter, receive_or_protocol: object, send: object = None): (source)

Dispatch a bounded connection inside a dedicated lifetime scope.

Parameters
interface:InterfaceServer protocol identifier.
adapter:TransportAdapterHandshake request metadata.
receive_or_protocol:objectASGI receive callback or Granian WebsocketProtocol.
send:object, optionalASGI send callback, omitted for RSGI.
Returns
NoneAwait the connection pipeline and always release admission.
def __init__(self, app: IApplication, catch: ICatch): (source)

Initialize the HTTP kernel with application and failure handler.

Parameters
app:IApplicationApplication instance providing configuration and DI container.
catch:ICatchFailure handler used to format unhandled exceptions.
Returns
NoneUndocumented
async def __preloadEndpointPolicy(self, controller: type, route: CompiledRoute, policy_instances: dict[type[IHttpEndpointPolicy], IHttpEndpointPolicy]): (source)

Bind one validated policy instance to a static HTTP endpoint.

Parameters
controller:typeController declaring an optional HTTP protocol policy.
route:CompiledRouteCompiled route associated with the controller.
policy_instances:dict[type[IHttpEndpointPolicy], IHttpEndpointPolicy]Policy instances already constructed during this kernel boot.
Returns
NoneThe endpoint uses the shared policy instance for its policy type.
Raises
TypeErrorIf a policy is not a policy class or the route is dynamic.
async def __preloadHandlers(self): (source)

Import route handlers and prepare their dependency metadata at boot time.

Populates two int-keyed dispatch tables using route object identity, eliminating per-request module imports, attribute lookups, and tuple key construction from the handler invocation hot path. View routes are stored in a third table holding only their template name. Ordinary constructor and action plans are prepared without resolving services or creating controller instances. Custom descriptors remain lazy.

Returns
NoneUndocumented
async def __preloadMiddleware(self): (source)

Pre-build middleware instances for all routes at boot time.

Iterate every compiled route and eagerly resolve each middleware class through the container. Results are stored keyed by the immutable stack tuple so identical stacks share the same instances.

Returns
NoneUndocumented
async def __processRequest(self, interface: Interface, adapter: TransportAdapter, receive_or_protocol: object, request_context: object, policy: IHttpEndpointPolicy | None = None) -> Response: (source)

Build the HTTP response for this request.

Runs global middleware, rate limiting, route resolution, and the handler pipeline. All exceptions are delegated to __handleException.

Parameters
interface:InterfaceTransport interface type used to construct the BodyStream.
adapter:TransportAdapterProtocol adapter carrying request metadata.
receive_or_protocol:objectASGI receive callable or RSGI HTTPProtocol instance.
request_context:objectActive DI request scope for per-request bindings.
policy:IHttpEndpointPolicy | NoneValue supplied for policy.
Returns
ResponseThe fully constructed HTTP response.
async def __processWebSocket(self, adapter: TransportAdapter, socket: WebSocket): (source)

Validate a handshake and run its connection middleware and handler.

Parameters
adapter:TransportAdapterHandshake metadata for global guards and route matching.
socket:WebSocketConnection already bound to the active application scope.
Returns
NoneReject the handshake or await the application connection lifetime.
Raises
TypeErrorIf middleware returns a value instead of None.
async def __requestLayer(self, request: Request, resolved_route: ResolvedRoute) -> Response: (source)

Execute route-level middleware for the resolved route.

Parameters
request:RequestIncoming HTTP request.
resolved_route:ResolvedRouteResolved route with matched handler and path parameters.
Returns
ResponseHTTP response produced by the pipeline or the handler.
async def __routeLayer(self, request: Request, resolved_route: ResolvedRoute) -> Response: (source)

Establish the web or API context before running route middleware.

Web routes restore the session, validate CSRF, and resolve the session identity. API routes resolve only the token identity. Both allow guests; access restrictions belong to the application's route middleware.

Parameters
request:RequestIncoming HTTP request.
resolved_route:ResolvedRouteResolved route metadata.
Returns
ResponseHTTP response produced by the middleware pipeline.
def __routeResolve(self, route_loader: IRouteLoader): (source)

Initialize route resolver with loaded routes.

Build a route resolver instance configured with routes loaded from the provided route loader and cache settings.

Parameters
route_loader:IRouteLoaderRoute loader instance to discover and load routes.
Returns
NoneUndocumented
async def __rsgiResponse(self, adapter: RSGITransportAdapter, response: Response, protocol: HTTPProtocol, policy: IHttpEndpointPolicy | None = None): (source)

Send an RSGI HTTP response through the transport adapter.

Apply CORS post-processing headers, log request details, and send the response back to the client via the RSGI protocol adapter.

Parameters
adapter:RSGITransportAdapterRSGI transport adapter with HTTP scope and client connection.
response:ResponseHTTP response object to send to client.
protocol:HTTPProtocolRSGI HTTP protocol version indicator.
policy:IHttpEndpointPolicy | NoneValue supplied for policy.
Returns
NoneUndocumented
async def __shutdownWebSockets(self): (source)

Cancel connection lifetimes within the existing shutdown lifecycle.

Returns
NoneAwait cooperative cleanup for at most five seconds.
def __websocketOriginAllowed(self, adapter: TransportAdapter) -> bool: (source)

Check browser origins before allowing an application handshake.

Parameters
adapter:TransportAdapterProxy-normalized handshake metadata.
Returns
boolTrue for missing Origin, same origin, or an explicit allowed origin.
async def __webTerminal(self, request: Request, resolved_route: ResolvedRoute) -> Response: (source)

Run the route pipeline and translate validation failures for the web.

Validation errors are caught here, inside the session middleware, so the resulting redirect still gets its flash bag persisted.

Parameters
request:RequestIncoming HTTP request.
resolved_route:ResolvedRouteResolved route metadata.
Returns
ResponseHandler response, or a redirect back carrying the errors.
async def boot(self): (source)

Boot the HTTP kernel by initializing all core components.

Returns
NoneUndocumented
def disconnectPaths(self) -> frozenset[str]: (source)

Expose compiled endpoint opt-ins to the application transport wrapper.

Returns
frozenset[str]Result of the operation described above.
async def handleASGI(self, scope: dict, receive: object, send: object): (source)

Handle an incoming ASGI HTTP request end-to-end.

Parameters
scope:dictASGI connection scope dict with request metadata.
receive:objectASGI receive callable for reading request body.
send:objectASGI send callable for writing response messages.
Returns
NoneUndocumented
async def handleRSGI(self, scope: Scope, protocol: HTTPProtocol | WebsocketProtocol) -> object | None: (source)

Handle an incoming RSGI HTTP request end-to-end.

Parameters
scope:ScopeGranian RSGI scope with connection metadata.
protocol:HTTPProtocolRSGI protocol object for writing the response.
Returns
object | NoneResult of sending the RSGI response, or None on error.
__api_middleware: tuple = (source)

Undocumented

Undocumented

__asgi_adapter = (source)

Undocumented

__body_limits = (source)

Undocumented

Undocumented

__catch: ICatch = (source)

Undocumented

__cls_dispatch: dict[int, tuple[type, str]] = (source)

Undocumented

Undocumented

__default_responses: IDefaultResponses = (source)

Undocumented

__endpoint_policies: dict[str, IHttpEndpointPolicy] = (source)

Undocumented

__fallback: tuple | None = (source)

Undocumented

__fn_dispatch: dict[int, object] = (source)

Undocumented

__health_path = (source)

Undocumented

__hub_dispatch = (source)

Undocumented

__middleware_cache: dict[tuple, tuple] = (source)

Undocumented

__printer_enabled: bool = (source)

Undocumented

__proxies = (source)

Undocumented

__rate_limit = (source)

Undocumented

__rate_limit_enabled = (source)

Undocumented

__request_printer = (source)

Undocumented

__request_slots = (source)

Undocumented

__routes = (source)

Undocumented

__rsgi_adapter = (source)

Undocumented

__security = (source)

Undocumented

__under_maintenance = (source)

Undocumented

__view_dispatch: dict[int, str] = (source)

Undocumented

__web_middleware: tuple = (source)

Undocumented

__websocket_config = (source)

Undocumented

__websocket_slots = (source)

Undocumented

__websocket_tasks: set[asyncio.Task] = (source)

Undocumented