Both sides#

asyncio#

class websockets.legacy.protocol.WebSocketCommonProtocol(*, logger=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2**20, max_queue=2**5, read_limit=2**16, write_limit=2**16)[source]#

WebSocket connection.

WebSocketCommonProtocol provides APIs shared between WebSocket servers and clients. You shouldn’t use it directly. Instead, use WebSocketClientProtocol or WebSocketServerProtocol.

This documentation focuses on low-level details that aren’t covered in the documentation of WebSocketClientProtocol and WebSocketServerProtocol for the sake of simplicity.

Once the connection is open, a Ping frame is sent every ping_interval seconds. This serves as a keepalive. It helps keeping the connection open, especially in the presence of proxies with short timeouts on inactive connections. Set ping_interval to None to disable this behavior.

If the corresponding Pong frame isn’t received within ping_timeout seconds, the connection is considered unusable and is closed with code 1011. This ensures that the remote endpoint remains responsive. Set ping_timeout to None to disable this behavior.

The close_timeout parameter defines a maximum wait time for completing the closing handshake and terminating the TCP connection. For legacy reasons, close() completes in at most 5 * close_timeout seconds for clients and 4 * close_timeout for servers.

See the discussion of timeouts for details.

close_timeout needs to be a parameter of the protocol because websockets usually calls close() implicitly upon exit:

  • on the client side, when connect() is used as a context manager;

  • on the server side, when the connection handler terminates;

To apply a timeout to any other API, wrap it in wait_for().

The max_size parameter enforces the maximum size for incoming messages in bytes. The default value is 1 MiB. If a larger message is received, recv() will raise ConnectionClosedError and the connection will be closed with code 1009.

The max_queue parameter sets the maximum length of the queue that holds incoming messages. The default value is 32. Messages are added to an in-memory queue when they’re received; then recv() pops from that queue. In order to prevent excessive memory consumption when messages are received faster than they can be processed, the queue must be bounded. If the queue fills up, the protocol stops processing incoming data until recv() is called. In this situation, various receive buffers (at least in asyncio and in the OS) will fill up, then the TCP receive window will shrink, slowing down transmission to avoid packet loss.

Since Python can use up to 4 bytes of memory to represent a single character, each connection may use up to 4 * max_size * max_queue bytes of memory to store incoming messages. By default, this is 128 MiB. You may want to lower the limits, depending on your application’s requirements.

The read_limit argument sets the high-water limit of the buffer for incoming bytes. The low-water limit is half the high-water limit. The default value is 64 KiB, half of asyncio’s default (based on the current implementation of StreamReader).

The write_limit argument sets the high-water limit of the buffer for outgoing bytes. The low-water limit is a quarter of the high-water limit. The default value is 64 KiB, equal to asyncio’s default (based on the current implementation of FlowControlMixin).

See the discussion of memory usage for details.

Parameters
  • logger (Optional[LoggerLike]) – logger for this connection; defaults to logging.getLogger("websockets.protocol"); see the logging guide for details.

  • ping_interval (Optional[float]) – delay between keepalive pings in seconds; None to disable keepalive pings.

  • ping_timeout (Optional[float]) – timeout for keepalive pings in seconds; None to disable timeouts.

  • close_timeout (Optional[float]) – timeout for closing the connection in seconds; for legacy reasons, the actual timeout is 4 or 5 times larger.

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

  • max_queue (Optional[int]) – maximum number of incoming messages in receive buffer; None to disable the limit.

  • read_limit (int) – high-water mark of read buffer in bytes.

  • write_limit (int) – high-water mark of write buffer in bytes.

await recv()[source]#

Receive the next message.

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

Canceling recv() is safe. There’s no risk of losing the next message. The next invocation of recv() will return it.

This makes it possible to enforce a timeout by wrapping recv() in wait_for().

Returns

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

Return type

Data

Raises
await send(message)[source]#

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.

send() also accepts an iterable or an asynchronous 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 want to send the keys of a dict-like object as fragments, call its keys() method and pass the result to send().)

Canceling send() is discouraged. Instead, you should close the connection with close(). Indeed, there are only two situations where send() may yield control to the event loop and then get canceled; in both cases, close() has the same effect and is more clear:

  1. The write buffer is full. If you don’t want to wait until enough data is sent, your only alternative is to close the connection. close() will likely time out then abort the TCP connection.

  2. message is an asynchronous iterator that yields control. Stopping in the middle of a fragmented message will cause a protocol error and the connection will be closed.

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 (Union[Data, Iterable[Data], AsyncIterable[Data]) – message to send.

Raises
await close(code=1000, reason='')[source]#

Perform the closing handshake.

close() waits for the other end to complete the handshake and for the TCP connection to terminate. As a consequence, there’s no need to await wait_closed() after close().

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

Wrapping close() in create_task() is safe, given that errors during connection termination aren’t particularly useful.

Canceling close() is discouraged. If it takes too long, you can set a shorter close_timeout. If you don’t want to wait, let the Python process exit, then the OS will take care of closing the TCP connection.

Parameters
  • code (int) – WebSocket close code.

  • reason (str) – WebSocket close reason.

await wait_closed()[source]#

Wait until the connection is closed.

This coroutine is identical to the closed attribute, except it can be awaited.

This can make it easier to detect connection termination, regardless of its cause, in tasks that interact with the WebSocket connection.

await ping(data=None)[source]#

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

Canceling ping() is discouraged. If ping() doesn’t return immediately, it means the write buffer is full. If you don’t want to wait, you should close the connection.

Canceling the Future returned by ping() has no effect.

Parameters

data (Optional[Data]) – payload of the ping; a string will be encoded to UTF-8; or None to generate a payload containing four random bytes.

Returns

A future that will be completed when the corresponding pong is received. You can ignore it if you don’t intend to wait.

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

Return type

Future

Raises
  • ConnectionClosed – when the connection is closed.

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

await pong(data=b'')[source]#

Send a Pong.

An unsolicited pong may serve as a unidirectional heartbeat.

Canceling pong() is discouraged. If pong() doesn’t return immediately, it means the write buffer is full. If you don’t want to wait, you should close the connection.

Parameters

data (Data) – payload of the pong; a string 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: Union[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().

None if the TCP connection isn’t established yet.

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

None if the TCP connection isn’t established yet.

property open: bool#

True when the connection is open; False otherwise.

This attribute may be used to detect disconnections. However, this approach is discouraged per the EAFP principle. Instead, you should handle ConnectionClosed exceptions.

property closed: bool#

True when the connection is closed; False otherwise.

Be aware that both open and closed are False during the opening and closing sequences.

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

path: str#

Path of the opening handshake request.

request_headers: Headers#

Opening handshake request headers.

response_headers: Headers#

Opening handshake response headers.

subprotocol: Optional[Subprotocol]#

Subprotocol, if one was negotiated.

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

property close_code: Optional[int]#

WebSocket close code, defined in section 7.1.5 of RFC 6455.

None if the connection isn’t closed yet.

property close_reason: Optional[str]#

WebSocket close reason, defined in section 7.1.6 of RFC 6455.

None if the connection isn’t closed yet.

Sans-I/O#

class websockets.connection.Connection(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 to disable 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:

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
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_*() 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: Union[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: Optional[int]#

WebSocket close code.

None if the connection isn’t closed yet.

property close_reason: Optional[str]#

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.connection.Side(value)[source]#

A WebSocket connection is either a server or a client.

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

A WebSocket connection is in one of these four states.

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

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