gh-121970: Replace .. coroutine{method,function} with :async: (#130448)

Co-authored-by: Adam Turner <[email protected]>

Author: sobolevn

Doc/library/asyncio-eventloop.rst

@@ -172,7 +172,8 @@ Running and stopping the loop
    This method is idempotent and irreversible.  No other methods
    should be called after the event loop is closed.
 
-.. coroutinemethod:: loop.shutdown_asyncgens()
+.. method:: loop.shutdown_asyncgens()
+   :async:
 
    Schedule all currently open :term:`asynchronous generator` objects to
    close with an :meth:`~agen.aclose` call.  After calling this method,
@@ -193,7 +194,8 @@ Running and stopping the loop
 
    .. versionadded:: 3.6
 
-.. coroutinemethod:: loop.shutdown_default_executor(timeout=None)
+.. method:: loop.shutdown_default_executor(timeout=None)
+   :async:
 
    Schedule the closure of the default executor and wait for it to join all of
    the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`.
@@ -404,14 +406,15 @@ Creating Futures and Tasks
 Opening network connections
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. coroutinemethod:: loop.create_connection(protocol_factory, \
-                          host=None, port=None, *, ssl=None, \
-                          family=0, proto=0, flags=0, sock=None, \
-                          local_addr=None, server_hostname=None, \
-                          ssl_handshake_timeout=None, \
-                          ssl_shutdown_timeout=None, \
-                          happy_eyeballs_delay=None, interleave=None, \
-                          all_errors=False)
+.. method:: loop.create_connection(protocol_factory, \
+                 host=None, port=None, *, ssl=None, \
+                 family=0, proto=0, flags=0, sock=None, \
+                 local_addr=None, server_hostname=None, \
+                 ssl_handshake_timeout=None, \
+                 ssl_shutdown_timeout=None, \
+                 happy_eyeballs_delay=None, interleave=None, \
+                 all_errors=False)
+   :async:
 
    Open a streaming transport connection to a given
    address specified by *host* and *port*.
@@ -557,11 +560,12 @@ Opening network connections
       API.  It returns a pair of (:class:`StreamReader`, :class:`StreamWriter`)
       that can be used directly in async/await code.
 
-.. coroutinemethod:: loop.create_datagram_endpoint(protocol_factory, \
-                        local_addr=None, remote_addr=None, *, \
-                        family=0, proto=0, flags=0, \
-                        reuse_port=None, \
-                        allow_broadcast=None, sock=None)
+.. method:: loop.create_datagram_endpoint(protocol_factory, \
+               local_addr=None, remote_addr=None, *, \
+               family=0, proto=0, flags=0, \
+               reuse_port=None, \
+               allow_broadcast=None, sock=None)
+   :async:
 
    Create a datagram connection.
 
@@ -642,10 +646,11 @@ Opening network connections
       The *reuse_address* parameter, disabled since Python 3.8.1,
       3.7.6 and 3.6.10, has been entirely removed.
 
-.. coroutinemethod:: loop.create_unix_connection(protocol_factory, \
-                        path=None, *, ssl=None, sock=None, \
-                        server_hostname=None, ssl_handshake_timeout=None, \
-                        ssl_shutdown_timeout=None)
+.. method:: loop.create_unix_connection(protocol_factory, \
+               path=None, *, ssl=None, sock=None, \
+               server_hostname=None, ssl_handshake_timeout=None, \
+               ssl_shutdown_timeout=None)
+   :async:
 
    Create a Unix connection.
 
@@ -678,16 +683,17 @@ Creating network servers
 
 .. _loop_create_server:
 
-.. coroutinemethod:: loop.create_server(protocol_factory, \
-                        host=None, port=None, *, \
-                        family=socket.AF_UNSPEC, \
-                        flags=socket.AI_PASSIVE, \
-                        sock=None, backlog=100, ssl=None, \
-                        reuse_address=None, reuse_port=None, \
-                        keep_alive=None, \
-                        ssl_handshake_timeout=None, \
-                        ssl_shutdown_timeout=None, \
-                        start_serving=True)
+.. method:: loop.create_server(protocol_factory, \
+               host=None, port=None, *, \
+               family=socket.AF_UNSPEC, \
+               flags=socket.AI_PASSIVE, \
+               sock=None, backlog=100, ssl=None, \
+               reuse_address=None, reuse_port=None, \
+               keep_alive=None, \
+               ssl_handshake_timeout=None, \
+               ssl_shutdown_timeout=None, \
+               start_serving=True)
+   :async:
 
    Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening
    on *port* of the *host* address.
@@ -795,11 +801,12 @@ Creating network servers
       that can be used in an async/await code.
 
 
-.. coroutinemethod:: loop.create_unix_server(protocol_factory, path=None, \
-                          *, sock=None, backlog=100, ssl=None, \
-                          ssl_handshake_timeout=None, \
-                          ssl_shutdown_timeout=None, \
-                          start_serving=True, cleanup_socket=True)
+.. method:: loop.create_unix_server(protocol_factory, path=None, \
+                 *, sock=None, backlog=100, ssl=None, \
+                 ssl_handshake_timeout=None, \
+                 ssl_shutdown_timeout=None, \
+                 start_serving=True, cleanup_socket=True)
+   :async:
 
    Similar to :meth:`loop.create_server` but works with the
    :py:const:`~socket.AF_UNIX` socket family.
@@ -832,9 +839,10 @@ Creating network servers
       Added the *cleanup_socket* parameter.
 
 
-.. coroutinemethod:: loop.connect_accepted_socket(protocol_factory, \
-                        sock, *, ssl=None, ssl_handshake_timeout=None, \
-                        ssl_shutdown_timeout=None)
+.. method:: loop.connect_accepted_socket(protocol_factory, \
+               sock, *, ssl=None, ssl_handshake_timeout=None, \
+               ssl_shutdown_timeout=None)
+   :async:
 
    Wrap an already accepted connection into a transport/protocol pair.
 
@@ -882,8 +890,9 @@ Creating network servers
 Transferring files
 ^^^^^^^^^^^^^^^^^^
 
-.. coroutinemethod:: loop.sendfile(transport, file, \
-                                   offset=0, count=None, *, fallback=True)
+.. method:: loop.sendfile(transport, file, \
+                          offset=0, count=None, *, fallback=True)
+   :async:
 
    Send a *file* over a *transport*.  Return the total number of bytes
    sent.
@@ -912,10 +921,11 @@ Transferring files
 TLS Upgrade
 ^^^^^^^^^^^
 
-.. coroutinemethod:: loop.start_tls(transport, protocol, \
-                        sslcontext, *, server_side=False, \
-                        server_hostname=None, ssl_handshake_timeout=None, \
-                        ssl_shutdown_timeout=None)
+.. method:: loop.start_tls(transport, protocol, \
+               sslcontext, *, server_side=False, \
+               server_hostname=None, ssl_handshake_timeout=None, \
+               ssl_shutdown_timeout=None)
+   :async:
 
    Upgrade an existing transport-based connection to TLS.
 
@@ -1009,7 +1019,8 @@ However, there are some use cases when performance is not critical, and
 working with :class:`~socket.socket` objects directly is more
 convenient.
 
-.. coroutinemethod:: loop.sock_recv(sock, nbytes)
+.. method:: loop.sock_recv(sock, nbytes)
+   :async:
 
    Receive up to *nbytes* from *sock*.  Asynchronous version of
    :meth:`socket.recv() <socket.socket.recv>`.
@@ -1023,7 +1034,8 @@ convenient.
       method, releases before Python 3.7 returned a :class:`Future`.
       Since Python 3.7 this is an ``async def`` method.
 
-.. coroutinemethod:: loop.sock_recv_into(sock, buf)
+.. method:: loop.sock_recv_into(sock, buf)
+   :async:
 
    Receive data from *sock* into the *buf* buffer.  Modeled after the blocking
    :meth:`socket.recv_into() <socket.socket.recv_into>` method.
@@ -1034,7 +1046,8 @@ convenient.
 
    .. versionadded:: 3.7
 
-.. coroutinemethod:: loop.sock_recvfrom(sock, bufsize)
+.. method:: loop.sock_recvfrom(sock, bufsize)
+   :async:
 
    Receive a datagram of up to *bufsize* from *sock*.  Asynchronous version of
    :meth:`socket.recvfrom() <socket.socket.recvfrom>`.
@@ -1045,7 +1058,8 @@ convenient.
 
    .. versionadded:: 3.11
 
-.. coroutinemethod:: loop.sock_recvfrom_into(sock, buf, nbytes=0)
+.. method:: loop.sock_recvfrom_into(sock, buf, nbytes=0)
+   :async:
 
    Receive a datagram of up to *nbytes* from *sock* into *buf*.
    Asynchronous version of
@@ -1057,7 +1071,8 @@ convenient.
 
    .. versionadded:: 3.11
 
-.. coroutinemethod:: loop.sock_sendall(sock, data)
+.. method:: loop.sock_sendall(sock, data)
+   :async:
 
    Send *data* to the *sock* socket. Asynchronous version of
    :meth:`socket.sendall() <socket.socket.sendall>`.
@@ -1075,7 +1090,8 @@ convenient.
       method, before Python 3.7 it returned a :class:`Future`.
       Since Python 3.7, this is an ``async def`` method.
 
-.. coroutinemethod:: loop.sock_sendto(sock, data, address)
+.. method:: loop.sock_sendto(sock, data, address)
+   :async:
 
    Send a datagram from *sock* to *address*.
    Asynchronous version of
@@ -1087,7 +1103,8 @@ convenient.
 
    .. versionadded:: 3.11
 
-.. coroutinemethod:: loop.sock_connect(sock, address)
+.. method:: loop.sock_connect(sock, address)
+   :async:
 
    Connect *sock* to a remote socket at *address*.
 
@@ -1108,7 +1125,8 @@ convenient.
       and  :func:`asyncio.open_connection() <open_connection>`.
 
 
-.. coroutinemethod:: loop.sock_accept(sock)
+.. method:: loop.sock_accept(sock)
+   :async:
 
    Accept a connection.  Modeled after the blocking
    :meth:`socket.accept() <socket.socket.accept>` method.
@@ -1130,8 +1148,9 @@ convenient.
 
       :meth:`loop.create_server` and :func:`start_server`.
 
-.. coroutinemethod:: loop.sock_sendfile(sock, file, offset=0, count=None, \
-                                        *, fallback=True)
+.. method:: loop.sock_sendfile(sock, file, offset=0, count=None, \
+                               *, fallback=True)
+   :async:
 
    Send a file using high-performance :mod:`os.sendfile` if possible.
    Return the total number of bytes sent.
@@ -1165,12 +1184,14 @@ convenient.
 DNS
 ^^^
 
-.. coroutinemethod:: loop.getaddrinfo(host, port, *, family=0, \
-                        type=0, proto=0, flags=0)
+.. method:: loop.getaddrinfo(host, port, *, family=0, \
+               type=0, proto=0, flags=0)
+   :async:
 
    Asynchronous version of :meth:`socket.getaddrinfo`.
 
-.. coroutinemethod:: loop.getnameinfo(sockaddr, flags=0)
+.. method:: loop.getnameinfo(sockaddr, flags=0)
+   :async:
 
    Asynchronous version of :meth:`socket.getnameinfo`.
 
@@ -1192,7 +1213,8 @@ DNS
 Working with pipes
 ^^^^^^^^^^^^^^^^^^
 
-.. coroutinemethod:: loop.connect_read_pipe(protocol_factory, pipe)
+.. method:: loop.connect_read_pipe(protocol_factory, pipe)
+   :async:
 
    Register the read end of *pipe* in the event loop.
 
@@ -1208,7 +1230,8 @@ Working with pipes
    With :class:`SelectorEventLoop` event loop, the *pipe* is set to
    non-blocking mode.
 
-.. coroutinemethod:: loop.connect_write_pipe(protocol_factory, pipe)
+.. method:: loop.connect_write_pipe(protocol_factory, pipe)
+   :async:
 
    Register the write end of *pipe* in the event loop.
 
@@ -1480,9 +1503,10 @@ async/await code consider using the high-level
 
 .. _loop_subprocess_exec:
 
-.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \
-                      stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
-                      stderr=subprocess.PIPE, **kwargs)
+.. method:: loop.subprocess_exec(protocol_factory, *args, \
+             stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
+             stderr=subprocess.PIPE, **kwargs)
+   :async:
 
    Create a subprocess from one or more string arguments specified by
    *args*.
@@ -1562,9 +1586,10 @@ async/await code consider using the high-level
    conforms to the :class:`asyncio.SubprocessTransport` base class and
    *protocol* is an object instantiated by the *protocol_factory*.
 
-.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, *, \
-                        stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
-                        stderr=subprocess.PIPE, **kwargs)
+.. method:: loop.subprocess_shell(protocol_factory, cmd, *, \
+               stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
+               stderr=subprocess.PIPE, **kwargs)
+   :async:
 
    Create a subprocess from *cmd*, which can be a :class:`str` or a
    :class:`bytes` string encoded to the
@@ -1709,7 +1734,8 @@ Do not instantiate the :class:`Server` class directly.
 
       .. versionadded:: 3.7
 
-   .. coroutinemethod:: start_serving()
+   .. method:: start_serving()
+      :async:
 
       Start accepting connections.
 
@@ -1725,7 +1751,8 @@ Do not instantiate the :class:`Server` class directly.
 
       .. versionadded:: 3.7
 
-   .. coroutinemethod:: serve_forever()
+   .. method:: serve_forever()
+      :async:
 
       Start accepting connections until the coroutine is cancelled.
       Cancellation of ``serve_forever`` task causes the server
@@ -1757,7 +1784,8 @@ Do not instantiate the :class:`Server` class directly.
 
       .. versionadded:: 3.7
 
-   .. coroutinemethod:: wait_closed()
+   .. method:: wait_closed()
+      :async:
 
       Wait until the :meth:`close` method completes and all active
       connections have finished.

Doc/library/asyncio-queue.rst

@@ -57,7 +57,8 @@ Queue
       If the queue was initialized with ``maxsize=0`` (the default),
       then :meth:`full` never returns ``True``.
 
-   .. coroutinemethod:: get()
+   .. method:: get()
+      :async:
 
       Remove and return an item from the queue. If queue is empty,
       wait until an item is available.
@@ -70,7 +71,8 @@ Queue
       Return an item if one is immediately available, else raise
       :exc:`QueueEmpty`.
 
-   .. coroutinemethod:: join()
+   .. method:: join()
+      :async:
 
       Block until all items in the queue have been received and processed.
 
@@ -80,7 +82,8 @@ Queue
       work on it is complete.  When the count of unfinished tasks drops
       to zero, :meth:`join` unblocks.
 
-   .. coroutinemethod:: put(item)
+   .. method:: put(item)
+      :async:
 
       Put an item into the queue. If the queue is full, wait until a
       free slot is available before adding the item.