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.
Execute a precompiled Hub using the existing application and scopes.
| Async Static Method | _error |
Send a sanitized terminal error with optional admission observation. |
| Method | __init__ |
Bind application services and compile a Hub's remote dispatch metadata. |
| Method | _bind |
Bind connection state and targeting helpers into the supplied scope. |
| Async Method | _build |
Build a Hub instance and attach connection-scoped client/group helpers. |
| Async Method | _disconnect |
Run the disconnect hook with a deadline, then close any open socket. |
| Async Method | _finish |
Finalize connection work while preserving an escaping primary failure. |
| Async Method | _invoke |
Execute one remote method with isolated dependencies and authentication. |
| Async Method | _receive |
Read Hub messages while admitted invocations execute concurrently. |
| Async Method | _start |
Admit a validated client invocation or send a controlled rejection. |
| Async Method | _stream |
Deliver stream items with send backpressure and close the source iterator. |
| Async Method | serve |
Serve one scoped Hub connection and finalize its owned work. |
| Class Variable | __slots__ |
Declare the instance attribute slots reserved by this class. |
| Instance Variable | _app |
Existing application and dependency container. |
| Instance Variable | _dispatch |
Dispatch produced by compile_hub. |
| Instance Variable | _hub |
Application-declared Hub class. |
| Instance Variable | _manager |
Shared worker-local registry and targeting service. |
| Instance Variable | _protocol |
JSON or MessagePack selected by the route. |
RealtimeConnection, invocation_id: str, code: str, *, streaming: bool = False, observed: bool = False):
(source)
¶
Send a sanitized terminal error with optional admission observation.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Destination connection and failure-observation runtime. |
invocationstr | Validated identifier used for response and incident correlation. |
code:str | Stable classification controlling the public error code and safe message. |
streaming:bool, optional | Terminate a stream instead of a scalar invocation. |
observed:bool, optional | Suppress duplicate admission observation for an already reported failure. |
| Returns | |
None | Send the terminal envelope after releasing any ID owned by the current task; skip writes to a closing or closed connection. |
| Raises | |
ConnectionError | If connection shutdown starts before the write acquires ownership. |
asyncio.CancelledError | If the terminal delivery wait is cancelled. |
IApplication, manager: IConnectionManager, hub: type[ Hub], protocol: str = 'json'):
(source)
¶
Bind application services and compile a Hub's remote dispatch metadata.
| Parameters | |
app:orionis.IApplication | Existing application used for dependency resolution and scoped execution. |
manager:orionis.realtime.contracts.manager.IConnectionManager | Shared connection registry and client-targeting service. |
hub:type[orionis.realtime.Hub] | Hub class whose remote methods and lifecycle hooks should run. |
protocol:str, optional | Route-selected JSON or MessagePack codec name. |
| Returns | |
None | Store services and compile the Hub method table and selected codec. |
| Raises | |
TypeError | If Hub metadata, remote descriptors, or type annotations are unsupported. |
ValueError | If remote names, aliases, protocol, or message-size settings are invalid. |
Bind connection state and targeting helpers into the supplied scope.
| Parameters | |
scope:orionis.container.context.manager.ScopeManager | Active connection or invocation dependency scope to populate. |
connection:orionis.realtime.connection.RealtimeConnection | Connection supplying the socket, identity, and Hub namespace. |
| Returns | |
None | Register socket, context, connection, client/group helpers, and the HTTP kernel marker. |
Build a Hub instance and attach connection-scoped client/group helpers.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Connection supplying lifecycle context and client targeting. |
| Returns | |
orionis.realtime.Hub | Hub with constructor dependencies, context, clients, and groups bound. |
Run the disconnect hook with a deadline, then close any open socket.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Connection already removed from the manager's registry. |
code:int | Status supplied to the hook and normalized for the outbound close frame. |
reason:str | Reason supplied to onDisconnect, not sent in the close frame. |
| Returns | |
None | Bound the hook to five seconds, observe ordinary hook failures, and close an open socket with an admissible wire status. |
| Raises | |
asyncio.CancelledError | If the hook or socket closure is cancelled. |
BaseException | If socket closure or another unhandled disconnect operation fails. |
RealtimeConnection, code: int, reason: str, original: BaseException | None):
(source)
¶
Finalize connection work while preserving an escaping primary failure.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Connection whose work, registration, and disconnect hook need cleanup. |
code:int | Selected close status passed to disconnect handling. |
reason:str | Peer or local close reason supplied to the disconnect hook. |
original:BaseException or None | Failure already escaping from the connection body, if any. |
| Returns | |
None | Join owned cleanup, unregister the connection, and run disconnect handling. |
| Raises | |
BaseException | If finalization fails; preserve original when present, otherwise keep a prior cleanup failure primary over a later close failure. |
RealtimeConnection, method: RemoteMethod, envelope: Invoke, auth: AuthenticationContext):
(source)
¶
Execute one remote method with isolated dependencies and authentication.
Defer terminal delivery until producer cleanup and invocation-scope exit have run.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Owner of invocation tasks and response delivery. |
method:orionis.realtime.metadata.RemoteMethod | Compiled method, argument bindings, and dependency metadata. |
envelope:orionis.realtime.protocol.Invoke | Validated client values and optional invocation timeout. |
auth:orionis.auth.context.AuthenticationContext | Forked authentication state with an independent authorization cache. |
| Returns | |
None | Send scalar completion, stream termination, or a sanitized failure after exiting the invocation scope. |
| Raises | |
asyncio.CancelledError | If the invocation is cancelled, after attempting its terminal response. |
BaseException | If terminal delivery, cleanup, or unhandled control flow escapes the invocation boundary. |
Read Hub messages while admitted invocations execute concurrently.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Ready connection whose socket this method owns as the sole reader. |
| Returns | |
tuple[int, str] | Peer disconnect code and reason, or (1000, "") when local reading ends. |
| Raises | |
orionis.realtime.errors.ProtocolError | If decoding fails or an active invocation ID is reused. |
orionis.http.WebSocketDisconnected | If socket operations report peer disconnection. |
asyncio.CancelledError | If the connection's reader task is cancelled. |
Admit a validated client invocation or send a controlled rejection.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Connection owning invocation IDs, task capacity, and client delivery. |
envelope:orionis.realtime.protocol.Invoke | Decoded invocation to check against compiled methods and limits. |
| Returns | |
None | Register a task with forked authentication state, or send a rejection for method, concurrency, timeout, or context failures. |
| Raises | |
orionis.realtime.errors.ProtocolError | If the client reuses an active invocation ID. |
RealtimeConnection, invocation_id: str, source: AsyncIterable[ object]):
(source)
¶
Deliver stream items with send backpressure and close the source iterator.
| Parameters | |
connection:orionis.realtime.connection.RealtimeConnection | Connection whose serialized writes govern producer backpressure. |
invocationstr | Invocation identifier attached to each stream item. |
source:collections.abc.AsyncIterable[object] | Application-produced iterable whose iterator owns streaming cleanup. |
| Returns | |
None | Finish ordered item delivery and invoke the iterator's optional asynchronous close hook. |
| Raises | |
BaseException | If iteration, encoding, delivery, or cleanup fails, including cancellation. Preserve the primary failure if cleanup also fails. |
Serve one scoped Hub connection and finalize its owned work.
| Parameters | |
socket:orionis.http.WebSocket | WebSocket already bound to the application's active connection scope. |
| Returns | |
None | Run connection hooks and message dispatch, then remove registry ownership and close the socket. |
| Raises | |
RuntimeError | If the application has no active connection scope. |
asyncio.CancelledError | If owner cancellation is not replaced by a recorded fatal task failure. |
BaseException | If a fatal child, connection hook, or finalization failure escapes. |