1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
API
===
.. currentmodule:: trio_websocket
In addition to the convenience functions documented in :ref:`websocket-clients`
and :ref:`websocket-servers`, the API has several important classes described
on this page.
Requests
--------
.. class:: WebSocketRequest
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 :meth:`accept` to complete the handshake and obtain a
connection object.
.. autoattribute:: headers
.. autoattribute:: proposed_subprotocols
.. autoattribute:: local
.. autoattribute:: remote
.. automethod:: accept
.. automethod:: reject
Connections
-----------
.. class:: WebSocketConnection
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 :ref:`websocket-clients` or
:ref:`websocket-servers`. Instantiating a connection instance directly is
tricky and is not recommended.
This object has properties that expose connection metadata.
.. autoattribute:: closed
.. autoattribute:: is_client
.. autoattribute:: is_server
.. autoattribute:: local
.. autoattribute:: remote
This object exposes the following properties related to the WebSocket
handshake.
.. autoattribute:: path
.. autoattribute:: subprotocol
.. autoattribute:: handshake_headers
A connection object has a pair of methods for sending and receiving
WebSocket messages. Messages can be ``str`` or ``bytes`` objects.
.. automethod:: send_message
.. automethod:: 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.
.. automethod:: ping
.. automethod:: pong
Finally, the socket offers a method to close the connection. The connection
context managers in :ref:`websocket-clients` and :ref:`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.
.. automethod:: aclose
.. autoclass:: CloseReason
:members:
.. autoexception:: ConnectionClosed
.. autoexception:: HandshakeError
.. autoexception:: ConnectionRejected
:show-inheritance:
.. autoexception:: ConnectionTimeout
:show-inheritance:
.. autoexception:: DisconnectionTimeout
:show-inheritance:
Utilities
---------
These are classes that you do not need to instantiate yourself, but you may
get access to instances of these classes through other APIs.
.. autoclass:: trio_websocket.Endpoint
:members:
|
