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 worker-local connections and isolate every group by Hub class.

Registry mutations contain no await points and run on the application's event loop. Delivery snapshots identifiers before awaiting network I/O. Replacing IConnectionManager is the extension point for distributed delivery; the default registry never crosses process or worker boundaries.

Method __init__ Initialize connection and Hub-local group registries with validated limits.
Async Method broadcast Broadcast an envelope with per-codec encoding and bounded concurrency.
Method connectionIds Snapshot ready, nonclosing connection identifiers in one Hub namespace.
Method get Return a ready, nonclosing connection within an optional Hub namespace.
Method groupIds Snapshot ready, nonclosing group members within one Hub namespace.
Method hub Create application-service client selectors for one Hub class.
Method join Join a nonclosing owned connection to a Hub-local group.
Method leave Remove an owned membership and discard empty Hub-local groups.
Method register Register a connection and its initial Hub-local membership state.
Method snapshot Return all currently owned connections for lifecycle coordination.
Method unregister Remove one owned connection and all of its group memberships.
Class Variable __slots__ Declare the instance attribute slots reserved by this class.
Instance Variable _config Group and broadcast limits shared by this application.
Instance Variable _connections Active realtime connections indexed by identifier.
Instance Variable _groups Realtime group membership and targeting interface.
Instance Variable _hubs Hub registrations associated with active connections.
Instance Variable _memberships Group memberships indexed by connection identifier.
Property config Return the application-wide realtime configuration.
Property connectionCount Count registered connections regardless of readiness or closing state.
Property groupCount Count nonempty groups across all Hub namespaces.
def __init__(self, config: RealtimeConfig): (source)

Initialize connection and Hub-local group registries with validated limits.

Parameters
config:orionis.realtime.config.RealtimeConfigRealtime limits shared by connections and broadcast workers.
Returns
NoneRetain configuration and create empty connection and membership indexes.
async def broadcast(self, hub: type[Hub], connection_ids: tuple[str, ...], envelope: object) -> BroadcastResult: (source)

Broadcast an envelope with per-codec encoding and bounded concurrency.

Parameters
hub:type[orionis.realtime.Hub]Exact Hub namespace restricting every recipient.
connection_ids:tuple[str, ...]Recipient identifier occurrences to attempt, without deduplication.
envelope:objectProtocol envelope accepted by the selected connection codecs.
Returns
orionis.realtime.BroadcastResultAggregate sent and failed counts, including unavailable recipients as failures. Empty input returns zero counts.
Raises
TypeError, ValueErrorIf encoding fails before recipient delivery starts.
asyncio.CancelledErrorIf delivery is cancelled; admitted connection-owned writes may finish independently.
def connectionIds(self, hub: type[Hub]) -> tuple[str, ...]: (source)

Snapshot ready, nonclosing connection identifiers in one Hub namespace.

Parameters
hub:type[orionis.realtime.Hub]Exact owning Hub class whose recipients should be selected.
Returns
tuple[str, ...]Ready recipient IDs at the time of the call; an unknown Hub produces an empty tuple.
def get(self, connection_id: str, hub: type[Hub] | None = None) -> RealtimeConnectionLike | None: (source)

Return a ready, nonclosing connection within an optional Hub namespace.

Parameters
connection_id:strRegistered connection identifier to resolve.
hub:type[orionis.realtime.Hub] or None, optionalExact owning Hub class, or None to disable namespace filtering.
Returns
orionis.realtime.contracts.connection.RealtimeConnectionLike or NoneReady, nonclosing connection, or None for absent, unready, closing, or differently namespaced entries.
def groupIds(self, hub: type[Hub], group: str) -> tuple[str, ...]: (source)

Snapshot ready, nonclosing group members within one Hub namespace.

Parameters
hub:type[orionis.realtime.Hub]Exact Hub class owning the requested group.
group:strGroup name within the selected Hub namespace.
Returns
tuple[str, ...]Ready member IDs at the time of the call, or an empty tuple for an unknown Hub or group.
Raises
ValueErrorIf the group name is invalid.
def hub(self, hub: type[Hub]) -> HubClients: (source)

Create application-service client selectors for one Hub class.

Parameters
hub:type[orionis.realtime.Hub]Hub class defining the recipient namespace.
Returns
orionis.realtime.HubClientsSelectors without a connection-specific caller, suitable for services.
Raises
TypeErrorIf the supplied value is not a Hub class.
def join(self, connection_id: str, group: str): (source)

Join a nonclosing owned connection to a Hub-local group.

Parameters
connection_id:strRegistered connection identifier, including provisional connections.
group:strGroup name within the connection's owning Hub namespace.
Returns
NoneAdd membership, leaving repeated joins unchanged without using capacity.
Raises
ValueErrorIf the group name is invalid.
ConnectionErrorIf the connection is absent or closing.
RuntimeErrorIf adding a membership would exceed the connection's configured limit.
def leave(self, connection_id: str, group: str): (source)

Remove an owned membership and discard empty Hub-local groups.

Parameters
connection_id:strConnection whose membership should be removed, if still registered.
group:strValid group name in the connection's Hub namespace.
Returns
NoneDiscard owned membership; ignore absent IDs and repeated leaves.
Raises
ValueErrorIf the group name is invalid.
def register(self, connection: RealtimeConnectionLike): (source)

Register a connection and its initial Hub-local membership state.

Parameters
connection:orionis.realtime.contracts.connection.RealtimeConnectionLikeConnection with a valid identifier not already owned by this worker.
Returns
NoneRetain the connection and initialize its Hub and membership indexes.
Raises
ValueErrorIf the identifier is invalid or already belongs to a registered connection.
def snapshot(self) -> tuple[RealtimeConnectionLike, ...]: (source)

Return all currently owned connections for lifecycle coordination.

Returns
tuple[orionis.realtime.contracts.connection.RealtimeConnectionLike, ...]Registered connection references, including provisional and closing ones, at the time of the call.
def unregister(self, connection: RealtimeConnectionLike): (source)

Remove one owned connection and all of its group memberships.

Parameters
connection:orionis.realtime.contracts.connection.RealtimeConnectionLikeExact registered instance; ignore absent or replaced instances.
Returns
NoneRemove its registry and Hub entries and discard empty groups without affecting another instance that reused the identifier.
__slots__: tuple[str, ...] = (source)

Declare the instance attribute slots reserved by this class.

Group and broadcast limits shared by this application.

_connections: dict[str, RealtimeConnectionLike] = (source)

Active realtime connections indexed by identifier.

Realtime group membership and targeting interface.

Hub registrations associated with active connections.

_memberships: dict[str, set[str]] = (source)

Group memberships indexed by connection identifier.

config: RealtimeConfig = (source)

Return the application-wide realtime configuration.

Returns
orionis.realtime.config.RealtimeConfigInvocation, client-result, group, and broadcast limits used by the manager.
connectionCount: int = (source)

Count registered connections regardless of readiness or closing state.

Returns
intNumber of owned entries, including provisional and closing connections.

Count nonempty groups across all Hub namespaces.

Returns
intNumber of Hub/group entries with at least one registered member.