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.
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 toNone
, 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
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
the message is 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 (
Events¶
-
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
.
-
Frame Protocol¶
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.