Both sides (Sans-I/O)

class websockets.protocol.Protocol(side, *, state=State.OPEN, max_size=1048576, 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 (int | None) – Maximum size of incoming messages in bytes; None disables the limit.

  • logger (LoggerLike | None) – 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.

receive_eof() is idempotent.

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 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[Request | Response | Frame]

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

State of the WebSocket connection.

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

property close_code: int | None

WebSocket close code received from the remote endpoint.

Defined in 7.1.5 of RFC 6455.

None if the connection isn’t closed yet.

property close_reason: str | None

WebSocket close reason received from the remote endpoint.

Defined in 7.1.6 of RFC 6455.

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.