Client (Sans-I/O) - websockets 12.0 documentation

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Client (Sans-I/O)

class websockets.client.ClientProtocol(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` 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)

    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.

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