[3.12] pythongh-121970: Replace .. coroutine{method,function} with :async: (pythonGH-130448)

(cherry picked from commit 5ec4bf8)

Co-authored-by: sobolevn <mail@sobolevn.me>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

Author: sobolevn

Diff for: Doc/library/asyncio-eventloop.rst

@@ -162,7 +162,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,
@@ -183,7 +184,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`.
@@ -394,14 +396,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*.
@@ -547,11 +550,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.
 
@@ -632,10 +636,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.
 
@@ -668,15 +673,15 @@ Creating network servers
 
 .. _loop_create_server:
 
-.. coroutinemethod:: loop.create_server(protocol_factory, \
+.. 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, \
                         ssl_handshake_timeout=None, \
                         ssl_shutdown_timeout=None, \
-                        start_serving=True)
+                        start_serving=True):async:
 
    Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening
    on *port* of the *host* address.
@@ -777,11 +782,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)
+.. 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)
+   :async:
 
    Similar to :meth:`loop.create_server` but works with the
    :py:const:`~socket.AF_UNIX` socket family.
@@ -806,9 +812,10 @@ Creating network servers
       Added the *ssl_shutdown_timeout* 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.
 
@@ -856,8 +863,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.
@@ -886,10 +894,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.
 
@@ -983,7 +992,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>`.
@@ -997,7 +1007,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.
@@ -1008,7 +1019,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>`.
@@ -1019,7 +1031,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
@@ -1031,7 +1044,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>`.
@@ -1049,7 +1063,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
@@ -1061,7 +1076,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*.
 
@@ -1082,7 +1098,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.
@@ -1104,8 +1121,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.
@@ -1139,12 +1157,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`.
 
@@ -1166,7 +1186,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.
 
@@ -1182,7 +1203,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.
 
@@ -1447,9 +1469,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*.
@@ -1529,9 +1552,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
@@ -1651,7 +1675,8 @@ Do not instantiate the :class:`Server` class directly.
 
       .. versionadded:: 3.7
 
-   .. coroutinemethod:: start_serving()
+   .. method:: start_serving()
+      :async:
 
       Start accepting connections.
 
@@ -1667,7 +1692,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
@@ -1699,7 +1725,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.

Diff for: 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.
@@ -67,7 +68,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.
 
@@ -77,7 +79,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.