trio_websocket
In addition to the convenience functions documented in websocket-clients and websocket-servers, the API has several important classes described on this page.
A request object presents the client's handshake to a server handler. The server can inspect handshake properties like HTTP headers, subprotocols, etc. The server can also set some handshake properties like subprotocol. The server should call accept to complete the handshake and obtain a connection object.
headers
proposed_subprotocols
local
remote
accept
reject
A connection object has functionality for sending and receiving messages, pinging the remote endpoint, and closing the WebSocket.
Note
The preferred way to obtain a connection is to use one of the convenience functions described in websocket-clients or websocket-servers. Instantiating a connection instance directly is tricky and is not recommended.
This object has properties that expose connection metadata.
closed
is_client
is_server
local
remote
This object exposes the following properties related to the WebSocket handshake.
path
subprotocol
handshake_headers
A connection object has a pair of methods for sending and receiving WebSocket messages. Messages can be str or bytes objects.
send_message
get_message
A connection object also has methods for sending pings and pongs. Each ping is sent with a unique payload, and the function blocks until a corresponding pong is received from the remote endpoint. This feature can be used to implement a bidirectional heartbeat.
A pong, on the other hand, sends an unsolicited pong to the remote endpoint and does not expect or wait for a response. This feature can be used to implement a unidirectional heartbeat.
ping
pong
Finally, the socket offers a method to close the connection. The connection context managers in websocket-clients and websocket-servers will automatically close the connection for you, but you may want to close the connection explicity if you are not using a context manager or if you want to customize the close reason.
aclose
CloseReason
ConnectionClosed
HandshakeError
ConnectionRejected
ConnectionTimeout
DisconnectionTimeout
These are classes that you do not need to instantiate yourself, but you may get access to instances of these classes through other APIs.
trio_websocket.Endpoint