Client (Sans-I/O)#

class websockets.client.ClientProtocol(wsuri, origin=None, extensions=None, subprotocols=None, state=State.CONNECTING, max_size=2**20, logger=None)[source]#

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

Parameters:

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

  • origin (Optional[Origin]) – 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 (Optional[Sequence[ClientExtensionFactory]]) – list of supported extensions, in order in which they should be tried.

  • subprotocols (Optional[Sequence[Subprotocol]]) – list of supported subprotocols, in order of decreasing preference.

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

connect()[source]#

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)[source]#

Send a handshake request to the server.

Parameters:

request (Request) – WebSocket handshake request event.

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

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#

WebSocket connection state.

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.

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.