Both sides (threading)

class websockets.sync.connection.Connection(socket, protocol, *, close_timeout=10, max_queue=16)

threading implementation of a WebSocket connection.

Connection provides APIs shared between WebSocket servers and clients.

You shouldn’t use it directly. Instead, use ClientConnection or ServerConnection.

for ... in __iter__()

Iterate on incoming messages.

The iterator calls recv() and yields messages in an infinite loop.

It exits when the connection is closed normally. It raises a ConnectionClosedError exception after a protocol error or a network failure.

recv(timeout=None, decode=None)

Receive the next message.

When the connection is closed, recv() raises ConnectionClosed. Specifically, it raises ConnectionClosedOK after a normal closure and ConnectionClosedError after a protocol error or a network failure. This is how you detect the end of the message stream.

If timeout is None, block until a message is received. If timeout is set and no message is received within timeout seconds, raise TimeoutError. Set timeout to 0 to check if a message was already received.

If the message is fragmented, wait until all fragments are received, reassemble them, and return the whole message.

Parameters:

• timeout (float | None) – Timeout for receiving a message in seconds.

• decode (bool | None) – Set this flag to override the default behavior of returning str or bytes. See below for details.

Returns:

A string (str) for a Text frame or a bytestring (bytes) for a Binary frame.

You may override this behavior with the decode argument:

• Set decode=False to disable UTF-8 decoding of Text frames and return a bytestring (bytes). This improves performance when decoding isn’t needed, for example if the message contains JSON and you’re using a JSON library that expects a bytestring.

• Set decode=True to force UTF-8 decoding of Binary frames and return a string (str). This may be useful for servers that send binary frames instead of text frames.

Raises:

• ConnectionClosed – When the connection is closed.

• ConcurrencyError – If two threads call recv() or recv_streaming() concurrently.

Return type:

str | bytes

for ... in recv_streaming(decode=None)

Receive the next message frame by frame.

This method is designed for receiving fragmented messages. It returns an iterator that yields each fragment as it is received. This iterator must be fully consumed. Else, future calls to recv() or recv_streaming() will raise ConcurrencyError, making the connection unusable.

recv_streaming() raises the same exceptions as recv().

Parameters:

decode (bool | None) – Set this flag to override the default behavior of returning str or bytes. See below for details.

Returns:

An iterator of strings (str) for a Text frame or bytestrings (bytes) for a Binary frame.

You may override this behavior with the decode argument:

• Set decode=False to disable UTF-8 decoding of Text frames and return bytestrings (bytes). This may be useful to optimize performance when decoding isn’t needed.

• Set decode=True to force UTF-8 decoding of Binary frames and return strings (str). This is useful for servers that send binary frames instead of text frames.

Raises:

• ConnectionClosed – When the connection is closed.

• ConcurrencyError – If two threads call recv() or recv_streaming() concurrently.

Return type:

Iterator[str | bytes]

send(message, text=None)

Send a message.

A string (str) is sent as a Text frame. A bytestring or bytes-like object (bytes, bytearray, or memoryview) is sent as a Binary frame.

You may override this behavior with the text argument:

• Set text=True to send a bytestring or bytes-like object (bytes, bytearray, or memoryview) as a Text frame. This improves performance when the message is already UTF-8 encoded, for example if the message contains JSON and you’re using a JSON library that produces a bytestring.

• Set text=False to send a string (str) in a Binary frame. This may be useful for servers that expect binary frames instead of text frames.

send() also accepts an iterable of strings, bytestrings, or bytes-like objects to enable fragmentation. Each item is treated as a message fragment and sent in its own frame. All items must be of the same type, or else send() will raise a TypeError and the connection will be closed.

send() rejects dict-like objects because this is often an error. (If you really want to send the keys of a dict-like object as fragments, call its keys() method and pass the result to send().)

When the connection is closed, send() raises ConnectionClosed. Specifically, it raises ConnectionClosedOK after a normal connection closure and ConnectionClosedError after a protocol error or a network failure.

Parameters:

message (str | bytes | Iterable[str | bytes]) – Message to send.

Raises:

• ConnectionClosed – When the connection is closed.

• ConcurrencyError – If the connection is sending a fragmented message.

• TypeError – If message doesn’t have a supported type.

close(code=CloseCode.NORMAL_CLOSURE, reason='')

Perform the closing handshake.

close() waits for the other end to complete the handshake, for the TCP connection to terminate, and for all incoming messages to be read with recv().

close() is idempotent: it doesn’t do anything once the connection is closed.

Parameters:

• code (int) – WebSocket close code.

• reason (str) – WebSocket close reason.

ping(data=None)

Send a Ping.

A ping may serve as a keepalive or as a check that the remote endpoint received all messages up to this point

Parameters:

data (str | bytes | None) – Payload of the ping. A str will be encoded to UTF-8. If data is None, the payload is four random bytes.

Returns:

An event that will be set when the corresponding pong is received. You can ignore it if you don’t intend to wait.

pong_event = ws.ping()
pong_event.wait()  # only if you want to wait for the pong

Raises:

• ConnectionClosed – When the connection is closed.

• ConcurrencyError – If another ping was sent with the same data and the corresponding pong wasn’t received yet.

Return type:

Event

pong(data=b'')

Send a Pong.

An unsolicited pong may serve as a unidirectional heartbeat.

Parameters:

data (str | bytes) – Payload of the pong. A str will be encoded to UTF-8.

Raises:

ConnectionClosed – When the connection is closed.

WebSocket connection objects also provide these attributes:

id: UUID

Unique identifier of the connection. Useful in logs.

logger: Logger | LoggerAdapter

Logger for this connection.

property local_address: Any

Local address of the connection.

For IPv4 connections, this is a (host, port) tuple.

The format of the address depends on the address family. See getsockname().

property remote_address: Any

Remote address of the connection.

For IPv4 connections, this is a (host, port) tuple.

The format of the address depends on the address family. See getpeername().

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

request: Request | None

Opening handshake request.

response: Response | None

Opening handshake response.

property subprotocol: Subprotocol | None

Subprotocol negotiated during the opening handshake.

None if no subprotocol was negotiated.