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)

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

bytes_to_send(amount=None)

Return any data that is to be sent to the remote peer.

Parameters:amount (int) – (optional) The maximum number of bytes to be provided. If None or not provided it will return all available bytes.

events()

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

Returns:generator

ping(payload=None)

Send a PING message to the peer.

Parameters:payload – an optional payload to send with the message

pong(payload=None)

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)

Pass some received bytes to the connection for processing.

Parameters:data (bytes) – The data received from the remote peer.

send_data(payload, final=True)

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

Extensions

class wsproto.extensions.Extension

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.