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 passCLIENT
otherwise passSERVER
. - 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)[source]¶ Return any data that is to be sent to the remote peer.
Parameters: amount ( int
) – (optional) The maximum number of bytes to be provided. IfNone
or not provided it will return all available bytes.
-
events
()[source]¶ Return a generator that provides any events that have been generated by protocol activity.
Returns: generator
-
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 bytes to the connection for processing.
Parameters: data ( bytes
) – The data received from the remote peer.
-
send_data
(payload, final=True)[source]¶ Send a message or part of a message to the remote peer.
If
final
isFalse
it indicates that this is part of a longer message. Iffinal
isTrue
it indicates that this is either a self-contained message or the last part of a longer message.If
payload
is of typebytes
then the message is flagged as being binary If it is of typestr
encoded as UTF-8 and sent as text.Parameters: - payload (
bytes
orstr
) – The message body to send. - final (
bool
) – Whether there are more parts to this message to be sent.
- payload (
- conn_type (
Extensions¶
-
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.