Client (Sans-I/O)

class websockets.client.ClientProtocol(uri, *, origin=None, extensions=None, subprotocols=None, state=State.CONNECTING, max_size=1048576, logger=None)

Sans-I/O implementation of a WebSocket client connection.

Parameters:

• uri (WebSocketURI) – URI of the WebSocket server, parsed with parse_uri().

• origin (Origin | None) – Value of the Origin header. This is useful when connecting to a server that validates the Origin header to defend against Cross-Site WebSocket Hijacking attacks.

• extensions (Sequence[ClientExtensionFactory] | None) – List of supported extensions, in order in which they should be tried.

• subprotocols (Sequence[Subprotocol] | None) – List of supported subprotocols, in order of decreasing preference.

• 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; defaults to logging.getLogger("websockets.client"); see the logging guide for details.

receive_data(data)

Receive data from the network.

After calling this method:

• You must call data_to_send() and send this data to the network.

• You should call events_received() and process resulting events.

Raises:

EOFError – If receive_eof() was called earlier.

receive_eof()

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.

connect()

Create a handshake request to open a connection.

You must send the handshake request with send_request().

You can modify it before sending it, for example to add HTTP headers.

Returns:

WebSocket handshake request event to send to the server.

Return type:

Request

send_request(request)

Send a handshake request to the server.

Parameters:

request (Request) – WebSocket handshake request event.

send_continuation(data, fin)

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)

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)

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='')

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)

Send a Ping frame.

Parameters:

data (bytes) – payload containing arbitrary binary data.

send_pong(data)

Send a Pong frame.

Parameters:

data (bytes) – payload containing arbitrary binary data.

fail(code, reason='')

Fail the WebSocket connection.

Parameters:

• code (int) – close code

• reason (str) – close reason

Raises:

ProtocolError – If the code isn’t valid.

events_received()

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()

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()

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

WebSocket protocol objects also provide these attributes:

id: uuid.UUID

Unique identifier of the connection. Useful in logs.

logger: LoggerLike

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.

The following attributes are available after the opening handshake, once the WebSocket connection is open:

handshake_exc: Exception | None

Exception to raise if the opening handshake failed.

None if the opening handshake succeeded.

The following attributes are available after the closing handshake, once the WebSocket connection is closed:

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.