Client - websockets 10.1 documentation
Description: asyncio: Opening a connection: Using a connection: Sans-I/O:

Hide navigation sidebar
Hide table of contents sidebar
Toggle table of contents sidebar

# Client

## asyncio

### Opening a connection

await websockets.client.connect(uri, *, create_protocol=None, logger=None, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, open_timeout=10, 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, **kwds)

  Connect to the WebSocket server at `uri`.

  Awaiting `connect()` yields a `WebSocketClientProtocol` which can then be used to send and receive messages.

  `connect()` can be used as a asynchronous context manager:

      async with websockets.connect(...) as websocket:
          ...

  The connection is closed automatically when exiting the context.

  `connect()` can be used as an infinite asynchronous iterator to reconnect automatically on errors:

      async for websocket in websockets.connect(...):
          try:
              ...
          except websockets.ConnectionClosed:
              continue

  The connection is closed automatically after each iteration of the loop.

  If an error occurs while establishing the connection, `connect()` retries with exponential backoff. The backoff delay starts at three seconds and increases up to one minute.

  If an error occurs in the body of the loop, you can handle the exception and `connect()` will reconnect with the next iteration; or you can let the exception bubble up and break out of the loop. This lets you decide which errors trigger a reconnection and which errors are fatal.

  Parameters

    - uri (str) – URI of the WebSocket server.

    - create_protocol (Optional[Callable[[Any], WebSocketClientProtocol]]) – factory for the `asyncio.Protocol` managing the connection; defaults to `WebSocketClientProtocol`; may be set to a wrapper or a subclass to customize connection handling.

    - logger (Optional[LoggerLike]) – logger for this connection; defaults to `logging.getLogger("websockets.client")`; see the logging guide for details.

    - compression (Optional[str]) – shortcut that enables the “permessage-deflate” extension by default; may be set to `None` to disable compression; see the compression guide for details.

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

    - extra_headers (Optional[HeadersLike]) – arbitrary HTTP headers to add to the request.

    - open_timeout (Optional[float]) – timeout for opening the connection in seconds; `None` to disable the timeout

  See `WebSocketCommonProtocol` for the documentation of `ping_interval`, `ping_timeout`, `close_timeout`, `max_size`, `max_queue`, `read_limit`, and `write_limit`.

  Any other keyword arguments are passed the event loop’s `create_connection()` method.

  For example:

  - You can set `ssl` to a `SSLContext` to enforce TLS settings. When connecting to a `wss://` URI, if `ssl` isn’t provided, a TLS context is created with `create_default_context()`.

  - You can set `host` and `port` to connect to a different host and port from those found in `uri`. This only changes the destination of the TCP connection. The host name from `uri` is still used in the TLS handshake for secure connections and in the `Host` header.

  Returns

    WebSocket connection.

  Return type

    WebSocketClientProtocol

  Raises

    - InvalidURI – if `uri` isn’t a valid WebSocket URI.

    - InvalidHandshake – if the opening handshake fails.

    - TimeoutError – if the opening handshake times out.

await websockets.client.unix_connect(path, uri='ws://localhost/', *, create_protocol=None, logger=None, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, open_timeout=10, 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, **kwds)

  Similar to `connect()`, but for connecting to a Unix socket.

  This function builds upon the event loop’s `create_unix_connection()` method.

  It is only available on Unix.

  It’s mainly useful for debugging servers listening on Unix sockets.

  Parameters

    - path (Optional[str]) – file system path to the Unix socket.

    - uri (str) – URI of the WebSocket server; the host is used in the TLS handshake for secure connections and in the `Host` header.

### Using a connection

class websockets.client.WebSocketClientProtocol(*, logger=None, origin=None, extensions=None, subprotocols=None, extra_headers=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)

  WebSocket client connection.

  `WebSocketClientProtocol` provides `recv()` and `send()` coroutines for receiving and sending messages.

  It supports asynchronous iteration to receive incoming messages:

      async for message in websocket:
          await process(message)

  The iterator exits normally when the connection is closed with close code 1000 (OK) or 1001 (going away). It raises a `ConnectionClosedError` when the connection is closed with any other code.

  See `connect()` for the documentation of `logger`, `origin`, `extensions`, `subprotocols`, and `extra_headers`.

  See `WebSocketCommonProtocol` for the documentation of `ping_interval`, `ping_timeout`, `close_timeout`, `max_size`, `max_queue`, `read_limit`, and `write_limit`.

  await recv()

    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

      - ConnectionClosed – when the connection is closed.

      - RuntimeError – if two coroutines call `recv()` concurrently.

  await send(message)

    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

      - ConnectionClosed – when the connection is closed.

      - TypeError – if `message` doesn’t have a supported type.

  await close(code=1000, reason='')

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

    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)

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

    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.UUID

    Unique identifier of the connection. Useful in logs.

  logger: LoggerLike

    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.client.ClientConnection(wsuri, origin=None, extensions=None, subprotocols=None, state=State.CONNECTING, max_size=2 ** 20, logger=None)

  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` to disable the limit.

    - logger (Optional[LoggerLike]) – 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.

    - You aren’t expected to call `events_received()`; it won’t return any new events.

    Raises

      EOFError – if `receive_eof()` was called earlier.

  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 (websockets.http11.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 (Optional[int]) – 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)

    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[Event]

  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_*()` 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.UUID

    Unique identifier of the connection. Useful in logs.

  logger: LoggerLike

    Logger for this connection.

  property state: websockets.connection.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: websockets.exceptions.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.