Both sides (Sans-I/O)#

class websockets.protocol.Protocol(side, state=State.OPEN, max_size=2**20, logger=None)[source]#

Sans-I/O implementation of a WebSocket connection.

Parameters:

  • side (Side) – CLIENT or SERVER.

  • state (State) – initial state of the WebSocket connection.

  • max_size (Optional[int]) – maximum size of incoming messages in bytes; None disables the limit.

  • logger (Optional[LoggerLike]) – logger for this connection; depending on side, defaults to logging.getLogger("websockets.client") or logging.getLogger("websockets.server"); see the logging guide for details.

receive_data(data)[source]#

Receive data from the network.

After calling this method:

Raises:

EOFError – if receive_eof() was called earlier.

receive_eof()[source]#

Receive the end of the data stream from the network.

After calling this method:

  • You must call data_to_send() and send this data to the network; it will return [b""], signaling the end of the stream, or [].

  • You aren’t expected to call events_received(); it won’t return any new events.

Raises:

EOFError – if receive_eof() was called earlier.

send_continuation(data, fin)[source]#

Send a Continuation frame.

Parameters:

  • data (bytes) – payload containing the same kind of data as the initial frame.

  • fin (bool) – FIN bit; set it to True if this is the last frame of a fragmented message and to False otherwise.

Raises:

ProtocolError – if a fragmented message isn’t in progress.

send_text(data, fin=True)[source]#

Send a Text frame.

Parameters:

  • data (bytes) – payload containing text encoded with UTF-8.

  • fin (bool) – FIN bit; set it to False if this is the first frame of a fragmented message.

Raises:

ProtocolError – if a fragmented message is in progress.

send_binary(data, fin=True)[source]#

Send a Binary frame.

Parameters:

  • data (bytes) – payload containing arbitrary binary data.

  • fin (bool) – FIN bit; set it to False if this is the first frame of a fragmented message.

Raises:

ProtocolError – if a fragmented message is in progress.

send_close(code=None, reason='')[source]#

Send a Close frame.

Parameters:

  • code (int | None) – close code.

  • reason (str) – close reason.

Raises:

ProtocolError – if a fragmented message is being sent, if the code isn’t valid, or if a reason is provided without a code

send_ping(data)[source]#

Send a Ping frame.

Parameters:

data (bytes) – payload containing arbitrary binary data.

send_pong(data)[source]#

Send a Pong frame.

Parameters:

data (bytes) – payload containing arbitrary binary data.

fail(code, reason='')[source]#

Fail the WebSocket connection.

Parameters:

  • code (int) – close code

  • reason (str) – close reason

Raises:

ProtocolError – if the code isn’t valid.

events_received()[source]#

Fetch events generated from data received from the network.

Call this method immediately after any of the receive_*() methods.

Process resulting events, likely by passing them to the application.

Returns:

Events read from the connection.

Return type:

List[Event]

data_to_send()[source]#

Obtain data to send to the network.

Call this method immediately after any of the receive_*(), send_*(), or fail() methods.

Write resulting data to the connection.

The empty bytestring SEND_EOF signals the end of the data stream. When you receive it, half-close the TCP connection.

Returns:

Data to write to the connection.

Return type:

List[bytes]

close_expected()[source]#

Tell if the TCP connection is expected to close soon.

Call this method immediately after any of the receive_*(), send_close(), or fail() methods.

If it returns True, schedule closing the TCP connection after a short timeout if the other side hasn’t already closed it.

Returns:

Whether the TCP connection is expected to close soon.

Return type:

bool

id: UUID#

Unique identifier of the connection. Useful in logs.

logger: Logger | LoggerAdapter#

Logger for this connection.

property state: State#

WebSocket connection state.

Defined in 4.1, 4.2, 7.1.3, and 7.1.4 of RFC 6455.

property close_code: int | None#

WebSocket close code.

None if the connection isn’t closed yet.

property close_reason: str | None#

WebSocket close reason.

None if the connection isn’t closed yet.

property close_exc: ConnectionClosed#

Exception to raise when trying to interact with a closed connection.

Don’t raise this exception while the connection state is CLOSING; wait until it’s CLOSED.

Indeed, the exception includes the close code and reason, which are known only once the connection is closed.

Raises:

AssertionError – if the connection isn’t closed yet.

class websockets.protocol.Side(value)[source]#

A WebSocket connection is either a server or a client.

SERVER = 0#
CLIENT = 1#
class websockets.protocol.State(value)[source]#

A WebSocket connection is in one of these four states.

CONNECTING = 0#
OPEN = 1#
CLOSING = 2#
CLOSED = 3#
websockets.protocol.SEND_EOF = b''#

Sentinel signaling that the TCP connection must be half-closed.