Utilities

Data structures

websockets.datastructures defines a class for manipulating HTTP headers.

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.

clear()

Remove all headers.

Return type:

None

get_all(key)

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

Parameters:

key (str) – header name

Return type:

List[str]

raw_items()

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

Return type:

Iterator[Tuple[str, str]]

exception websockets.datastructures.MultipleValuesError

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

Exceptions

websockets.exceptions defines the following exception hierarchy:

• WebSocketException

  • ConnectionClosed

    • ConnectionClosedError

    • ConnectionClosedOK

  • InvalidHandshake

    • SecurityError

    • InvalidMessage

    • InvalidHeader

      • InvalidHeaderFormat

      • InvalidHeaderValue

      • InvalidOrigin

      • InvalidUpgrade

    • InvalidStatusCode

    • NegotiationError

      • DuplicateParameter

      • InvalidParameterName

      • InvalidParameterValue

    • AbortHandshake

    • RedirectHandshake

  • InvalidState

  • InvalidURI

  • PayloadTooBig

  • ProtocolError

exception websockets.exceptions.AbortHandshake(status, headers, body=b'')

Raised to abort the handshake on purpose and return a HTTP response.

This exception is an implementation detail.

The public API is process_request().

exception websockets.exceptions.ConnectionClosed(code, reason)

Raised when trying to interact with a closed connection.

Provides the connection close code and reason in its code and reason attributes respectively.

exception websockets.exceptions.ConnectionClosedError(code, reason)

Like ConnectionClosed, when the connection terminated with an error.

This means the close code is different from 1000 (OK) and 1001 (going away).

exception websockets.exceptions.ConnectionClosedOK(code, reason)

Like ConnectionClosed, when the connection terminated properly.

This means the close code is 1000 (OK) or 1001 (going away).

exception websockets.exceptions.DuplicateParameter(name)

Raised when a parameter name is repeated in an extension header.

exception websockets.exceptions.InvalidHandshake

Raised during the handshake when the WebSocket connection fails.

exception websockets.exceptions.InvalidHeader(name, value=None)

Raised when a HTTP header doesn’t have a valid format or value.

exception websockets.exceptions.InvalidHeaderFormat(name, error, header, pos)

Raised when a HTTP header cannot be parsed.

The format of the header doesn’t match the grammar for that header.

exception websockets.exceptions.InvalidHeaderValue(name, value=None)

Raised when a HTTP header has a wrong value.

The format of the header is correct but a value isn’t acceptable.

exception websockets.exceptions.InvalidMessage

Raised when a handshake request or response is malformed.

exception websockets.exceptions.InvalidOrigin(origin)

Raised when the Origin header in a request isn’t allowed.

exception websockets.exceptions.InvalidParameterName(name)

Raised when a parameter name in an extension header is invalid.

exception websockets.exceptions.InvalidParameterValue(name, value)

Raised when a parameter value in an extension header is invalid.

exception websockets.exceptions.InvalidState

Raised when an operation is forbidden in the current state.

This exception is an implementation detail.

It should never be raised in normal circumstances.

exception websockets.exceptions.InvalidStatusCode(status_code)

Raised when a handshake response status code is invalid.

The integer status code is available in the status_code attribute.

exception websockets.exceptions.InvalidURI(uri)

Raised when connecting to an URI that isn’t a valid WebSocket URI.

exception websockets.exceptions.InvalidUpgrade(name, value=None)

Raised when the Upgrade or Connection header isn’t correct.

exception websockets.exceptions.NegotiationError

Raised when negotiating an extension fails.

exception websockets.exceptions.PayloadTooBig

Raised when receiving a frame with a payload exceeding the maximum size.

exception websockets.exceptions.ProtocolError

Raised when a frame breaks the protocol.

exception websockets.exceptions.RedirectHandshake(uri)

Raised when a handshake gets redirected.

This exception is an implementation detail.

exception websockets.exceptions.SecurityError

Raised when a handshake request or response breaks a security rule.

Security limits are hard coded.

exception websockets.exceptions.WebSocketException

Base class for all exceptions defined by websockets.

websockets.exceptions.WebSocketProtocolError

alias of ProtocolError

Types

websockets.typing.Origin(x)

Value of a Origin header

websockets.typing.Subprotocol(x)

Subprotocol value in a Sec-WebSocket-Protocol header