From 034cecc42b765eca64bd6dd95bd5e8f074adf82c Mon Sep 17 00:00:00 2001 From: Sam Bull Date: Fri, 28 Jul 2023 00:29:29 +0100 Subject: [PATCH] Remove sphinxcontrib-asyncio (#7439) (#7440) I don't think this is needed anymore, and may be causing issues with newer sphinx releases. (cherry picked from commit c6217be36c2e64d16656be940997f6cb7d82cc94) --- docs/abc.rst | 9 ++- docs/client_reference.rst | 125 +++++++++++++++++++---------------- docs/conf.py | 1 - docs/multipart_reference.rst | 39 +++++++---- docs/streams.rst | 33 +++++---- docs/testing.rst | 56 ++++++++++------ docs/web_reference.rst | 99 ++++++++++++++++++--------- requirements/constraints.txt | 5 +- requirements/doc.txt | 3 +- 9 files changed, 225 insertions(+), 145 deletions(-) diff --git a/docs/abc.rst b/docs/abc.rst index f905d927efc..bf84b5a2807 100644 --- a/docs/abc.rst +++ b/docs/abc.rst @@ -39,7 +39,8 @@ Not Allowed*. :meth:`aiohttp.abc.AbstractMatchInfo.handler` raises *router* parameter and returns as :attr:`aiohttp.web.Application.router`. - .. coroutinemethod:: resolve(request) + .. method:: resolve(request) + :async: Performs URL resolving. It's an abstract method, should be overridden in *router* implementation. @@ -61,7 +62,8 @@ Not Allowed*. :meth:`aiohttp.abc.AbstractMatchInfo.handler` raises :exc:`aiohttp.web.HTTPException` if no match was found, ``None`` otherwise. - .. coroutinemethod:: handler(request) + .. method:: handler(request) + :async: Abstract method performing :term:`web-handler` processing. @@ -73,7 +75,8 @@ Not Allowed*. :meth:`aiohttp.abc.AbstractMatchInfo.handler` raises :raise: :class:`aiohttp.web.HTTPException` on error - .. coroutinemethod:: expect_handler(request) + .. method:: expect_handler(request) + :async: Abstract method for handling *100-continue* processing. diff --git a/docs/client_reference.rst b/docs/client_reference.rst index 7d31fe468d4..e4f1b22be43 100644 --- a/docs/client_reference.rst +++ b/docs/client_reference.rst @@ -352,7 +352,7 @@ The client session supports the context manager protocol for self closing. .. versionadded:: 3.7 - .. comethod:: request(method, url, *, params=None, data=None, json=None,\ + .. method:: request(method, url, *, params=None, data=None, json=None,\ cookies=None, headers=None, skip_auto_headers=None, \ auth=None, allow_redirects=True,\ max_redirects=10,\ @@ -364,11 +364,11 @@ The client session supports the context manager protocol for self closing. verify_ssl=None, fingerprint=None, \ ssl_context=None, proxy_headers=None, \ auto_decompress=None) - :async-with: - :coroutine: + :async: :noindexentry: - Performs an asynchronous HTTP request. Returns a response object. + Performs an asynchronous HTTP request. Returns a response object that + should be used as an async context manager. :param str method: HTTP method @@ -544,11 +544,10 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: get(url, *, allow_redirects=True, **kwargs) - :async-with: - :coroutine: + .. method:: get(url, *, allow_redirects=True, **kwargs) + :async: - Perform a ``GET`` request. + Perform a ``GET`` request. Returns an async context manager. In order to modify inner :meth:`request` @@ -562,11 +561,10 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: post(url, *, data=None, **kwargs) - :async-with: - :coroutine: + .. method:: post(url, *, data=None, **kwargs) + :async: - Perform a ``POST`` request. + Perform a ``POST`` request. Returns an async context manager. In order to modify inner :meth:`request` @@ -582,11 +580,10 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: put(url, *, data=None, **kwargs) - :async-with: - :coroutine: + .. method:: put(url, *, data=None, **kwargs) + :async: - Perform a ``PUT`` request. + Perform a ``PUT`` request. Returns an async context manager. In order to modify inner :meth:`request` @@ -602,11 +599,10 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: delete(url, **kwargs) - :async-with: - :coroutine: + .. method:: delete(url, **kwargs) + :async: - Perform a ``DELETE`` request. + Perform a ``DELETE`` request. Returns an async context manager. In order to modify inner :meth:`request` @@ -617,11 +613,10 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: head(url, *, allow_redirects=False, **kwargs) - :async-with: - :coroutine: + .. method:: head(url, *, allow_redirects=False, **kwargs) + :async: - Perform a ``HEAD`` request. + Perform a ``HEAD`` request. Returns an async context manager. In order to modify inner :meth:`request` @@ -635,11 +630,10 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: options(url, *, allow_redirects=True, **kwargs) - :async-with: - :coroutine: + .. method:: options(url, *, allow_redirects=True, **kwargs) + :async: - Perform an ``OPTIONS`` request. + Perform an ``OPTIONS`` request. Returns an async context manager. In order to modify inner :meth:`request` @@ -654,11 +648,10 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: patch(url, *, data=None, **kwargs) - :async-with: - :coroutine: + .. method:: patch(url, *, data=None, **kwargs) + :async: - Perform a ``PATCH`` request. + Perform a ``PATCH`` request. Returns an async context manager. In order to modify inner :meth:`request` @@ -673,7 +666,7 @@ The client session supports the context manager protocol for self closing. :return ClientResponse: a :class:`client response ` object. - .. comethod:: ws_connect(url, *, method='GET', \ + .. method:: ws_connect(url, *, method='GET', \ protocols=(), timeout=10.0,\ receive_timeout=None,\ auth=None,\ @@ -687,11 +680,10 @@ The client session supports the context manager protocol for self closing. verify_ssl=None, fingerprint=None, \ ssl_context=None, proxy_headers=None, \ compress=0, max_msg_size=4194304) - :async-with: - :coroutine: + :async: Create a websocket connection. Returns a - :class:`ClientWebSocketResponse` object. + :class:`ClientWebSocketResponse` async context manager object. :param url: Websocket server url, :class:`~yarl.URL` or :class:`str` that will be encoded with :class:`~yarl.URL` (see :class:`~yarl.URL` @@ -818,7 +810,8 @@ The client session supports the context manager protocol for self closing. .. versionadded:: 3.5 - .. comethod:: close() + .. method:: close() + :async: Close underlying connector. @@ -843,7 +836,7 @@ keepaliving, cookies and complex connection stuff like properly configured SSL certification chaining. -.. cofunction:: request(method, url, *, params=None, data=None, \ +.. function:: request(method, url, *, params=None, data=None, \ json=None,\ headers=None, cookies=None, auth=None, \ allow_redirects=True, max_redirects=10, \ @@ -853,10 +846,11 @@ certification chaining. read_bufsize=None, \ connector=None, loop=None,\ read_until_eof=True, timeout=sentinel) - :async-with: + :async: Asynchronous context manager for performing an asynchronous HTTP - request. Returns a :class:`ClientResponse` response object. + request. Returns a :class:`ClientResponse` response object. Use as + an async context manager. :param str method: HTTP method @@ -1028,11 +1022,13 @@ BaseConnector Read-only property. - .. comethod:: close() + .. method:: close() + :async: Close all opened connections. - .. comethod:: connect(request) + .. method:: connect(request) + :async: Get a free connection from pool or create new one if connection is absent in the pool. @@ -1046,7 +1042,8 @@ BaseConnector :return: :class:`Connection` object. - .. comethod:: _create_connection(req) + .. method:: _create_connection(req) + :async: Abstract method for actual connection establishing, should be overridden in subclasses. @@ -1397,7 +1394,8 @@ Response object For :term:`keep-alive` support see :meth:`release`. - .. comethod:: read() + .. method:: read() + :async: Read the whole response's body as :class:`bytes`. @@ -1411,7 +1409,8 @@ Response object .. seealso:: :meth:`close`, :meth:`release`. - .. comethod:: release() + .. method:: release() + :async: It is not required to call `release` on the response object. When the client fully receives the payload, the @@ -1425,7 +1424,8 @@ Response object Do nothing for success responses (less than 400). - .. comethod:: text(encoding=None) + .. method:: text(encoding=None) + :async: Read response's body and return decoded :class:`str` using specified *encoding* parameter. @@ -1460,8 +1460,9 @@ Response object await resp.text('ISO-8859-1') - .. comethod:: json(*, encoding=None, loads=json.loads, \ + .. method:: json(*, encoding=None, loads=json.loads, \ content_type='application/json') + :async: Read response's body as *JSON*, return :class:`dict` using specified *encoding* and *loader*. If data is not still available @@ -1550,7 +1551,8 @@ manually. Returns exception if any occurs or returns None. - .. comethod:: ping(message=b'') + .. method:: ping(message=b'') + :async: Send :const:`~aiohttp.WSMsgType.PING` to peer. @@ -1562,7 +1564,8 @@ manually. The method is converted into :term:`coroutine` - .. comethod:: pong(message=b'') + .. method:: pong(message=b'') + :async: Send :const:`~aiohttp.WSMsgType.PONG` to peer. @@ -1574,7 +1577,8 @@ manually. The method is converted into :term:`coroutine` - .. comethod:: send_str(data, compress=None) + .. method:: send_str(data, compress=None) + :async: Send *data* to peer as :const:`~aiohttp.WSMsgType.TEXT` message. @@ -1591,7 +1595,8 @@ manually. The method is converted into :term:`coroutine`, *compress* parameter added. - .. comethod:: send_bytes(data, compress=None) + .. method:: send_bytes(data, compress=None) + :async: Send *data* to peer as :const:`~aiohttp.WSMsgType.BINARY` message. @@ -1609,7 +1614,8 @@ manually. The method is converted into :term:`coroutine`, *compress* parameter added. - .. comethod:: send_json(data, compress=None, *, dumps=json.dumps) + .. method:: send_json(data, compress=None, *, dumps=json.dumps) + :async: Send *data* to peer as JSON string. @@ -1635,7 +1641,8 @@ manually. The method is converted into :term:`coroutine`, *compress* parameter added. - .. comethod:: close(*, code=WSCloseCode.OK, message=b'') + .. method:: close(*, code=WSCloseCode.OK, message=b'') + :async: A :ref:`coroutine` that initiates closing handshake by sending :const:`~aiohttp.WSMsgType.CLOSE` message. It waits for @@ -1647,7 +1654,8 @@ manually. :param message: optional payload of *close* message, :class:`str` (converted to *UTF-8* encoded bytes) or :class:`bytes`. - .. comethod:: receive() + .. method:: receive() + :async: A :ref:`coroutine` that waits upcoming *data* message from peer and returns it. @@ -1662,7 +1670,8 @@ manually. :return: :class:`~aiohttp.WSMessage` - .. coroutinemethod:: receive_str() + .. method:: receive_str() + :async: A :ref:`coroutine` that calls :meth:`receive` but also asserts the message type is @@ -1672,7 +1681,8 @@ manually. :raise TypeError: if message is :const:`~aiohttp.WSMsgType.BINARY`. - .. coroutinemethod:: receive_bytes() + .. method:: receive_bytes() + :async: A :ref:`coroutine` that calls :meth:`receive` but also asserts the message type is @@ -1682,7 +1692,8 @@ manually. :raise TypeError: if message is :const:`~aiohttp.WSMsgType.TEXT`. - .. coroutinemethod:: receive_json(*, loads=json.loads) + .. method:: receive_json(*, loads=json.loads) + :async: A :ref:`coroutine` that calls :meth:`receive_str` and loads the JSON string to a Python dict. diff --git a/docs/conf.py b/docs/conf.py index 5379d663ed8..0b201af1fb8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,7 +52,6 @@ "sphinx.ext.intersphinx", "sphinx.ext.viewcode", # Third-party extensions: - "sphinxcontrib.asyncio", "sphinxcontrib.blockdiag", "sphinxcontrib.towncrier", # provides `towncrier-draft-entries` directive ] diff --git a/docs/multipart_reference.rst b/docs/multipart_reference.rst index 90fda21179d..e0f6e4a0162 100644 --- a/docs/multipart_reference.rst +++ b/docs/multipart_reference.rst @@ -17,11 +17,13 @@ Multipart reference :rtype: bool - .. comethod:: next() + .. method:: next() + :async: Emits next multipart reader object. - .. comethod:: release() + .. method:: release() + :async: Releases the connection gracefully, reading all the content to the void. @@ -31,7 +33,8 @@ Multipart reference Multipart reader for single body part. - .. comethod:: read(*, decode=False) + .. method:: read(*, decode=False) + :async: Reads body part data. @@ -41,7 +44,8 @@ Multipart reference :rtype: bytearray - .. comethod:: read_chunk(size=chunk_size) + .. method:: read_chunk(size=chunk_size) + :async: Reads body part content chunk of the specified size. @@ -49,19 +53,22 @@ Multipart reference :rtype: bytearray - .. comethod:: readline() + .. method:: readline() + :async: Reads body part by line by line. :rtype: bytearray - .. comethod:: release() + .. method:: release() + :async: Like :meth:`read`, but reads all the data to the void. :rtype: None - .. comethod:: text(*, encoding=None) + .. method:: text(*, encoding=None) + :async: Like :meth:`read`, but assumes that body part contains text data. @@ -70,14 +77,16 @@ Multipart reference :rtype: str - .. comethod:: json(*, encoding=None) + .. method:: json(*, encoding=None) + :async: Like :meth:`read`, but assumes that body parts contains JSON data. :param str encoding: Custom JSON encoding. Overrides specified in charset param of ``Content-Type`` header - .. comethod:: form(*, encoding=None) + .. method:: form(*, encoding=None) + :async: Like :meth:`read`, but assumes that body parts contains form urlencoded data. @@ -144,15 +153,18 @@ Multipart reference :rtype: bool - .. comethod:: next() + .. method:: next() + :async: Emits the next multipart body part. - .. comethod:: release() + .. method:: release() + :async: Reads all the body parts to the void till the final boundary. - .. comethod:: fetch_next_part() + .. method:: fetch_next_part() + :async: Returns the next body part reader. @@ -191,7 +203,8 @@ Multipart reference Size of the payload. - .. comethod:: write(writer, close_boundary=True) + .. method:: write(writer, close_boundary=True) + :async: Write body. diff --git a/docs/streams.rst b/docs/streams.rst index 25a83be40c4..10eec6d6a43 100644 --- a/docs/streams.rst +++ b/docs/streams.rst @@ -23,7 +23,8 @@ Streaming API Reading Methods --------------- -.. comethod:: StreamReader.read(n=-1) +.. method:: StreamReader.read(n=-1) + :async: Read up to *n* bytes. If *n* is not provided, or set to ``-1``, read until EOF and return all read bytes. @@ -35,7 +36,8 @@ Reading Methods :return bytes: the given data -.. comethod:: StreamReader.readany() +.. method:: StreamReader.readany() + :async: Read next data portion for the stream. @@ -43,7 +45,8 @@ Reading Methods :return bytes: the given data -.. comethod:: StreamReader.readexactly(n) +.. method:: StreamReader.readexactly(n) + :async: Read exactly *n* bytes. @@ -57,7 +60,8 @@ Reading Methods :return bytes: the given data -.. comethod:: StreamReader.readline() +.. method:: StreamReader.readline() + :async: Read one line, where “line” is a sequence of bytes ending with ``\n``. @@ -70,7 +74,8 @@ Reading Methods :return bytes: the given line -.. comethod:: StreamReader.readuntil(separator="\n") +.. method:: StreamReader.readuntil(separator="\n") + :async: Read until separator, where `separator` is a sequence of bytes. @@ -84,7 +89,8 @@ Reading Methods :return bytes: the given data -.. comethod:: StreamReader.readchunk() +.. method:: StreamReader.readchunk() + :async: Read a chunk of data as it was received by the server. @@ -113,24 +119,24 @@ By default it iterates over lines:: Also there are methods for iterating over data chunks with maximum size limit and over any available data. -.. comethod:: StreamReader.iter_chunked(n) - :async-for: +.. method:: StreamReader.iter_chunked(n) + :async: Iterates over data chunks with maximum size limit:: async for data in response.content.iter_chunked(1024): print(data) -.. comethod:: StreamReader.iter_any() - :async-for: +.. method:: StreamReader.iter_any() + :async: Iterates over data chunks in order of intaking them into the stream:: async for data in response.content.iter_any(): print(data) -.. comethod:: StreamReader.iter_chunks() - :async-for: +.. method:: StreamReader.iter_chunks() + :async: Iterates over data chunks as received from the server:: @@ -193,6 +199,7 @@ Helpers E.g. :meth:`~StreamReader.read()` will not be resumed. -.. comethod:: wait_eof() +.. method:: wait_eof() + :async: Wait for EOF. The given data may be accessible by upcoming read calls. diff --git a/docs/testing.rst b/docs/testing.rst index 47edd65e266..15f163107f2 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -293,7 +293,8 @@ functionality, the AioHTTPTestCase is provided:: The application returned by :meth:`~aiohttp.test_utils.AioHTTPTestCase.get_application` (:class:`aiohttp.web.Application` instance). - .. comethod:: get_client() + .. method:: get_client() + :async: This async method can be overridden to return the :class:`TestClient` object used in the test. @@ -302,7 +303,8 @@ functionality, the AioHTTPTestCase is provided:: .. versionadded:: 2.3 - .. comethod:: get_server() + .. method:: get_server() + :async: This async method can be overridden to return the :class:`TestServer` object used in the test. @@ -311,7 +313,8 @@ functionality, the AioHTTPTestCase is provided:: .. versionadded:: 2.3 - .. comethod:: get_application() + .. method:: get_application() + :async: This async method should be overridden to return the :class:`aiohttp.web.Application` @@ -319,7 +322,8 @@ functionality, the AioHTTPTestCase is provided:: :return: :class:`aiohttp.web.Application` instance. - .. comethod:: asyncSetUp() + .. method:: asyncSetUp() + :async: This async method can be overridden to execute asynchronous code during the ``setUp`` stage of the ``TestCase``:: @@ -334,7 +338,8 @@ functionality, the AioHTTPTestCase is provided:: ``await super().asyncSetUp()`` call is required. - .. comethod:: asyncTearDown() + .. method:: asyncTearDown() + :async: This async method can be overridden to execute asynchronous code during the ``tearDown`` stage of the ``TestCase``:: @@ -408,7 +413,7 @@ conditions that hard to reproduce on real server:: :param headers: mapping containing the headers. Can be anything accepted by the multidict.CIMultiDict constructor. - :type headers: dict, multidict.CIMultiDict, list of pairs + :type headers: dict, multidict.CIMultiDict, list of tuple(str, str) :param match_info: mapping containing the info to match with url parameters. :type match_info: dict @@ -562,14 +567,16 @@ for accessing to the server. .. versionadded:: 3.8 - .. comethod:: start_server(loop=None, **kwargs) + .. method:: start_server(loop=None, **kwargs) + :async: :param loop: the event_loop to use :type loop: asyncio.AbstractEventLoop Start a test server. - .. comethod:: close() + .. method:: close() + :async: Stop and finish executed test server. @@ -686,11 +693,13 @@ Test Client requests do not automatically include the host in the url queried, and will require an absolute path to the resource. - .. comethod:: start_server(**kwargs) + .. method:: start_server(**kwargs) + :async: Start a test server. - .. comethod:: close() + .. method:: close() + :async: Stop and finish executed test server. @@ -698,7 +707,8 @@ Test Client Return an *absolute* :class:`~yarl.URL` for given *path*. - .. comethod:: request(method, path, *args, **kwargs) + .. method:: request(method, path, *args, **kwargs) + :async: Routes a request to tested http server. @@ -706,35 +716,43 @@ Test Client :meth:`aiohttp.ClientSession.request`, except the loop kwarg is overridden by the instance used by the test server. - .. comethod:: get(path, *args, **kwargs) + .. method:: get(path, *args, **kwargs) + :async: Perform an HTTP GET request. - .. comethod:: post(path, *args, **kwargs) + .. method:: post(path, *args, **kwargs) + :async: Perform an HTTP POST request. - .. comethod:: options(path, *args, **kwargs) + .. method:: options(path, *args, **kwargs) + :async: Perform an HTTP OPTIONS request. - .. comethod:: head(path, *args, **kwargs) + .. method:: head(path, *args, **kwargs) + :async: Perform an HTTP HEAD request. - .. comethod:: put(path, *args, **kwargs) + .. method:: put(path, *args, **kwargs) + :async: Perform an HTTP PUT request. - .. comethod:: patch(path, *args, **kwargs) + .. method:: patch(path, *args, **kwargs) + :async: Perform an HTTP PATCH request. - .. comethod:: delete(path, *args, **kwargs) + .. method:: delete(path, *args, **kwargs) + :async: Perform an HTTP DELETE request. - .. comethod:: ws_connect(path, *args, **kwargs) + .. method:: ws_connect(path, *args, **kwargs) + :async: Initiate websocket connection. diff --git a/docs/web_reference.rst b/docs/web_reference.rst index 78c7e1ea8b5..2023129ac5f 100644 --- a/docs/web_reference.rst +++ b/docs/web_reference.rst @@ -404,7 +404,8 @@ and :ref:`aiohttp-web-signals` handlers. .. versionadded:: 3.7 - .. comethod:: read() + .. method:: read() + :async: Read request body, returns :class:`bytes` object with body content. @@ -413,7 +414,8 @@ and :ref:`aiohttp-web-signals` handlers. The method **does** store read data internally, subsequent :meth:`~aiohttp.web.BaseRequest.read` call will return the same value. - .. comethod:: text() + .. method:: text() + :async: Read request body, decode it using :attr:`charset` encoding or ``UTF-8`` if no encoding was specified in *MIME-type*. @@ -425,7 +427,8 @@ and :ref:`aiohttp-web-signals` handlers. The method **does** store read data internally, subsequent :meth:`~aiohttp.web.BaseRequest.text` call will return the same value. - .. comethod:: json(*, loads=json.loads) + .. method:: json(*, loads=json.loads) + :async: Read request body decoded as *json*. @@ -447,7 +450,8 @@ and :ref:`aiohttp-web-signals` handlers. :meth:`~aiohttp.web.BaseRequest.json` call will return the same value. - .. comethod:: multipart() + .. method:: multipart() + :async: Returns :class:`aiohttp.MultipartReader` which processes incoming *multipart* request. @@ -472,7 +476,8 @@ and :ref:`aiohttp-web-signals` handlers. Dropped *reader* parameter. - .. comethod:: post() + .. method:: post() + :async: A :ref:`coroutine ` that reads POST parameters from request body. @@ -490,7 +495,8 @@ and :ref:`aiohttp-web-signals` handlers. The method **does** store read data internally, subsequent :meth:`~aiohttp.web.BaseRequest.post` call will return the same value. - .. comethod:: release() + .. method:: release() + :async: Release request. @@ -824,7 +830,8 @@ StreamResponse .. versionadded:: 3.8 - .. comethod:: prepare(request) + .. method:: prepare(request) + :async: :param aiohttp.web.Request request: HTTP request object, that the response answers. @@ -836,7 +843,8 @@ StreamResponse signal handlers after default headers have been computed and directly before headers are sent. - .. comethod:: write(data) + .. method:: write(data) + :async: Send byte-ish data as the part of *response BODY*:: @@ -851,7 +859,8 @@ StreamResponse Raises :exc:`RuntimeError` if :meth:`write_eof` has been called. - .. comethod:: write_eof() + .. method:: write_eof() + :async: A :ref:`coroutine` *may* be called as a mark of the *HTTP response* processing finish. @@ -978,7 +987,8 @@ WebSocketResponse print(msg.data) - .. comethod:: prepare(request) + .. method:: prepare(request) + :async: Starts websocket. After the call you can use websocket methods. @@ -1033,7 +1043,8 @@ WebSocketResponse Returns last occurred exception or None. - .. comethod:: ping(message=b'') + .. method:: ping(message=b'') + :async: Send :const:`~aiohttp.WSMsgType.PING` to peer. @@ -1047,7 +1058,8 @@ WebSocketResponse The method is converted into :term:`coroutine` - .. comethod:: pong(message=b'') + .. method:: pong(message=b'') + :async: Send *unsolicited* :const:`~aiohttp.WSMsgType.PONG` to peer. @@ -1061,7 +1073,8 @@ WebSocketResponse The method is converted into :term:`coroutine` - .. comethod:: send_str(data, compress=None) + .. method:: send_str(data, compress=None) + :async: Send *data* to peer as :const:`~aiohttp.WSMsgType.TEXT` message. @@ -1080,7 +1093,8 @@ WebSocketResponse The method is converted into :term:`coroutine`, *compress* parameter added. - .. comethod:: send_bytes(data, compress=None) + .. method:: send_bytes(data, compress=None) + :async: Send *data* to peer as :const:`~aiohttp.WSMsgType.BINARY` message. @@ -1100,7 +1114,8 @@ WebSocketResponse The method is converted into :term:`coroutine`, *compress* parameter added. - .. comethod:: send_json(data, compress=None, *, dumps=json.dumps) + .. method:: send_json(data, compress=None, *, dumps=json.dumps) + :async: Send *data* to peer as JSON string. @@ -1125,7 +1140,8 @@ WebSocketResponse The method is converted into :term:`coroutine`, *compress* parameter added. - .. comethod:: close(*, code=WSCloseCode.OK, message=b'') + .. method:: close(*, code=WSCloseCode.OK, message=b'') + :async: A :ref:`coroutine` that initiates closing handshake by sending :const:`~aiohttp.WSMsgType.CLOSE` message. @@ -1140,7 +1156,8 @@ WebSocketResponse :raise RuntimeError: if connection is not started - .. comethod:: receive(timeout=None) + .. method:: receive(timeout=None) + :async: A :ref:`coroutine` that waits upcoming *data* message from peer and returns it. @@ -1165,7 +1182,8 @@ WebSocketResponse :raise RuntimeError: if connection is not started - .. comethod:: receive_str(*, timeout=None) + .. method:: receive_str(*, timeout=None) + :async: A :ref:`coroutine` that calls :meth:`receive` but also asserts the message type is :const:`~aiohttp.WSMsgType.TEXT`. @@ -1182,7 +1200,8 @@ WebSocketResponse :raise TypeError: if message is :const:`~aiohttp.WSMsgType.BINARY`. - .. comethod:: receive_bytes(*, timeout=None) + .. method:: receive_bytes(*, timeout=None) + :async: A :ref:`coroutine` that calls :meth:`receive` but also asserts the message type is @@ -1200,7 +1219,8 @@ WebSocketResponse :raise TypeError: if message is :const:`~aiohttp.WSMsgType.TEXT`. - .. comethod:: receive_json(*, loads=json.loads, timeout=None) + .. method:: receive_json(*, loads=json.loads, timeout=None) + :async: A :ref:`coroutine` that calls :meth:`receive_str` and loads the JSON string to a Python dict. @@ -1584,7 +1604,8 @@ duplicated like one using :meth:`~aiohttp.web.Application.copy`. The method is deprecated and will be removed in future aiohttp versions. Please use :ref:`aiohttp-web-app-runners` instead. - .. comethod:: startup() + .. method:: startup() + :async: A :ref:`coroutine` that will be called along with the application's request handler. @@ -1592,7 +1613,8 @@ duplicated like one using :meth:`~aiohttp.web.Application.copy`. The purpose of the method is calling :attr:`on_startup` signal handlers. - .. comethod:: shutdown() + .. method:: shutdown() + :async: A :ref:`coroutine` that should be called on server stopping but before :meth:`cleanup()`. @@ -1600,7 +1622,8 @@ duplicated like one using :meth:`~aiohttp.web.Application.copy`. The purpose of the method is calling :attr:`on_shutdown` signal handlers. - .. comethod:: cleanup() + .. method:: cleanup() + :async: A :ref:`coroutine` that should be called on server stopping but after :meth:`shutdown`. @@ -1663,7 +1686,8 @@ A protocol factory compatible with Amount of processed requests. - .. comethod:: Server.shutdown(timeout) + .. method:: Server.shutdown(timeout) + :async: A :ref:`coroutine` that should be called to close all opened connections. @@ -1869,7 +1893,8 @@ Router is any object that implements :class:`~aiohttp.abc.AbstractRouter` interf :returns: new :class:`~aiohttp.web.AbstractRoute` instance. - .. comethod:: resolve(request) + .. method:: resolve(request) + :async: A :ref:`coroutine` that returns :class:`~aiohttp.abc.AbstractMatchInfo` for *request*. @@ -2005,7 +2030,8 @@ Resource classes hierarchy:: .. versionadded:: 3.3 - .. comethod:: resolve(request) + .. method:: resolve(request) + :async: Resolve resource by finding appropriate :term:`web-handler` for ``(method, path)`` combination. @@ -2207,7 +2233,8 @@ and *405 Method Not Allowed*. Actually it's a shortcut for ``route.resource.url_for(...)``. - .. comethod:: handle_expect_header(request) + .. method:: handle_expect_header(request) + :async: ``100-continue`` handler. @@ -2637,11 +2664,13 @@ application on specific TCP or Unix socket, e.g.:: A read-only :class:`set` of served sites (:class:`TCPSite` / :class:`UnixSite` / :class:`NamedPipeSite` / :class:`SockSite` instances). - .. comethod:: setup() + .. method:: setup() + :async: Initialize the server. Should be called before adding sites. - .. comethod:: cleanup() + .. method:: cleanup() + :async: Stop handling all registered sites and cleanup used resources. @@ -2703,13 +2732,15 @@ application on specific TCP or Unix socket, e.g.:: Read-only attribute for accessing to :class:`Application` served instance. - .. comethod:: setup() + .. method:: setup() + :async: Initialize application. Should be called before adding sites. The method calls :attr:`Application.on_startup` registered signals. - .. comethod:: cleanup() + .. method:: cleanup() + :async: Stop handling all registered sites and cleanup used resources. @@ -2747,11 +2778,13 @@ application on specific TCP or Unix socket, e.g.:: An identifier for site, read-only :class:`str` property. Could be a handled URL or UNIX socket path. - .. comethod:: start() + .. method:: start() + :async: Start handling a site. - .. comethod:: stop() + .. method:: stop() + :async: Stop handling a site. diff --git a/requirements/constraints.txt b/requirements/constraints.txt index 038853453c2..e7ece2301cc 100644 --- a/requirements/constraints.txt +++ b/requirements/constraints.txt @@ -187,17 +187,14 @@ six==1.16.0 # virtualenv snowballstemmer==2.1.0 # via sphinx -sphinx==5.1.1 +sphinx==5.3.0 # via # -r requirements/doc.txt - # sphinxcontrib-asyncio # sphinxcontrib-blockdiag # sphinxcontrib-spelling # sphinxcontrib-towncrier sphinxcontrib-applehelp==1.0.2 # via sphinx -sphinxcontrib-asyncio==0.3.0 - # via -r requirements/doc.txt sphinxcontrib-blockdiag==3.0.0 # via -r requirements/doc.txt sphinxcontrib-devhelp==1.0.2 diff --git a/requirements/doc.txt b/requirements/doc.txt index c72f9d0621e..387f0513ba2 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -2,8 +2,7 @@ aiohttp-theme==0.1.6 # Temp fix till updated: https://github.com/blockdiag/blockdiag/pull/148 funcparserlib==1.0.1 pygments==2.15.1 -sphinx==5.1.1 -sphinxcontrib-asyncio==0.3.0 +sphinx==5.3.0 sphinxcontrib-blockdiag==3.0.0 sphinxcontrib-towncrier==0.3.0a0 towncrier==22.8.0