Both sides (Sans-I/O) - websockets 11.0 documentation

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

# Both sides (Sans-I/O)

class websockets.protocol.Protocol(side, state=State.OPEN, max_size=2**20, logger=None)

  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` disables 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)

    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.

  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

  id: UUID

    Unique identifier of the connection. Useful in logs.

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

class websockets.protocol.Side(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  A WebSocket connection is either a server or a client.

  SERVER = 0
  CLIENT = 1

class websockets.protocol.State(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  A WebSocket connection is in one of these four states.

  CONNECTING = 0
  OPEN = 1
  CLOSING = 2
  CLOSED = 3

websockets.protocol.SEND_EOF = b''

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