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

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

# Server (Sans-I/O)

class websockets.server.ServerProtocol(origins=None, extensions=None, subprotocols=None, state=State.CONNECTING, max_size=2**20, logger=None)

  Sans-I/O implementation of a WebSocket server connection.

  Parameters:

    - origins (Optional[Sequence[Optional[Origin]]]) – acceptable values of the `Origin` header; include `None` in the list if the lack of an origin is acceptable. This is useful for defending against Cross-Site WebSocket Hijacking attacks.

    - extensions (List[Extension]) – 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.

    - select_subprotocol (Optional[Callable[[ServerProtocol, Sequence[Subprotocol]], Optional[Subprotocol]]]) – Callback for selecting a subprotocol among those supported by the client and the server. It has the same signature as the `select_subprotocol()` method, including a `ServerProtocol` instance as first argument.

    - state (State) – initial state of the WebSocket connection.

    - max_size (Optional[int]) – maximum size of incoming messages in bytes; `None` disables the limit.

    - logger (Logger | LoggerAdapter) – 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.

  accept(request)

    Create a handshake response to accept the connection.

    If the connection cannot be established, the handshake response actually rejects the handshake.

    You must send the handshake response with `send_response()`.

    You may modify it before sending it, for example to add HTTP headers.

    Parameters:

      request (Request) – WebSocket handshake request event received from the client.

    Returns:

      WebSocket handshake response event to send to the client.

    Return type:

      Response

  select_subprotocol(subprotocols)

    Pick a subprotocol among those offered by the client.

    If several subprotocols are supported by both the client and the server, pick the first one in the list declared the server.

    If the server doesn’t support any subprotocols, continue without a subprotocol, regardless of what the client offers.

    If the server supports at least one subprotocol and the client doesn’t offer any, abort the handshake with an HTTP 400 error.

    You provide a `select_subprotocol` argument to `ServerProtocol` to override this logic. For example, you could accept the connection even if client doesn’t offer a subprotocol, rather than reject it.

    Here’s how to negotiate the `chat` subprotocol if the client supports it and continue without a subprotocol otherwise:

        def select_subprotocol(protocol, subprotocols):
            if "chat" in subprotocols:
                return "chat"

    Parameters:

      subprotocols (Sequence[Subprotocol]) – list of subprotocols offered by the client.

    Returns:

      Selected subprotocol, if a common subprotocol was found.

      `None` to continue without a subprotocol.

    Return type:

      Optional[Subprotocol]

    Raises:

      NegotiationError – custom implementations may raise this exception to abort the handshake with an HTTP 400 error.

  reject(status, text)

    Create a handshake response to reject the connection.

    A short plain text response is the best fallback when failing to establish a WebSocket connection.

    You must send the handshake response with `send_response()`.

    You can modify it before sending it, for example to alter HTTP headers.

    Parameters:

      - status (HTTPStatus | int) – HTTP status code.

      - text (str) – HTTP response body; will be encoded to UTF-8.

    Returns:

      WebSocket handshake response event to send to the client.

    Return type:

      Response

  send_response(response)

    Send a handshake response to the client.

    Parameters:

      response (Response) – WebSocket handshake response event to send.

  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.