orionis.realtime.connection.RealtimeConnection

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.

Explore modules View classes

class documentation

class RealtimeConnection: (source)

Constructor: RealtimeConnection(context, hub, protocol, config)

View In Hierarchy

Own tasks and pending client results for exactly one connection.

Method	`__init__`	Bind immutable context and initialize finite connection registries.
Method	`_cancelTask`	Deliver at most one cancellation without interrupting cleanup again.
Method	`_writeDone`	Release write ownership even when its original caller was cancelled.
Method	`cancel`	Schedule one cancellation after an admitted task can enter its finally.
Async Method	`cleanup`	Cancel owned work and release every retained task and Future.
Method	`complete`	Correlate a completion without retaining duplicate or late messages.
Method	`finish`	Release a completed ID while retaining its terminal delivery task.
Method	`invocationDone`	Retrieve invocation failures and wake a reader after fatal delivery.
Async Method	`invoke`	Invoke one client and release its Future on every exit path.
Async Method	`send`	Encode and await delivery of a protocol envelope.
Async Method	`sendEncoded`	Await one serialized write without letting RPC cancellation tear it.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_cancel_requested`	Undocumented
Instance Variable	`_counter`	Undocumented
Instance Variable	`_write_lock`	Undocumented
Instance Variable	`_write_task`	Undocumented
Instance Variable	`active`	Undocumented
Instance Variable	`closing`	Undocumented
Instance Variable	`config`	Undocumented
Instance Variable	`context`	Undocumented
Instance Variable	`failure`	Undocumented
Instance Variable	`finishing`	Undocumented
Instance Variable	`hub`	Undocumented
Instance Variable	`owner`	Undocumented
Instance Variable	`pending`	Undocumented
Instance Variable	`protocol`	Undocumented
Instance Variable	`ready`	Undocumented
Instance Variable	`socket`	Undocumented

def __init__(self, context: HubContext, hub: type[Hub], protocol: HubProtocol, config: RealtimeConfig): (source) ¶

Bind immutable context and initialize finite connection registries.

Parameters
context:`HubContext`	Connection identity and public socket.
hub:`type[Hub]`	Application-owned Hub type.
protocol:`HubProtocol`	Route-selected codec.
config:`RealtimeConfig`	Invocation and broadcast limits.

Returns
`None`	Initialize owned tasks, pending results and serialized write state.

Raises
`RuntimeError`	If no event loop is running to identify the connection owner.

def _cancelTask(self, task: asyncio.Task[None]): (source) ¶

Deliver at most one cancellation without interrupting cleanup again.

Parameters
task:`asyncio.Task[None]`	Invocation admitted before this event-loop callback was scheduled.

Returns
`None`	Cancel the task unless it is finishing, done or already cancelling.

def _writeDone(self, task: asyncio.Task[None]): (source) ¶

Release write ownership even when its original caller was cancelled.

Parameters
task:`asyncio.Task[None]`	Completed task for the sole in-flight transport write.

Returns
`None`	Release the write lock and cancel the owner after a failed write.

def cancel(self, invocation_id: str): (source) ¶

Schedule one cancellation after an admitted task can enter its finally.

Parameters
invocation_id:`str`	Active invocation to cancel; unknown IDs are ignored.

Returns
`None`	Schedule cancellation once for the selected active invocation.

Raises
`RuntimeError`	If cancellation needs scheduling but no event loop is running.

async def cleanup(self): (source) ¶

Cancel owned work and release every retained task and Future.

Returns
`None`	Finish cooperative cancellation before the connection scope exits.

Raises
`asyncio.CancelledError`	If cleanup is cancelled while joining tasks; task registries and owner references are still cleared.

def complete(self, completion: Completion): (source) ¶

Correlate a completion without retaining duplicate or late messages.

Parameters
completion:`Completion`	Validated client completion.

Returns
`None`	Resolve the pending result or record a sanitized client error; ignore unknown, duplicate and already completed identifiers.

def finish(self, invocation_id: str): (source) ¶

Release a completed ID while retaining its terminal delivery task.

Parameters
invocation_id:`str`	ID belonging to the current invocation task. Admission errors from the connection reader cannot release another invocation's ownership.

Returns
`None`	Move the current owned invocation from active to finishing tasks.

Raises
`RuntimeError`	If no event loop is running to identify the current task.

def invocationDone(self, invocation_id: str, task: asyncio.Task[None]): (source) ¶

Retrieve invocation failures and wake a reader after fatal delivery.

Parameters
invocation_id:`str`	Identifier owned by this task, including cancellation before entry.
task:`asyncio.Task[None]`	Invocation whose local cleanup has already run.

Returns
`None`	Release task ownership and cancel the connection owner on failure.

async def invoke(self, target: str, *args: object, timeout: float | None = None) -> object: (source) ¶

Invoke one client and release its Future on every exit path.

Parameters
target:`str`	Explicit client method name.
*args:`object`	Up to 64 serializable positional arguments.
timeout:`float \| None, optional`	Total send/result deadline in seconds. None uses the configured client-result timeout.

Returns
`object`	Client completion result, including `None`.

Raises
`ConnectionError`	If the target is not ready or disconnects.
`RuntimeError`	If the 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 receiving the completion exceeds the deadline.
`ClientInvocationError`	If the client returns a completion error.
`asyncio.CancelledError`	If the invocation is cancelled; its pending result is released.

async def send(self, envelope: object): (source) ¶

Encode and await delivery of a protocol envelope.

Parameters
envelope:`object`	Serializable Orionis protocol message.

Returns
`None`	Encode the envelope and complete its ordered transport write.

Raises
`TypeError, ValueError`	If the selected codec cannot encode the envelope.
`ConnectionError`	If connection cleanup has started.
`asyncio.CancelledError`	If delivery is cancelled; an already started write stays shielded.

async def sendEncoded(self, data: str | bytes): (source) ¶

Await one serialized write without letting RPC cancellation tear it.

Parameters
data:`str \| bytes`	Immutable, already encoded envelope.

Returns
`None`	Complete the ordered transport write while preserving backpressure.

Raises
`ConnectionError`	If cleanup has started.
`asyncio.CancelledError`	If the caller is cancelled; an already started write stays shielded until it finishes or connection cleanup cancels it.