Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Feb 22, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
081cc42
gh-121970: Replace `.. coroutine{method,function}` with `:async:`
sobolevn Feb 22, 2025
ada3eef
Fix lint
sobolevn Feb 22, 2025
d3efa3c
Fix problems
AA-Turner Feb 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 95 additions & 67 deletions Doc/library/asyncio-eventloop.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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`.
Expand Down Expand Up @@ -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*.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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>`.
Expand All @@ -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.
Expand All @@ -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>`.
Expand All @@ -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
Expand All @@ -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>`.
Expand All @@ -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
Expand All @@ -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*.

Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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`.

Expand All @@ -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.

Expand All @@ -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.

Expand Down Expand Up @@ -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*.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
9 changes: 6 additions & 3 deletions Doc/library/asyncio-queue.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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.
Expand Down
Loading
Loading