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.
Serve concurrent requests within one worker event loop.
| Async Method | __asgi |
Send ASGI HTTP response through transport adapter. |
| Async Method | __body |
Reject invalid framing and declared oversized bodies before reading. |
| Async Method | __call |
Invoke the registered fallback handler and return its response. |
| Async Method | __call |
Dispatch the route handler and validate direct schema results. |
| Async Method | __call |
Invoke a preloaded connection handler through the scoped container. |
| Async Method | __close |
Close a connection while retaining the failure already escaping its owner. |
| Method | __default |
Initialize default HTTP middleware stack. |
| Async Method | __exception |
Apply endpoint policies and application handling to an ordinary error. |
| Async Method | __global |
Execute global middleware and serve packaged default-page assets. |
| Async Method | __handle |
Translate a caught exception into an HTTP response. |
| Async Method | __handle |
Dispatch a bounded connection inside a dedicated lifetime scope. |
| Method | __init__ |
Initialize the HTTP kernel with application and failure handler. |
| Async Method | __is |
Classify an error while observing failures of a custom classifier. |
| Async Method | __preload |
Bind one validated policy instance to a static HTTP endpoint. |
| Async Method | __preload |
Import route handlers and prepare their dependency metadata at boot time. |
| Async Method | __preload |
Pre-build middleware instances for all routes at boot time. |
| Async Method | __process |
Build the HTTP response for this request. |
| Async Method | __process |
Validate a handshake and run its connection middleware and handler. |
| Async Method | __request |
Execute route-level middleware for the resolved route. |
| Async Method | __route |
Establish the web or API context before running route middleware. |
| Method | __route |
Initialize route resolver with loaded routes. |
| Async Method | __rsgi |
Send an RSGI HTTP response through the transport adapter. |
| Async Method | __run |
Run an admitted connection and observe errors before transport cleanup. |
| Async Method | __shutdown |
Cancel connection lifetimes within the existing shutdown lifecycle. |
| Method | __websocket |
Check browser origins before allowing an application handshake. |
| Async Method | __web |
Run the route pipeline and translate validation failures for the web. |
| Async Method | boot |
Boot the HTTP kernel by initializing all core components. |
| Method | disconnect |
Expose compiled endpoint opt-ins to the application transport wrapper. |
| Async Method | handle |
Handle an incoming ASGI HTTP request end-to-end. |
| Async Method | handle |
Handle an incoming RSGI HTTP request end-to-end. |
| Class Variable | __slots__ |
Declare the instance attribute slots reserved by this class. |
| Instance Variable | __api |
API identity resolution uses Bearer credentials without starting a session. |
| Instance Variable | __app |
Application instance providing configuration and DI container. |
| Instance Variable | __asgi |
Adapter translating ASGI request events into framework operations. |
| Instance Variable | __body |
Body limits produced by HTTPBodyLimits. |
| Instance Variable | __boot |
Boot flag used by KernelHTTP. |
| Instance Variable | __catch |
Failure handler used to format unhandled exceptions. |
| Instance Variable | __cls |
Cls dispatch supplied through cls_dispatch. |
| Instance Variable | __cors |
Cors produced by CORSMiddleware. |
| Instance Variable | __default |
Build the default response factory for common HTTP error responses. |
| Instance Variable | __endpoint |
Compiled policies associated with each dispatched endpoint. |
| Instance Variable | __fallback |
Handler or route selected when no ordinary route matches. |
| Instance Variable | __fn |
Fn dispatch supplied through fn_dispatch. |
| Instance Variable | __health |
Health path produced by self.__app.routeHealthCheck.rstrip. |
| Instance Variable | __hub |
Hub dispatch supplied through hub_dispatch. |
| Instance Variable | __middleware |
Associate each route middleware stack with its instances. |
| Instance Variable | __printer |
Record whether requests should be timed and logged. |
| Instance Variable | __proxies |
Proxies produced by ProxiesMiddleware. |
| Instance Variable | __rate |
Rate limit produced by RateLimitMiddleware. |
| Instance Variable | __rate |
Record whether rate limiting is active. |
| Instance Variable | __request |
Request logger; only active when the application runs in debug mode. |
| Instance Variable | __request |
Request slots obtained from self.__body_limits.max_concurrent_requests. |
| Instance Variable | __routes |
Build the resolver with compiled routes and a fixed hot-cache budget. |
| Instance Variable | __rsgi |
Protocol-level response adapters for RSGI and ASGI transports. |
| Instance Variable | __security |
Security produced by SecurityMiddleware. |
| Instance Variable | __under |
Value supplied for under_maintenance. |
| Instance Variable | __view |
View dispatch supplied through view_dispatch. |
| Instance Variable | __web |
Resolve web identities only after session restoration and CSRF checks. |
| Instance Variable | __websocket |
Websocket config produced by HTTPWebSocket. |
| Instance Variable | __websocket |
Synchronization primitive controlling access to websocket slots. |
| Instance Variable | __websocket |
Websocket tasks produced by set. |
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:orionis.http.adapters.request.contracts.transport.TransportAdapter | Transport adapter encapsulating the HTTP request. |
response:orionis.http.Response | HTTP response object to send to client. |
receive:object | ASGI receive callable for reading request body. |
send:object | ASGI send callable for sending response. |
policy:orionis.http.contracts.endpoint_policy.IHttpEndpointPolicy | None | Value supplied for policy. |
| Returns | |
None | Send ASGI HTTP response through transport adapter. |
Reject invalid framing and declared oversized bodies before reading.
| Parameters | |
adapter:orionis.http.adapters.request.contracts.transport.TransportAdapter | Incoming transport metadata. |
| Returns | |
orionis.http.Response | None | A 400 or 413 response for rejected framing, otherwise None. Stream byte counting remains authoritative when length is absent or false. |
Invoke the registered fallback handler and return its response.
| Parameters | |
fallback:tuple | Pair of (handler_class_or_callable, method_name_or_function). |
| Returns | |
orionis.http.Response | HTTP response produced by the fallback handler. |
| Raises | |
TypeError | If the fallback does not return a Response object. |
ResolvedRoute, request: Request) -> Response:
(source)
¶
Dispatch the route handler and validate direct schema results.
Reuse boot-time dispatch tables and serialize structured results. Return explicit responses unchanged.
| Parameters | |
resolvedorionis.http.routes.entities.resolved_route.ResolvedRoute | Resolved route descriptor with handler reference and path params. |
request:orionis.http.Request | Request-local parameters, including middleware changes. |
| Returns | |
orionis.http.Response | Handler response or JSON response containing the handler result. |
| Raises | |
TypeError | If the handler does not return a Response, dict, or msgspec.Struct. |
orionis.http.exceptions.response_validation.ResponseValidationException | If a returned Orionis schema violates its output contract. |
ResolvedRoute, socket: WebSocket):
(source)
¶
Invoke a preloaded connection handler through the scoped container.
| Parameters | |
resolvedorionis.http.routes.entities.resolved_route.ResolvedRoute | Compiled route with converted parameters. |
socket:orionis.http.WebSocket | Scoped connection injected into application handlers. |
| Returns | |
None | Run the handler for the lifetime of the connection. |
| Raises | |
TypeError | If the handler returns an HTTP response or another value. |
WebSocket, *, code: int = 1000, primary: BaseException | None = None):
(source)
¶
Close a connection while retaining the failure already escaping its owner.
| Parameters | |
socket:WebSocket | Accepted connection or pending handshake owned by the HTTP kernel. |
code:int, optional | Protocol close status selected by the connection owner. |
primary:BaseException | None, optional | Failure escaping this connection, not an unrelated caller exception. |
| Returns | |
None | Complete closure and observe any secondary operational error. |
| Raises | |
Exception | If closing fails without an existing primary error or cancellation. |
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 | |
httpdict | HTTP configuration dictionary with middleware settings. |
defaultorionis.http.default.contracts.responses.IDefaultResponses | Default response handler for middleware rejections. |
underbool | Value supplied for under_maintenance. |
| Returns | |
None | Initialize default HTTP middleware stack. |
Exception, request: object, policy: IHttpEndpointPolicy | None) -> Response:
(source)
¶
Apply endpoint policies and application handling to an ordinary error.
| Parameters | |
exc:Exception | Error to report or translate. |
request:object | Typed request or the adapter used before routing. |
policy:orionis.http.contracts.endpoint_policy.IHttpEndpointPolicy | None | Optional endpoint-specific failure policy. |
| Returns | |
orionis.http.Response | Response produced by ordinary failure handling. |
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:orionis.http.adapters.request.contracts.transport.TransportAdapter | Transport adapter encapsulating the HTTP request. |
| Returns | |
orionis.http.Response | None | HTTP response if middleware rejects request, None if request passes all middleware checks. |
Exception, request: object, policy: IHttpEndpointPolicy | None = None) -> Response:
(source)
¶
Translate a caught exception into an HTTP response.
| Parameters | |
exc:Exception | The exception raised during request processing. |
request:object | Current request object (may be the raw transport adapter for pre-routing errors). |
policy:orionis.http.contracts.endpoint_policy.IHttpEndpointPolicy | None | Value supplied for policy. |
| Returns | |
orionis.http.Response | Appropriate HTTP response for the given exception type. |
Interface, adapter: TransportAdapter, receive_or_protocol: object, send: object = None):
(source)
¶
Dispatch a bounded connection inside a dedicated lifetime scope.
| Parameters | |
interface:orionis.http.enums.Interface | Server protocol identifier. |
adapter:orionis.http.adapters.request.contracts.transport.TransportAdapter | Handshake request metadata. |
receiveobject | ASGI receive callback or Granian WebsocketProtocol. |
send:object, optional | ASGI send callback, omitted for RSGI. |
| Returns | |
None | Complete connection handling and release acquired admission. |
Initialize the HTTP kernel with application and failure handler.
| Parameters | |
app:orionis.IApplication | Application instance providing configuration and DI container. |
catch:orionis.failure.contracts.ICatch | Failure handler used to format unhandled exceptions. |
| Returns | |
None | Initialize the HTTP kernel with application and failure handler. |
Exception, policy: IHttpEndpointPolicy | None) -> bool:
(source)
¶
Classify an error while observing failures of a custom classifier.
| Parameters | |
exc:Exception | Original error whose ownership must be preserved. |
policy:orionis.http.contracts.endpoint_policy.IHttpEndpointPolicy | None | Optional endpoint-specific failure policy. |
| Returns | |
bool | Whether the original error is expected. |
type, route: CompiledRoute, policy_instances: dict[ type[ IHttpEndpointPolicy], IHttpEndpointPolicy]):
(source)
¶
Bind one validated policy instance to a static HTTP endpoint.
| Parameters | |
controller:type | Controller declaring an optional HTTP protocol policy. |
route:orionis.http.routes.entities.compiled_route.CompiledRoute | Compiled route associated with the controller. |
policydict[type[IHttpEndpointPolicy], IHttpEndpointPolicy] | Policy instances already constructed during this kernel boot. |
| Returns | |
None | The endpoint uses the shared policy instance for its policy type. |
| Raises | |
TypeError | If a policy is not a policy class or the route is dynamic. |
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 | |
None | Import route handlers and prepare their dependency metadata at boot time. |
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 | |
None | Pre-build middleware instances for all routes at boot time. |
Interface, adapter: TransportAdapter, receive_or_protocol: object, request_context: ScopeManager, policy: IHttpEndpointPolicy | None = None) -> Response:
(source)
¶
Build the HTTP response for this request.
Runs global middleware, rate limiting, route resolution, and the handler pipeline. Debug dumps interrupt only this request with an HTML response; ordinary errors are delegated to __handleException.
| Parameters | |
interface:orionis.http.enums.Interface | Transport interface type used to construct the BodyStream. |
adapter:orionis.http.adapters.request.contracts.transport.TransportAdapter | Protocol adapter carrying request metadata. |
receiveobject | ASGI receive callable or RSGI HTTPProtocol instance. |
requestorionis.container.context.manager.ScopeManager | Active DI request scope for per-request bindings. |
policy:orionis.http.contracts.endpoint_policy.IHttpEndpointPolicy | None | Value supplied for policy. |
| Returns | |
orionis.http.Response | The fully constructed HTTP response. |
Validate a handshake and run its connection middleware and handler.
| Parameters | |
adapter:orionis.http.adapters.request.contracts.transport.TransportAdapter | Handshake metadata for global guards and route matching. |
socket:orionis.http.WebSocket | Connection already bound to the active application scope. |
| Returns | |
None | Reject the handshake or await the application connection lifetime. |
| Raises | |
TypeError | If middleware returns a value instead of None. |
Request, resolved_route: ResolvedRoute) -> Response:
(source)
¶
Execute route-level middleware for the resolved route.
| Parameters | |
request:orionis.http.Request | Incoming HTTP request. |
resolvedorionis.http.routes.entities.resolved_route.ResolvedRoute | Resolved route with matched handler and path parameters. |
| Returns | |
orionis.http.Response | HTTP response produced by the pipeline or the handler. |
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:orionis.http.Request | Incoming HTTP request. |
resolvedorionis.http.routes.entities.resolved_route.ResolvedRoute | Resolved route metadata. |
| Returns | |
orionis.http.Response | HTTP response produced by the middleware pipeline. |
Initialize route resolver with loaded routes.
Build a route resolver instance configured with routes loaded from the provided route loader and cache settings.
| Parameters | |
routeorionis.http.routes.contracts.loader.IRouteLoader | Route loader instance to discover and load routes. |
| Returns | |
None | Initialize route resolver with loaded routes. |
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:orionis.http.adapters.request.rsgi.RSGITransportAdapter | RSGI transport adapter with HTTP scope and client connection. |
response:orionis.http.Response | HTTP response object to send to client. |
protocol:granian.rsgi.HTTPProtocol | RSGI HTTP protocol version indicator. |
policy:orionis.http.contracts.endpoint_policy.IHttpEndpointPolicy | None | Value supplied for policy. |
| Returns | |
None | Send an RSGI HTTP response through the transport adapter. |
TransportAdapter, socket: WebSocket, interface: Interface):
(source)
¶
Run an admitted connection and observe errors before transport cleanup.
| Parameters | |
adapter:TransportAdapter | Adapter used to resolve the connection endpoint. |
socket:WebSocket | Admitted socket whose closure this boundary owns. |
interface:Interface | Server protocol attached to failure metadata. |
| Returns | |
None | Finish handling and attempt closure without replacing an escaping error. |
Cancel connection lifetimes within the existing shutdown lifecycle.
| Returns | |
None | Await cooperative cleanup for at most five seconds. |
Check browser origins before allowing an application handshake.
| Parameters | |
adapter:orionis.http.adapters.request.contracts.transport.TransportAdapter | Proxy-normalized handshake metadata. |
| Returns | |
bool | True for missing Origin, same origin, or an explicit allowed origin. |
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:orionis.http.Request | Incoming HTTP request. |
resolvedorionis.http.routes.entities.resolved_route.ResolvedRoute | Resolved route metadata. |
| Returns | |
orionis.http.Response | Handler response, or a redirect back carrying the errors. |
Boot the HTTP kernel by initializing all core components.
| Returns | |
None | Boot the HTTP kernel by initializing all core components. |
Scope, protocol: HTTPProtocol | WebsocketProtocol) -> object | None:
(source)
¶
Handle an incoming RSGI HTTP request end-to-end.
| Parameters | |
scope:granian.rsgi.Scope | Granian RSGI scope with connection metadata. |
protocol:granian.rsgi.HTTPProtocol | RSGI protocol object for writing the response. |
| Returns | |
object | None | Result of sending the RSGI response, or None on error. |