1API
2===
3
4Design
5------
6
7``websockets`` provides complete client and server implementations, as shown
8in the :doc:`getting started guide <intro>`. These functions are built on top
9of low-level APIs reflecting the two phases of the WebSocket protocol:
10
111. An opening handshake, in the form of an HTTP Upgrade request;
12
132. Data transfer, as framed messages, ending with a closing handshake.
14
15The first phase is designed to integrate with existing HTTP software.
16``websockets`` provides a minimal implementation to build, parse and validate
17HTTP requests and responses.
18
19The second phase is the core of the WebSocket protocol. ``websockets``
20provides a complete implementation on top of ``asyncio`` with a simple API.
21
22For convenience, public APIs can be imported directly from the
23:mod:`websockets` package, unless noted otherwise. Anything that isn't listed
24in this document is a private API.
25
26High-level
27----------
28
29Server
30......
31
32.. automodule:: websockets.server
33
34    .. autofunction:: serve(ws_handler, host=None, port=None, *, create_protocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, **kwds)
35        :async:
36
37    .. autofunction:: unix_serve(ws_handler, path, *, create_protocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, compression='deflate', origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, **kwds)
38        :async:
39
40
41    .. autoclass:: WebSocketServer
42
43        .. automethod:: close
44        .. automethod:: wait_closed
45        .. autoattribute:: sockets
46
47    .. autoclass:: WebSocketServerProtocol(ws_handler, ws_server, *, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None)
48
49        .. automethod:: handshake
50        .. automethod:: process_request
51        .. automethod:: select_subprotocol
52
53Client
54......
55
56.. automodule:: websockets.client
57
58    .. autofunction:: connect(uri, *, create_protocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, **kwds)
59        :async:
60
61    .. autofunction:: unix_connect(path, uri="ws://localhost/", *, create_protocol=None, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, **kwds)
62        :async:
63
64    .. autoclass:: WebSocketClientProtocol(*, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None, origin=None, extensions=None, subprotocols=None, extra_headers=None)
65
66        .. automethod:: handshake
67
68Shared
69......
70
71.. automodule:: websockets.protocol
72
73    .. autoclass:: WebSocketCommonProtocol(*, ping_interval=20, ping_timeout=20, close_timeout=10, max_size=2 ** 20, max_queue=2 ** 5, read_limit=2 ** 16, write_limit=2 ** 16, loop=None)
74
75        .. automethod:: close
76        .. automethod:: wait_closed
77
78        .. automethod:: recv
79        .. automethod:: send
80
81        .. automethod:: ping
82        .. automethod:: pong
83
84        .. autoattribute:: local_address
85        .. autoattribute:: remote_address
86
87        .. autoattribute:: open
88        .. autoattribute:: closed
89
90Types
91.....
92
93.. automodule:: websockets.typing
94
95    .. autodata:: Data
96
97
98Per-Message Deflate Extension
99.............................
100
101.. automodule:: websockets.extensions.permessage_deflate
102
103    .. autoclass:: ServerPerMessageDeflateFactory
104
105    .. autoclass:: ClientPerMessageDeflateFactory
106
107HTTP Basic Auth
108...............
109
110.. automodule:: websockets.auth
111
112    .. autofunction:: basic_auth_protocol_factory
113
114    .. autoclass:: BasicAuthWebSocketServerProtocol
115
116        .. automethod:: process_request
117
118Exceptions
119..........
120
121.. automodule:: websockets.exceptions
122    :members:
123
124Low-level
125---------
126
127Opening handshake
128.................
129
130.. automodule:: websockets.handshake
131    :members:
132
133Data transfer
134.............
135
136.. automodule:: websockets.framing
137    :members:
138
139URI parser
140..........
141
142.. automodule:: websockets.uri
143    :members:
144
145Utilities
146.........
147
148.. automodule:: websockets.headers
149    :members:
150
151.. automodule:: websockets.http
152    :members:
153