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 RealtimeConnection: (source)
Constructor: RealtimeConnection(context, hub, protocol, config, ...)
Own tasks and pending client results for exactly one connection.
| Method | __init__ |
Bind connection state and initialize task, result, and write ownership. |
| Method | _cancel |
Cancel unfinished invocation work without interrupting cleanup twice. |
| Method | _cancel |
Reject pending client results and request cancellation of owned tasks. |
| Method | _observe |
Observe a connection failure and retain ownership of pending reports. |
| Async Method | _send |
Send within an owned incident context that survives caller cancellation. |
| Method | _write |
Retire a completed write and notify its waiter without losing failures. |
| Method | bind |
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 | invocation |
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 | send |
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 |
Cancel requested produced by set. |
| Instance Variable | _counter |
Counter value used by RealtimeConnection. |
| Instance Variable | _failure |
Connection boundary receiving fatal child-task incident identity. |
| Instance Variable | _failure |
Application runtime retained through connection cleanup. |
| Instance Variable | _reports |
Failure delivery tasks owned by this connection. |
| Instance Variable | _write |
Synchronization primitive controlling access to write lock. |
| Instance Variable | _write |
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 | failure |
Return the retained runtime used for connection failure delivery. |
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.HubContext | Connection identity and public socket to retain. |
hub:type[orionis.realtime.Hub] | Hub class defining this connection's namespace. |
protocol:orionis.realtime.HubProtocol | Route-selected codec used for connection messages. |
config:orionis.realtime.config.RealtimeConfig | Invocation, client-result, and delivery limits. |
runtime:orionis.failure.runtime.FailureRuntime or None, optional | Runtime for failure delivery; None retains the current runtime. |
| Returns | |
None | Initialize owned tasks, pending results, and serialized write state. |
| Raises | |
RuntimeError | If no event loop is running while identifying the owner task. |
Cancel unfinished invocation work without interrupting cleanup twice.
| Parameters | |
task:asyncio.Task[None] | Admitted invocation targeted by a deferred cancellation callback. |
| Returns | |
None | Cancel only tasks that are not finishing, done, or already cancelling. |
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. |
Observe a connection failure and retain ownership of pending reports.
| Parameters | |
error:BaseException | Connection, invocation-cleanup, or transport failure to observe. |
phase:str | Realtime lifecycle phase identifying the failure. |
| Returns | |
None | Preserve incident correlation across callbacks and track any pending failure delivery until completion. |
Send within an owned incident context that survives caller cancellation.
| Parameters | |
data:str | bytes | Encoded message passed unchanged to the socket. |
| Returns | |
None | Complete the socket send under connection-level failure ownership. |
| Raises | |
BaseException | If the send fails or is cancelled. Observe non-cancellation failures before propagating them. |
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, optional | Completion notification for the task's original waiter, if supplied. |
| Returns | |
None | Release write ownership, observe failures, and notify an unfinished waiter; begin shutdown after a failed or cancelled write. |
Bind the current failure operation as the connection's incident boundary.
| Returns | |
None | Retain the current operation for later incident handoff, or clear the saved boundary when none is active. |
Schedule cancellation once for an active invocation identifier.
| Parameters | |
invocationstr | Active invocation identifier; ignore unknown or already requested IDs. |
| Returns | |
None | Defer cancellation to the event loop so admitted work can enter cleanup. |
| Raises | |
RuntimeError | If cancellation needs scheduling but no event loop is running. |
Cancel owned work, join cleanup, and release connection task registries.
| Returns | |
None | Drain owned tasks and pending failure reports before clearing registries and owner references. |
| Raises | |
BaseException | If joining or failure observation fails, including cancellation; clear registries and owner references before propagating it. |
Settle a pending client invocation and ignore late or duplicate completions.
| Parameters | |
completion:orionis.realtime.protocol.Completion | Validated completion identifying a pending client invocation. |
| Returns | |
None | Remove the pending ID and store its result or a sanitized client error; ignore absent or already settled futures. |
Release an invocation ID while retaining ownership of terminal delivery.
| Parameters | |
invocationstr | Identifier owned by the current task; ignore attempts from other tasks. |
| Returns | |
None | Move the current ID owner from active work to terminal-delivery tracking. |
| Raises | |
RuntimeError | If no event loop is running to identify the current task. |
Retire a completed invocation and observe unhandled task failures.
| Parameters | |
invocationstr | Identifier originally owned by this invocation task. |
task:asyncio.Task[None] | Completed invocation whose local cleanup has already run. |
| Returns | |
None | Retire ownership without disturbing a reused ID and observe task failures, requesting shutdown only for a new unhandled failure. |
str, *args: object, timeout: float | None = None) -> object:
(source)
¶
Invoke a client method and release its pending result on every exit.
| Parameters | |
target:str | Public client method identifier, at most 128 characters. |
*args:object | Up to 64 positional arguments accepted by the selected codec. |
timeout:float or None, optional | Total send-and-result deadline in seconds; None uses the configured client-result timeout. |
| Returns | |
object | Value carried by a successful client completion, which may be None. |
| Raises | |
ConnectionError | If the connection is not ready, is closing, or disconnects. |
RuntimeError | If the configured pending-result budget is exhausted. |
ValueError | If the target, argument count, deadline, or encoded payload is invalid. |
TypeError | If the selected codec cannot encode an argument value. |
TimeoutError | If sending or awaiting the completion exceeds the total deadline. |
orionis.realtime.errors.ClientInvocationError | If the client returns an error, represented by a sanitized exception. |
asyncio.CancelledError | If the invocation is cancelled; release its pending-result entry. |
Encode a protocol envelope and await its serialized transport write.
| Parameters | |
envelope:object | Protocol message accepted by the selected connection codec. |
| Returns | |
None | Encode the message and complete its ordered transport write. |
| Raises | |
TypeError, ValueError | If the codec cannot encode the envelope. |
ConnectionError | If connection shutdown begins before write admission. |
asyncio.CancelledError | If delivery is cancelled; an admitted write remains connection-owned. |
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 | bytes | Immutable envelope already encoded for this connection's codec. |
| Returns | |
None | Complete this message's ordered transport write. |
| Raises | |
ConnectionError | If connection shutdown begins before write admission. |
asyncio.CancelledError | If the caller or owned write is cancelled; caller cancellation does not itself cancel an admitted write. |
BaseException | If the owned transport write fails. |
Return the retained runtime used for connection failure delivery.
| Returns | |
orionis.failure.runtime.FailureRuntime or None | Runtime captured at construction, or None if none was available. |