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

Own tasks and pending client results for exactly one connection.

Method __init__ Bind connection state and initialize task, result, and write ownership.
Method _cancelTask Cancel unfinished invocation work without interrupting cleanup twice.
Method _cancelWork Reject pending client results and request cancellation of owned tasks.
Method _observe Observe a connection failure and retain ownership of pending reports.
Async Method _sendOwned Send within an owned incident context that survives caller cancellation.
Method _writeDone Retire a completed write and notify its waiter without losing failures.
Method bindFailureOperation Bind the current failure operation as the connection's incident boundary.
Method cancel Schedule cancellation once for an active invocation identifier.
Async Method cleanup Cancel owned work, join cleanup, and release connection task registries.
Method complete Settle a pending client invocation and ignore late or duplicate completions.
Method finish Release an invocation ID while retaining ownership of terminal delivery.
Method invocationDone Retire a completed invocation and observe unhandled task failures.
Async Method invoke Invoke a client method and release its pending result on every exit.
Async Method send Encode a protocol envelope and await its serialized transport write.
Async Method sendEncoded Serialize an encoded message while retaining ownership of its write task.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _cancel_requested Cancel requested produced by set.
Instance Variable _counter Counter value used by RealtimeConnection.
Instance Variable _failure_operation Connection boundary receiving fatal child-task incident identity.
Instance Variable _failure_runtime Application runtime retained through connection cleanup.
Instance Variable _reports Failure delivery tasks owned by this connection.
Instance Variable _write_lock Synchronization primitive controlling access to write lock.
Instance Variable _write_task Background task sending queued messages to the connection.
Instance Variable active Operations currently running for this connection or transport.
Instance Variable closing Closing flag used by RealtimeConnection.
Instance Variable config Invocation and broadcast limits.
Instance Variable context Connection identity and public socket.
Instance Variable failure Failure retained for propagation or reporting.
Instance Variable finishing Finishing produced by set.
Instance Variable hub Application-owned Hub type.
Instance Variable owner Owner produced by asyncio.current_task.
Instance Variable pending Work that has been admitted and is awaiting completion.
Instance Variable protocol Route-selected codec.
Instance Variable ready Ready flag used by RealtimeConnection.
Instance Variable socket WebSocket associated with the current realtime invocation.
Property failureRuntime Return the retained runtime used for connection failure delivery.
def __init__(self, context: HubContext, hub: type[Hub], protocol: HubProtocol, config: RealtimeConfig, *, runtime: FailureRuntime | None = None): (source)

Bind connection state and initialize task, result, and write ownership.

Parameters
context:orionis.realtime.HubContextConnection identity and public socket to retain.
hub:type[orionis.realtime.Hub]Hub class defining this connection's namespace.
protocol:orionis.realtime.HubProtocolRoute-selected codec used for connection messages.
config:orionis.realtime.config.RealtimeConfigInvocation, client-result, and delivery limits.
runtime:orionis.failure.runtime.FailureRuntime or None, optionalRuntime for failure delivery; None retains the current runtime.
Returns
NoneInitialize owned tasks, pending results, and serialized write state.
Raises
RuntimeErrorIf no event loop is running while identifying the owner task.
def _cancelTask(self, task: asyncio.Task[None]): (source)

Cancel unfinished invocation work without interrupting cleanup twice.

Parameters
task:asyncio.Task[None]Admitted invocation targeted by a deferred cancellation callback.
Returns
NoneCancel only tasks that are not finishing, done, or already cancelling.
def _cancelWork(self) -> tuple[asyncio.Task, ...]: (source)

Reject pending client results and request cancellation of owned tasks.

Returns
tuple[asyncio.Task, ...]Invocation tasks and any retained write task for the caller to join; do not await them here.
def _observe(self, error: BaseException, phase: str): (source)

Observe a connection failure and retain ownership of pending reports.

Parameters
error:BaseExceptionConnection, invocation-cleanup, or transport failure to observe.
phase:strRealtime lifecycle phase identifying the failure.
Returns
NonePreserve incident correlation across callbacks and track any pending failure delivery until completion.
async def _sendOwned(self, data: str | bytes): (source)

Send within an owned incident context that survives caller cancellation.

Parameters
data:str | bytesEncoded message passed unchanged to the socket.
Returns
NoneComplete the socket send under connection-level failure ownership.
Raises
BaseExceptionIf the send fails or is cancelled. Observe non-cancellation failures before propagating them.
def _writeDone(self, task: asyncio.Task[None], *, ready: asyncio.Future | None = None): (source)

Retire a completed write and notify its waiter without losing failures.

Parameters
task:asyncio.Task[None]Completed task owning the sole in-flight transport write.
ready:asyncio.Future or None, optionalCompletion notification for the task's original waiter, if supplied.
Returns
NoneRelease write ownership, observe failures, and notify an unfinished waiter; begin shutdown after a failed or cancelled write.
def bindFailureOperation(self): (source)

Bind the current failure operation as the connection's incident boundary.

Returns
NoneRetain the current operation for later incident handoff, or clear the saved boundary when none is active.
def cancel(self, invocation_id: str): (source)

Schedule cancellation once for an active invocation identifier.

Parameters
invocation_id:strActive invocation identifier; ignore unknown or already requested IDs.
Returns
NoneDefer cancellation to the event loop so admitted work can enter cleanup.
Raises
RuntimeErrorIf cancellation needs scheduling but no event loop is running.
async def cleanup(self): (source)

Cancel owned work, join cleanup, and release connection task registries.

Returns
NoneDrain owned tasks and pending failure reports before clearing registries and owner references.
Raises
BaseExceptionIf joining or failure observation fails, including cancellation; clear registries and owner references before propagating it.
def complete(self, completion: Completion): (source)

Settle a pending client invocation and ignore late or duplicate completions.

Parameters
completion:orionis.realtime.protocol.CompletionValidated completion identifying a pending client invocation.
Returns
NoneRemove the pending ID and store its result or a sanitized client error; ignore absent or already settled futures.
def finish(self, invocation_id: str): (source)

Release an invocation ID while retaining ownership of terminal delivery.

Parameters
invocation_id:strIdentifier owned by the current task; ignore attempts from other tasks.
Returns
NoneMove the current ID owner from active work to terminal-delivery tracking.
Raises
RuntimeErrorIf no event loop is running to identify the current task.
def invocationDone(self, invocation_id: str, task: asyncio.Task[None]): (source)

Retire a completed invocation and observe unhandled task failures.

Parameters
invocation_id:strIdentifier originally owned by this invocation task.
task:asyncio.Task[None]Completed invocation whose local cleanup has already run.
Returns
NoneRetire ownership without disturbing a reused ID and observe task failures, requesting shutdown only for a new unhandled failure.
async def invoke(self, target: str, *args: object, timeout: float | None = None) -> object: (source)

Invoke a client method and release its pending result on every exit.

Parameters
target:strPublic client method identifier, at most 128 characters.
*args:objectUp to 64 positional arguments accepted by the selected codec.
timeout:float or None, optionalTotal send-and-result deadline in seconds; None uses the configured client-result timeout.
Returns
objectValue carried by a successful client completion, which may be None.
Raises
ConnectionErrorIf the connection is not ready, is closing, or disconnects.
RuntimeErrorIf the configured pending-result budget is exhausted.
ValueErrorIf the target, argument count, deadline, or encoded payload is invalid.
TypeErrorIf the selected codec cannot encode an argument value.
TimeoutErrorIf sending or awaiting the completion exceeds the total deadline.
orionis.realtime.errors.ClientInvocationErrorIf the client returns an error, represented by a sanitized exception.
asyncio.CancelledErrorIf the invocation is cancelled; release its pending-result entry.
async def send(self, envelope: object): (source)

Encode a protocol envelope and await its serialized transport write.

Parameters
envelope:objectProtocol message accepted by the selected connection codec.
Returns
NoneEncode the message and complete its ordered transport write.
Raises
TypeError, ValueErrorIf the codec cannot encode the envelope.
ConnectionErrorIf connection shutdown begins before write admission.
asyncio.CancelledErrorIf delivery is cancelled; an admitted write remains connection-owned.
async def sendEncoded(self, data: str | bytes): (source)

Serialize an encoded message while retaining ownership of its write task.

An admitted write outlives caller cancellation until it finishes or connection cleanup cancels it.

Parameters
data:str | bytesImmutable envelope already encoded for this connection's codec.
Returns
NoneComplete this message's ordered transport write.
Raises
ConnectionErrorIf connection shutdown begins before write admission.
asyncio.CancelledErrorIf the caller or owned write is cancelled; caller cancellation does not itself cancel an admitted write.
BaseExceptionIf the owned transport write fails.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

_cancel_requested: set[str] = (source)

Cancel requested produced by set.

_counter: int = (source)

Counter value used by RealtimeConnection.

_failure_operation = (source)

Connection boundary receiving fatal child-task incident identity.

_failure_runtime = (source)

Application runtime retained through connection cleanup.

Failure delivery tasks owned by this connection.

_write_lock = (source)

Synchronization primitive controlling access to write lock.

Background task sending queued messages to the connection.

Operations currently running for this connection or transport.

Closing flag used by RealtimeConnection.

Invocation and broadcast limits.

Connection identity and public socket.

Failure retained for propagation or reporting.

Finishing produced by set.

Application-owned Hub type.

Owner produced by asyncio.current_task.

Work that has been admitted and is awaiting completion.

protocol = (source)

Route-selected codec.

Ready flag used by RealtimeConnection.

WebSocket associated with the current realtime invocation.

Return the retained runtime used for connection failure delivery.

Returns
orionis.failure.runtime.FailureRuntime or NoneRuntime captured at construction, or None if none was available.