orionis.http.WebSocket

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 WebSocket: (source)

Constructor: WebSocket(transport, adapter, params, max_message_size)

View In Hierarchy

Own one server-independent connection with direct awaited messaging.

Method	`__aiter__`	Iterate data messages until the peer disconnects.
Async Method	`__anext__`	Receive the next application message for asynchronous iteration.
Method	`__init__`	Bind a normalized transport and connection metadata.
Method	`_disconnected`	Retain terminal metadata for later operation failures.
Async Method	`_receiveData`	Receive data while translating disconnects to exceptions.
Method	`_requireOpen`	Reject messaging outside the connected lifecycle state.
Async Method	`accept`	Accept the pending handshake exactly once.
Async Method	`close`	Close an accepted connection or reject a pending handshake once.
Async Method	`receive`	Receive one immutable data or disconnect message.
Async Method	`receiveBytes`	Receive one binary payload.
Async Method	`receiveJson`	Decode the next text or binary JSON message with msgspec.
Async Method	`receiveText`	Receive one text payload.
Async Method	`reject`	Reject the pending handshake once.
Method	`routeParams`	Return mutable connection-local route parameters.
Async Method	`send`	Send text or bytes through a serialized, awaited transport write.
Async Method	`sendBytes`	Send one binary message without copying the payload.
Async Method	`sendJson`	Encode a JSON value and send one UTF-8 text message.
Async Method	`sendText`	Send one text message with natural backpressure.
Class Variable	`__slots__`	Undocumented
Instance Variable	`_accepted`	Undocumented
Instance Variable	`_adapter`	Undocumented
Instance Variable	`_close_code`	Undocumented
Instance Variable	`_close_reason`	Undocumented
Instance Variable	`_connection_state`	Undocumented
Instance Variable	`_max_message_size`	Undocumented
Instance Variable	`_params`	Undocumented
Instance Variable	`_receive_lock`	Undocumented
Instance Variable	`_send_lock`	Undocumented
Instance Variable	`_state`	Undocumented
Instance Variable	`_transport`	Undocumented
Property	`accepted`	Report completed or interrupted acceptance.
Property	`closed`	Report terminal connection closure.
Property	`connectionState`	Return the explicit lifecycle state.
Property	`headers`	Return handshake headers.
Property	`path`	Return the handshake path.
Property	`state`	Return connection-local application state.
Property	`supportsCloseDetails`	Report support for custom wire close details.

def __aiter__(self) -> WebSocket: (source) ¶

Iterate data messages until the peer disconnects.

Returns
`WebSocket`	This connection as a single-consumer async iterator.

async def __anext__(self) -> WebSocketMessage: (source) ¶

Receive the next application message for asynchronous iteration.

Returns
`WebSocketMessage`	Next text or binary message.

Raises
`StopAsyncIteration`	If connection closure is observed.

def __init__(self, transport: IWebSocketTransport, adapter: TransportAdapter, *, params: Mapping[str, object] | None = None, max_message_size: int = _DEFAULT_MESSAGE_LIMIT): (source) ¶

Bind a normalized transport and connection metadata.

Parameters
transport:`IWebSocketTransport`	Server adapter implementing awaited network operations.
adapter:`TransportAdapter`	Handshake metadata, including normalized proxy information.
params:`Mapping[str, object] \| None, optional`	Converted route parameters owned by this connection.
max_message_size:`int, optional`	Positive maximum incoming message size in bytes.

Returns
`None`	Prepare a connection awaiting explicit acceptance.

Raises
`ValueError`	If the message size limit is not a positive integer.

def _disconnected(self, code: int, reason: str = ''): (source) ¶

Retain terminal metadata for later operation failures.

Parameters
code:`int`	Observed or locally chosen close code.
reason:`str, optional`	Available close reason.

Returns
`None`	Transition to the terminal lifecycle state.

async def _receiveData(self) -> WebSocketMessage: (source) ¶

Receive data while translating disconnects to exceptions.

Returns
`WebSocketMessage`	Text or binary data message.

Raises
`WebSocketDisconnected`	If the peer sends its terminal event.

def _requireOpen(self): (source) ¶

Reject messaging outside the connected lifecycle state.

Returns
`None`	Validate that the handshake completed and closure has not started.

Raises
`RuntimeError`	If acceptance has not completed.
`WebSocketDisconnected`	If the connection is closing or closed.

async def accept(self, *, subprotocol: str | None = None, headers: Mapping[str, str] | None = None): (source) ¶

Accept the pending handshake exactly once.

Parameters
subprotocol:`str \| None, optional`	Selected client-offered protocol, when supported by the server.
headers:`Mapping[str, str] \| None, optional`	Additional acceptance headers, when supported by the server.

Returns
`None`	Open the connection for messaging.

Raises
`RuntimeError`	If acceptance or closure already completed.
`WebSocketDisconnected`	If the peer closes during acceptance.

async def close(self, code: WebSocketStatus | int = WebSocketStatus.NORMAL_CLOSURE, reason: str = ''): (source) ¶

Close an accepted connection or reject a pending handshake once.

Parameters
code:`WebSocketStatus \| int, optional`	Valid wire close code.
reason:`str, optional`	Close reason bounded to 123 UTF-8 bytes.

Returns
`None`	Complete closure; repeated calls do nothing.

Raises
`ValueError`	If the code or reason is invalid.
`NotImplementedError`	If the transport cannot transmit custom close details.

async def receive(self) -> WebSocketMessage: (source) ¶

Receive one immutable data or disconnect message.

Returns
`WebSocketMessage`	Complete data or terminal peer event, delivered once.

Raises
`RuntimeError`	If unaccepted or another receiver is already active.
`WebSocketDisconnected`	If closed, oversized, or the underlying transport disconnects.

async def receiveBytes(self) -> bytes: (source) ¶

Receive one binary payload.

Returns
`bytes`	Original binary message.

Raises
`TypeError`	If the next message contains text.
`WebSocketDisconnected`	If the connection ends.

async def receiveJson(self) -> object: (source) ¶

Decode the next text or binary JSON message with msgspec.

Returns
`object`	Decoded JSON value.

Raises
`msgspec.DecodeError`	If the payload is invalid JSON.
`WebSocketDisconnected`	If the connection ends.

async def receiveText(self) -> str: (source) ¶

Receive one text payload.

Returns
`str`	Original text message.

Raises
`TypeError`	If the next message is binary.
`WebSocketDisconnected`	If the connection ends.

async def reject(self, status_code: int = 403): (source) ¶

Reject the pending handshake once.

Parameters
status_code:`int, optional`	HTTP error status when supported by the server.

Returns
`None`	Finish handshake denial; repeated calls do nothing.

Raises
`RuntimeError`	If acceptance was already attempted.
`ValueError`	If the status is not an HTTP error code.

def routeParams(self) -> dict[str, object]: (source) ¶

Return mutable connection-local route parameters.

Returns
`dict[str, object]`	Converted parameters used by handler injection.

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

Send text or bytes through a serialized, awaited transport write.

Parameters
data:`str \| bytes`	Complete message payload.

Returns
`None`	Deliver the message while preserving server backpressure.

Raises
`TypeError`	If data is neither text nor bytes.
`WebSocketDisconnected`	If the peer closes before delivery.

async def sendBytes(self, data: bytes): (source) ¶

Send one binary message without copying the payload.

Parameters
data:`bytes`	Complete binary payload.

Returns
`None`	Await the serialized write.

Raises
`TypeError`	If the payload is not bytes.

async def sendJson(self, data: object): (source) ¶

Encode a JSON value and send one UTF-8 text message.

Parameters
data:`object`	JSON-serializable value.

Returns
`None`	Await delivery of the msgspec encoded payload.

async def sendText(self, data: str): (source) ¶

Send one text message with natural backpressure.

Parameters
data:`str`	Complete text payload.

Returns
`None`	Await the serialized write.

Raises
`TypeError`	If the payload is not text.

__slots__: tuple[str, ...] = (source) ¶

Undocumented

_accepted: bool = (source) ¶

Undocumented

_adapter = (source) ¶

Undocumented

_close_code = (source) ¶

Undocumented

_close_reason = (source) ¶

Undocumented

_connection_state = (source) ¶

Undocumented

_max_message_size = (source) ¶

Undocumented

_params = (source) ¶

Undocumented

_receive_lock = (source) ¶

Undocumented

_send_lock = (source) ¶

Undocumented

_state = (source) ¶

Undocumented

_transport = (source) ¶

Undocumented

@property

accepted: bool = (source) ¶

Report completed or interrupted acceptance.

Returns
`bool`	Historical handshake indicator, retained after closure.

@property

closed: bool = (source) ¶

Report terminal connection closure.

Returns
`bool`	True when the connection is terminal.

@property

connectionState: WebSocketState = (source) ¶

Return the explicit lifecycle state.

Returns
`WebSocketState`	Current connection lifecycle phase.

@property

headers: Headers = (source) ¶

Return handshake headers.

Returns
`Headers`	Server supplied header collection.

@property

path: str = (source) ¶

Return the handshake path.

Returns
`str`	Path without query parameters.

@property

state: SimpleNamespace = (source) ¶

Return connection-local application state.

Returns
`SimpleNamespace`	Mutable attributes shared only by this connection's pipeline.

@property

supportsCloseDetails: bool = (source) ¶

Report support for custom wire close details.

Returns
`bool`	True when close codes and reasons can be transmitted.