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

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)

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()

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

Returns:generator of Event subclasses

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

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

Base class for wsproto events.

class wsproto.events.ConnectionRequested(proposed_subprotocols, h11request)

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

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

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)

class wsproto.events.DataReceived(data, frame_finished, message_finished)

class wsproto.events.TextReceived(data, frame_finished, message_finished)

class wsproto.events.BytesReceived(data, frame_finished, message_finished)

class wsproto.events.PingReceived(payload)

class wsproto.events.PongReceived(payload)

Frame Protocol

class wsproto.frame_protocol.Opcode

RFC 6455, Section 5.2 - Base Framing Protocol

class wsproto.frame_protocol.CloseReason

RFC 6455, Section 7.4.1 - Defined Status Codes

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.