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

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 _bindContext Bind connection state and targeting helpers into the supplied scope.
Async Method _buildHub 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 _finishConnection 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 _startInvocation 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.
async def _error(connection: 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.RealtimeConnectionDestination connection and failure-observation runtime.
invocation_id:strValidated identifier used for response and incident correlation.
code:strStable classification controlling the public error code and safe message.
streaming:bool, optionalTerminate a stream instead of a scalar invocation.
observed:bool, optionalSuppress duplicate admission observation for an already reported failure.
Returns
NoneSend the terminal envelope after releasing any ID owned by the current task; skip writes to a closing or closed connection.
Raises
ConnectionErrorIf connection shutdown starts before the write acquires ownership.
asyncio.CancelledErrorIf the terminal delivery wait is cancelled.
def __init__(self, app: IApplication, manager: IConnectionManager, hub: type[Hub], protocol: str = 'json'): (source)

Bind application services and compile a Hub's remote dispatch metadata.

Parameters
app:orionis.IApplicationExisting application used for dependency resolution and scoped execution.
manager:orionis.realtime.contracts.manager.IConnectionManagerShared connection registry and client-targeting service.
hub:type[orionis.realtime.Hub]Hub class whose remote methods and lifecycle hooks should run.
protocol:str, optionalRoute-selected JSON or MessagePack codec name.
Returns
NoneStore services and compile the Hub method table and selected codec.
Raises
TypeErrorIf Hub metadata, remote descriptors, or type annotations are unsupported.
ValueErrorIf remote names, aliases, protocol, or message-size settings are invalid.
def _bindContext(self, scope: ScopeManager, connection: RealtimeConnection): (source)

Bind connection state and targeting helpers into the supplied scope.

Parameters
scope:orionis.container.context.manager.ScopeManagerActive connection or invocation dependency scope to populate.
connection:orionis.realtime.connection.RealtimeConnectionConnection supplying the socket, identity, and Hub namespace.
Returns
NoneRegister socket, context, connection, client/group helpers, and the HTTP kernel marker.
async def _buildHub(self, connection: RealtimeConnection) -> Hub: (source)

Build a Hub instance and attach connection-scoped client/group helpers.

Parameters
connection:orionis.realtime.connection.RealtimeConnectionConnection supplying lifecycle context and client targeting.
Returns
orionis.realtime.HubHub with constructor dependencies, context, clients, and groups bound.
async def _disconnect(self, connection: RealtimeConnection, code: int, reason: str): (source)

Run the disconnect hook with a deadline, then close any open socket.

Parameters
connection:orionis.realtime.connection.RealtimeConnectionConnection already removed from the manager's registry.
code:intStatus supplied to the hook and normalized for the outbound close frame.
reason:strReason supplied to onDisconnect, not sent in the close frame.
Returns
NoneBound the hook to five seconds, observe ordinary hook failures, and close an open socket with an admissible wire status.
Raises
asyncio.CancelledErrorIf the hook or socket closure is cancelled.
BaseExceptionIf socket closure or another unhandled disconnect operation fails.
async def _finishConnection(self, connection: RealtimeConnection, code: int, reason: str, original: BaseException | None): (source)

Finalize connection work while preserving an escaping primary failure.

Parameters
connection:orionis.realtime.connection.RealtimeConnectionConnection whose work, registration, and disconnect hook need cleanup.
code:intSelected close status passed to disconnect handling.
reason:strPeer or local close reason supplied to the disconnect hook.
original:BaseException or NoneFailure already escaping from the connection body, if any.
Returns
NoneJoin owned cleanup, unregister the connection, and run disconnect handling.
Raises
BaseExceptionIf finalization fails; preserve original when present, otherwise keep a prior cleanup failure primary over a later close failure.
async def _invoke(self, connection: 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.RealtimeConnectionOwner of invocation tasks and response delivery.
method:orionis.realtime.metadata.RemoteMethodCompiled method, argument bindings, and dependency metadata.
envelope:orionis.realtime.protocol.InvokeValidated client values and optional invocation timeout.
auth:orionis.auth.context.AuthenticationContextForked authentication state with an independent authorization cache.
Returns
NoneSend scalar completion, stream termination, or a sanitized failure after exiting the invocation scope.
Raises
asyncio.CancelledErrorIf the invocation is cancelled, after attempting its terminal response.
BaseExceptionIf terminal delivery, cleanup, or unhandled control flow escapes the invocation boundary.
async def _receive(self, connection: RealtimeConnection) -> tuple[int, str]: (source)

Read Hub messages while admitted invocations execute concurrently.

Parameters
connection:orionis.realtime.connection.RealtimeConnectionReady 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.ProtocolErrorIf decoding fails or an active invocation ID is reused.
orionis.http.WebSocketDisconnectedIf socket operations report peer disconnection.
asyncio.CancelledErrorIf the connection's reader task is cancelled.
async def _startInvocation(self, connection: RealtimeConnection, envelope: Invoke): (source)

Admit a validated client invocation or send a controlled rejection.

Parameters
connection:orionis.realtime.connection.RealtimeConnectionConnection owning invocation IDs, task capacity, and client delivery.
envelope:orionis.realtime.protocol.InvokeDecoded invocation to check against compiled methods and limits.
Returns
NoneRegister a task with forked authentication state, or send a rejection for method, concurrency, timeout, or context failures.
Raises
orionis.realtime.errors.ProtocolErrorIf the client reuses an active invocation ID.
async def _stream(self, connection: RealtimeConnection, invocation_id: str, source: AsyncIterable[object]): (source)

Deliver stream items with send backpressure and close the source iterator.

Parameters
connection:orionis.realtime.connection.RealtimeConnectionConnection whose serialized writes govern producer backpressure.
invocation_id:strInvocation identifier attached to each stream item.
source:collections.abc.AsyncIterable[object]Application-produced iterable whose iterator owns streaming cleanup.
Returns
NoneFinish ordered item delivery and invoke the iterator's optional asynchronous close hook.
Raises
BaseExceptionIf iteration, encoding, delivery, or cleanup fails, including cancellation. Preserve the primary failure if cleanup also fails.
async def serve(self, socket: WebSocket): (source)

Serve one scoped Hub connection and finalize its owned work.

Parameters
socket:orionis.http.WebSocketWebSocket already bound to the application's active connection scope.
Returns
NoneRun connection hooks and message dispatch, then remove registry ownership and close the socket.
Raises
RuntimeErrorIf the application has no active connection scope.
asyncio.CancelledErrorIf owner cancellation is not replaced by a recorded fatal task failure.
BaseExceptionIf a fatal child, connection hook, or finalization failure escapes.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

Existing application and dependency container.

_dispatch = (source)

Dispatch produced by compile_hub.

Application-declared Hub class.

_manager = (source)

Shared worker-local registry and targeting service.

_protocol = (source)

JSON or MessagePack selected by the route.