wsproto API

This document details the API of wsproto.

Semantic Versioning

wsproto follows semantic versioning for its public API. Please note that the guarantees of semantic versioning apply only to the API that is documented here. Simply because a method or data field is not prefaced by an underscore does not make it part of wsproto’s public API. Anything not documented here is subject to change at any time.

Connection

class wsproto.connection.WSConnection(conn_type, host=None, resource=None, extensions=None, subprotocols=None)[source]

A low-level WebSocket connection object.

This wraps two other protocol objects, an HTTP/1.1 protocol object used to do the initial HTTP upgrade handshake and a WebSocket frame protocol object used to exchange messages and other control frames.

Parameters:
  • conn_type (ConnectionType) – Whether this object is on the client- or server-side of a connection. To initialise as a client pass CLIENT otherwise pass SERVER.
  • host (str) – The hostname to pass to the server when acting as a client.
  • resource (str) – The resource (aka path) to pass to the server when acting as a client.
  • extensions – A list of extensions to use on this connection. Defaults to to an empty list. Extensions should be instances of a subclass of Extension.
  • subprotocols – A list of subprotocols to request when acting as a client, ordered by preference. This has no impact on the connection itself. Defaults to an empty list.
bytes_to_send(amount=None)[source]

Returns some data for sending out of the internal data buffer.

This method is analogous to read on a file-like object, but it doesn’t block. Instead, it returns as much data as the user asks for, or less if that much data is not available. It does not perform any I/O, and so uses a different name.

Parameters:amount (int) – (optional) The maximum amount of data to return. If not set, or set to None, will return as much data as possible.
Returns:A bytestring containing the data to send on the wire.
Return type:bytes
close(code=<CloseReason.NORMAL_CLOSURE: 1000>, reason=None)[source]

Initiate the close handshake by sending a CLOSE control message.

A clean teardown requires a CLOSE control messages from the other endpoint before the underlying TCP connection can be closed, see ConnectionClosed.

events()[source]

Return a generator that provides any events that have been generated by protocol activity.

Returns:generator of Event subclasses
ping(payload=None)[source]

Send a PING message to the peer.

Parameters:payload – an optional payload to send with the message
pong(payload=None)[source]

Send a PONG message to the peer.

This method can be used to send an unsolicted PONG to the peer. It is not needed otherwise since every received PING causes a corresponding PONG to be sent automatically.

Parameters:payload – an optional payload to send with the message
receive_bytes(data)[source]

Pass some received data to the connection for handling.

A list of events that the remote peer triggered by sending this data can be retrieved with events().

Parameters:data (bytes) – The data received from the remote peer on the network.
send_data(payload, final=True)[source]

Send a message or part of a message to the remote peer.

If final is False it indicates that this is part of a longer message. If final is True it indicates that this is either a self-contained message or the last part of a longer message.

If payload is of type bytes then the message is flagged as being binary. If it is of type str the message is encoded as UTF-8 and sent as text.

Parameters:
  • payload (bytes or str) – The message body to send.
  • final (bool) – Whether there are more parts to this message to be sent.

Events

class wsproto.events.Event[source]

Base class for wsproto events.

class wsproto.events.ConnectionRequested(proposed_subprotocols, h11request)[source]

The ConnectionRequested event is fired when a SERVER connection receives a WebSocket handshake request (HTTP with upgrade header).

class wsproto.events.ConnectionEstablished(subprotocol=None, extensions=None)[source]

The ConnectionEstablished event is fired when a CLIENT connection completes the WebSocket handshake and is ready to send & receive messages.

class wsproto.events.ConnectionClosed(code, reason=None)[source]

The ConnectionClosed event is fired after the connection is considered closed.

wsproto automatically emits a CLOSE frame when it receives one, to complete the close-handshake.

code = None

The close status code, see CloseReason.

class wsproto.events.ConnectionFailed(code, reason=None)[source]
class wsproto.events.DataReceived(data, frame_finished, message_finished)[source]
data = None

The message data as byte string, can be decoded as UTF-8 for TEXT messages. This only represents a single chunk of data and not a full WebSocket message. You need to buffer and reassemble these chunks to get the full message.

frame_finished = None

This has no semantic content, but is provided just in case some weird edge case user wants to be able to reconstruct the fragmentation pattern of the original stream. You don’t want it:

message_finished = None

True if this frame is the last one of this message, False if more frames are expected.

class wsproto.events.TextReceived(data, frame_finished, message_finished)[source]

The TextReceived event is fired when a data frame with TEXT payload is received.

class wsproto.events.BytesReceived(data, frame_finished, message_finished)[source]

The BytesReceived event is fired when a data frame with BINARY payload is received.

class wsproto.events.PingReceived(payload)[source]

The PingReceived event is fired when a Ping is received.

wsproto automatically emits a PONG frame with the same payload.

payload = None

Optional “Application data”, i.e., binary payload.

class wsproto.events.PongReceived(payload)[source]

The PongReceived event is fired when a Pong is received.

payload = None

Optional “Application data”, i.e., binary payload. Make sure to verify against the orignal PING payload.

Frame Protocol

class wsproto.frame_protocol.Opcode[source]

RFC 6455, Section 5.2 - Base Framing Protocol

BINARY = 2

Binary message

CLOSE = 8

Close frame

CONTINUATION = 0

Contiuation frame

PING = 9

Ping frame

PONG = 10

Pong frame

TEXT = 1

Text message

class wsproto.frame_protocol.CloseReason[source]

RFC 6455, Section 7.4.1 - Defined Status Codes

ABNORMAL_CLOSURE = 1006

is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed abnormally, e.g., without sending or receiving a Close control frame.

GOING_AWAY = 1001

indicates that an endpoint is “going away”, such as a server going down or a browser having navigated away from a page.

INTERNAL_ERROR = 1011

indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request.

INVALID_FRAME_PAYLOAD_DATA = 1007

indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 [RFC3629] data within a text message).

MANDATORY_EXT = 1010

indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn’t return them in the response message of the WebSocket handshake. The list of extensions that are needed SHOULD appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead.

MESSAGE_TOO_BIG = 1009

indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process.

NORMAL_CLOSURE = 1000

indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled.

NO_STATUS_RCVD = 1005

is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that no status code was actually present.

POLICY_VIOLATION = 1008

indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the policy.

PROTOCOL_ERROR = 1002

indicates that an endpoint is terminating the connection due to a protocol error.

SERVICE_RESTART = 1012

Server/service is restarting (not part of RFC6455)

TLS_HANDSHAKE_FAILED = 1015

is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can’t be verified).

TRY_AGAIN_LATER = 1013

Temporary server condition forced blocking client’s request (not part of RFC6455)

UNSUPPORTED_DATA = 1003

indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message).

Extensions

class wsproto.extensions.Extension[source]
wsproto.extensions.SUPPORTED_EXTENSIONS = {'permessage-deflate': <class 'wsproto.extensions.PerMessageDeflate'>}

SUPPORTED_EXTENSIONS maps all supported extension names to their class. This can be used to iterate all supported extensions of wsproto, instantiate new extensions based on their name, or check if a given extension is supported or not.