Data structures - websockets 12.0 documentation
Description: WebSocket events: HTTP events: URIs:

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

# Data structures

## WebSocket events

class websockets.frames.Frame(opcode, data, fin=True, rsv1=False, rsv2=False, rsv3=False)

  WebSocket frame.

  opcode

    Opcode.

    Type:

      websockets.frames.Opcode

  data

    Payload data.

    Type:

      bytes

  fin

    FIN bit.

    Type:

      bool

  rsv1

    RSV1 bit.

    Type:

      bool

  rsv2

    RSV2 bit.

    Type:

      bool

  rsv3

    RSV3 bit.

    Type:

      bool

  Only these fields are needed. The MASK bit, payload length and masking-key are handled on the fly when parsing and serializing frames.

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

  Opcode values for WebSocket frames.

  CONT = 0
  TEXT = 1
  BINARY = 2
  CLOSE = 8
  PING = 9
  PONG = 10

class websockets.frames.Close(code, reason)

  Code and reason for WebSocket close frames.

  code

    Close code.

    Type:

      int

  reason

    Close reason.

    Type:

      str

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

  Close code values for WebSocket close frames.

  NORMAL_CLOSURE = 1000
  GOING_AWAY = 1001
  PROTOCOL_ERROR = 1002
  UNSUPPORTED_DATA = 1003
  NO_STATUS_RCVD = 1005
  ABNORMAL_CLOSURE = 1006
  INVALID_DATA = 1007
  POLICY_VIOLATION = 1008
  MESSAGE_TOO_BIG = 1009
  MANDATORY_EXTENSION = 1010
  INTERNAL_ERROR = 1011
  SERVICE_RESTART = 1012
  TRY_AGAIN_LATER = 1013
  BAD_GATEWAY = 1014
  TLS_HANDSHAKE = 1015

## HTTP events

class websockets.http11.Request(path, headers, _exception=None)

  WebSocket handshake request.

  path

    Request path, including optional query.

    Type:

      str

  headers

    Request headers.

    Type:

      websockets.datastructures.Headers

class websockets.http11.Response(status_code, reason_phrase, headers, body=None, _exception=None)

  WebSocket handshake response.

  status_code

    Response code.

    Type:

      int

  reason_phrase

    Response reason.

    Type:

      str

  headers

    Response headers.

    Type:

      websockets.datastructures.Headers

  body

    Response body, if any.

    Type:

      bytes | None

class websockets.datastructures.Headers(*args, **kwargs)

  Efficient data structure for manipulating HTTP headers.

  A `list` of `(name, values)` is inefficient for lookups.

  A `dict` doesn’t suffice because header names are case-insensitive and multiple occurrences of headers with the same name are possible.

  `Headers` stores HTTP headers in a hybrid data structure to provide efficient insertions and lookups while preserving the original data.

  In order to account for multiple values with minimal hassle, `Headers` follows this logic:

  - When getting a header with `headers[name]`:

      - if there’s no value, `KeyError` is raised;

      - if there’s exactly one value, it’s returned;

      - if there’s more than one value, `MultipleValuesError` is raised.

  - When setting a header with `headers[name] = value`, the value is appended to the list of values for that header.

  - When deleting a header with `del headers[name]`, all values for that header are removed (this is slow).

  Other methods for manipulating headers are consistent with this logic.

  As long as no header occurs multiple times, `Headers` behaves like `dict`, except keys are lower-cased to provide case-insensitivity.

  Two methods support manipulating multiple values explicitly:

  - `get_all()` returns a list of all values for a header;

  - `raw_items()` returns an iterator of `(name, values)` pairs.

  get_all(key)

    Return the (possibly empty) list of all values for a header.

    Parameters:

      key (str) – header name.

  raw_items()

    Return an iterator of all values as `(name, value)` pairs.

exception websockets.datastructures.MultipleValuesError

  Exception raised when `Headers` has more than one value for a key.

## URIs

websockets.uri.parse_uri(uri)

  Parse and validate a WebSocket URI.

  Parameters:

    uri (str) – WebSocket URI.

  Returns:

    Parsed WebSocket URI.

  Return type:

    WebSocketURI

  Raises:

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

class websockets.uri.WebSocketURI(secure, host, port, path, query, username=None, password=None)

  WebSocket URI.

  secure

    `True` for a `wss` URI, `False` for a `ws` URI.

    Type:

      bool

  host

    Normalized to lower case.

    Type:

      str

  port

    Always set even if it’s the default.

    Type:

      int

  path

    May be empty.

    Type:

      str

  query

    May be empty if the URI doesn’t include a query component.

    Type:

      str

  username

    Available when the URI contains User Information.

    Type:

      str | None

  password

    Available when the URI contains User Information.

    Type:

      str | None