Skip to content

Commit 626cd7f

Browse files
aaugustinaaugustin
committed
Review reference docs.
Remove sphinx-autodoc-typehints and use native autodoc features instead, mainly because I can't find a workaround for: https://github.com/agronholm/sphinx-autodoc-typehints/issues/132 Re-introduce the "common" docs, else linking to send() and recv() is a mess.
1 parent 9e75d1e commit 626cd7f

30 files changed

+649
-490
lines changed

‎docs/conf.py

+10-1
Original file line numberDiff line numberDiff line change
@@ -34,15 +34,24 @@
3434
extensions = [
3535
"sphinx.ext.autodoc",
3636
"sphinx.ext.intersphinx",
37+
"sphinx.ext.napoleon",
3738
"sphinx.ext.viewcode",
38-
"sphinx_autodoc_typehints",
3939
"sphinx_copybutton",
4040
"sphinx_inline_tabs",
4141
"sphinxcontrib.spelling",
4242
"sphinxcontrib_trio",
4343
"sphinxext.opengraph",
4444
]
4545

46+
autodoc_typehints = "description"
47+
48+
autodoc_typehints_description_target = "documented"
49+
50+
# Workaround for https://github.com/sphinx-doc/sphinx/issues/9560
51+
from sphinx.domains.python import PythonDomain
52+
assert PythonDomain.object_types['data'].roles == ('data', 'obj')
53+
PythonDomain.object_types['data'].roles = ('data', 'class', 'obj')
54+
4655
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
4756

4857
spelling_show_suggestions = True

‎docs/reference/client.rst

+3-57
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,18 @@
11
Client
22
======
3-
43
.. automodule:: websockets.client
54

65
Opening a connection
76
--------------------
87

9-
.. 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, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, logger=None, **kwds)
8+
.. autofunction:: connect(uri, *, create_protocol=None, logger=None, compression="deflate", origin=None, extensions=None, subprotocols=None, extra_headers=None, open_timeout=10, 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, **kwds)
109
:async:
1110

12-
.. 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, compression='deflate', origin=None, extensions=None, subprotocols=None, extra_headers=None, logger=None, **kwds)
11+
.. autofunction:: unix_connect(path, uri="ws://localhost/", *, create_protocol=None, logger=None, compression="deflate", origin=None, extensions=None, subprotocols=None, extra_headers=None, open_timeout=10, 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, **kwds)
1312
:async:
1413

1514
Using a connection
1615
------------------
1716

18-
.. 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, origin=None, extensions=None, subprotocols=None, extra_headers=None, logger=None)
19-
20-
.. attribute:: id
21-
22-
UUID for the connection.
23-
24-
Useful for identifying connections in logs.
25-
26-
.. autoattribute:: local_address
27-
28-
.. autoattribute:: remote_address
29-
30-
.. autoattribute:: open
31-
32-
.. autoattribute:: closed
33-
34-
.. attribute:: path
35-
36-
Path of the HTTP request.
37-
38-
Available once the connection is open.
39-
40-
.. attribute:: request_headers
41-
42-
HTTP request headers as a :class:`~websockets.http.Headers` instance.
43-
44-
Available once the connection is open.
45-
46-
.. attribute:: response_headers
47-
48-
HTTP response headers as a :class:`~websockets.http.Headers` instance.
49-
50-
Available once the connection is open.
51-
52-
.. attribute:: subprotocol
53-
54-
Subprotocol, if one was negotiated.
55-
56-
Available once the connection is open.
57-
58-
.. autoattribute:: close_code
59-
60-
.. autoattribute:: close_reason
61-
62-
.. automethod:: recv
63-
64-
.. automethod:: send
65-
66-
.. automethod:: ping
67-
68-
.. automethod:: pong
69-
70-
.. automethod:: close
17+
.. autoclass:: WebSocketClientProtocol(*, logger=None, origin=None, extensions=None, subprotocols=None, extra_headers=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)
7118

72-
.. automethod:: wait_closed

‎docs/reference/common.rst

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
Both sides
2+
==========
3+
4+
.. automodule:: websockets.legacy.protocol
5+
6+
.. 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, logger=None)
7+
8+
.. automethod:: recv
9+
10+
.. automethod:: send
11+
12+
.. automethod:: ping
13+
14+
.. automethod:: pong
15+
16+
.. automethod:: close
17+
18+
.. automethod:: wait_closed
19+
20+
WebSocket connection objects also provide these attributes:
21+
22+
.. attribute:: id
23+
24+
UUID for the connection.
25+
26+
Useful for identifying connections in logs.
27+
28+
:type: :class:`~uuid.UUID`
29+
30+
.. autoattribute:: local_address
31+
32+
:type: :obj:`~typing.Any`
33+
34+
.. autoattribute:: remote_address
35+
36+
:type: :obj:`~typing.Any`
37+
38+
.. autoattribute:: open
39+
40+
.. autoattribute:: closed
41+
42+
The following attributes are available after the opening handshake,
43+
once the connection is open:
44+
45+
.. attribute:: path
46+
47+
Path of the opening handshake request.
48+
49+
:type: :class:`str`
50+
51+
.. attribute:: request_headers
52+
53+
Opening handshake request headers.
54+
55+
:type: :class:`~websockets.datastructures.Headers`
56+
57+
.. attribute:: response_headers
58+
59+
Opening handshake response headers.
60+
61+
:type: :class:`~websockets.datastructures.Headers`
62+
63+
.. attribute:: subprotocol
64+
65+
Subprotocol, if one was negotiated.
66+
67+
:type: :obj:`~typing.Optional`\[:data:`~websockets.typing.Subprotocol`]
68+
69+
The following attributes are available after the closing handshake,
70+
once the connection is closed:
71+
72+
.. autoattribute:: close_code
73+
74+
:type: :obj:`~typing.Optional`\[:class:`int`]
75+
76+
.. autoattribute:: close_reason
77+
78+
:type: :obj:`~typing.Optional`\[:class:`str`]

‎docs/reference/exceptions.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Exceptions
2+
==========
3+
4+
.. automodule:: websockets.exceptions
5+
:members:
6+

‎docs/reference/index.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,11 @@ both in the client API and server API.
4242

4343
client
4444
server
45-
extensions
45+
common
4646
utilities
47+
exceptions
48+
types
49+
extensions
4750
limitations
4851

4952
All public APIs can be imported from the :mod:`websockets` package, unless

‎docs/reference/limitations.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
Limitations
22
===========
33

4+
.. currentmodule:: websockets
5+
46
Client
57
------
68

79
The client doesn't attempt to guarantee that there is no more than one
810
connection to a given IP address in a CONNECTING state. This behavior is
9-
`mandated by RFC 6455`_. However, :func:`~websockets.connect()` isn't the
11+
`mandated by RFC 6455`_. However, :func:`~client.connect()` isn't the
1012
right layer for enforcing this constraint. It's the caller's responsibility.
1113

1214
.. _mandated by RFC 6455: https://www.rfc-editor.org/rfc/rfc6455.html#section-4.1

‎docs/reference/server.rst

-54
Original file line numberDiff line numberDiff line change
@@ -27,64 +27,10 @@ Server
2727

2828
.. 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, origins=None, extensions=None, subprotocols=None, extra_headers=None, process_request=None, select_subprotocol=None, logger=None)
2929

30-
.. attribute:: id
31-
32-
UUID for the connection.
33-
34-
Useful for identifying connections in logs.
35-
36-
.. autoattribute:: local_address
37-
38-
.. autoattribute:: remote_address
39-
40-
.. autoattribute:: open
41-
42-
.. autoattribute:: closed
43-
44-
.. attribute:: path
45-
46-
Path of the HTTP request.
47-
48-
Available once the connection is open.
49-
50-
.. attribute:: request_headers
51-
52-
HTTP request headers as a :class:`~websockets.http.Headers` instance.
53-
54-
Available once the connection is open.
55-
56-
.. attribute:: response_headers
57-
58-
HTTP response headers as a :class:`~websockets.http.Headers` instance.
59-
60-
Available once the connection is open.
61-
62-
.. attribute:: subprotocol
63-
64-
Subprotocol, if one was negotiated.
65-
66-
Available once the connection is open.
67-
68-
.. autoattribute:: close_code
69-
70-
.. autoattribute:: close_reason
71-
7230
.. automethod:: process_request
7331

7432
.. automethod:: select_subprotocol
7533

76-
.. automethod:: recv
77-
78-
.. automethod:: send
79-
80-
.. automethod:: ping
81-
82-
.. automethod:: pong
83-
84-
.. automethod:: close
85-
86-
.. automethod:: wait_closed
87-
8834
Basic authentication
8935
--------------------
9036

‎docs/reference/types.rst

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Types
2+
=====
3+
4+
.. automodule:: websockets.typing
5+
6+
.. autodata:: Data
7+
8+
.. autodata:: LoggerLike
9+
10+
.. autodata:: Origin
11+
12+
.. autodata:: Subprotocol
13+
14+
.. autodata:: ExtensionName
15+
16+
.. autodata:: ExtensionParameter
17+

‎docs/reference/utilities.rst

-22
Original file line numberDiff line numberDiff line change
@@ -17,25 +17,3 @@ Data structures
1717

1818
.. autoexception:: MultipleValuesError
1919

20-
Exceptions
21-
----------
22-
23-
.. automodule:: websockets.exceptions
24-
:members:
25-
26-
Types
27-
-----
28-
29-
.. automodule:: websockets.typing
30-
31-
.. autodata:: Data
32-
33-
.. autodata:: LoggerLike
34-
35-
.. autodata:: Origin
36-
37-
.. autodata:: Subprotocol
38-
39-
.. autodata:: ExtensionName
40-
41-
.. autodata:: ExtensionParameter

‎docs/requirements.txt

-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
furo
22
sphinx
33
sphinx-autobuild
4-
sphinx-autodoc-typehints
54
sphinx-copybutton
65
sphinx-inline-tabs
76
sphinxcontrib-spelling

‎src/websockets/__init__.py

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
from __future__ import annotations
2+
13
from .imports import lazy_import
24
from .version import version as __version__ # noqa
35

‎src/websockets/auth.py

+2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
1+
from __future__ import annotations
2+
13
# See #940 for why lazy_import isn't used here for backwards compatibility.
24
from .legacy.auth import * # noqa

‎src/websockets/client.py

+6-3
Original file line numberDiff line numberDiff line change
@@ -109,9 +109,12 @@ def process_response(self, response: Response) -> None:
109109
"""
110110
Check a handshake response received from the server.
111111
112-
:param response: response
113-
:param key: comes from :func:`build_request`
114-
:raises ~websockets.exceptions.InvalidHandshake: if the handshake response
112+
Args:
113+
response: response
114+
key: comes from :func:`build_request`
115+
116+
Raises:
117+
~websockets.exceptions.InvalidHandshake: if the handshake response
115118
is invalid
116119
117120
"""

‎src/websockets/connection.py

+4-2
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,8 @@ def receive_data(self, data: bytes) -> None:
212212
- You must call :meth:`data_to_send` and send this data.
213213
- You should call :meth:`events_received` and process these events.
214214
215-
:raises EOFError: if :meth:`receive_eof` was called before
215+
Raises:
216+
EOFError: if :meth:`receive_eof` was called before.
216217
217218
"""
218219
self.reader.feed_data(data)
@@ -228,7 +229,8 @@ def receive_eof(self) -> None:
228229
- You aren't exepcted to call :meth:`events_received` as it won't
229230
return any new events.
230231
231-
:raises EOFError: if :meth:`receive_eof` was called before
232+
Raises:
233+
EOFError: if :meth:`receive_eof` was called before.
232234
233235
"""
234236
self.reader.feed_eof()

‎src/websockets/datastructures.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,8 @@ def get_all(self, key: str) -> List[str]:
155155
"""
156156
Return the (possibly empty) list of all values for a header.
157157
158-
:param key: header name
158+
Args:
159+
key: header name.
159160
160161
"""
161162
return self._dict.get(key.lower(), [])

0 commit comments

Comments
 (0)