mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 10:19:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.13] gh-121970: Replace .. coroutine{method,function} with :async: (GH-130448) (#130465)

Browse source 
(cherry picked from commit 5ec4bf86b7)

Co-authored-by: sobolevn <mail@sobolevn.me>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot) 2025-02-22 19:00:49 +01:00 • committed by GitHub
parent 2412c914ef
commit c68a8722be
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 197 additions and 150 deletions
Download patch file Download diff file Expand all files Collapse all files

84
Doc/library/asyncio-eventloop.rst
View file

@ -162,7 +162,8 @@ Running and stopping the loop
This method is idempotent and irreversible. No other methods This method is idempotent and irreversible. No other methods
should be called after the event loop is closed. 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 Schedule all currently open :term:`asynchronous generator` objects to
close with an :meth:`~agen.aclose` call. After calling this method, close with an :meth:`~agen.aclose` call. After calling this method,
@ -183,7 +184,8 @@ Running and stopping the loop
.. versionadded:: 3.6 .. 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 Schedule the closure of the default executor and wait for it to join all of
the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`. the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`.
@ -394,7 +396,7 @@ Creating Futures and Tasks
Opening network connections Opening network connections
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.create_connection(protocol_factory, \ .. method:: loop.create_connection(protocol_factory, \
host=None, port=None, *, ssl=None, \ host=None, port=None, *, ssl=None, \
family=0, proto=0, flags=0, sock=None, \ family=0, proto=0, flags=0, sock=None, \
local_addr=None, server_hostname=None, \ local_addr=None, server_hostname=None, \
@ -402,6 +404,7 @@ Opening network connections
ssl_shutdown_timeout=None, \ ssl_shutdown_timeout=None, \
happy_eyeballs_delay=None, interleave=None, \ happy_eyeballs_delay=None, interleave=None, \
all_errors=False) all_errors=False)
:async:
Open a streaming transport connection to a given Open a streaming transport connection to a given
address specified by *host* and *port*. address specified by *host* and *port*.
@ -547,11 +550,12 @@ Opening network connections
API. It returns a pair of (:class:`StreamReader`, :class:`StreamWriter`) API. It returns a pair of (:class:`StreamReader`, :class:`StreamWriter`)
that can be used directly in async/await code. that can be used directly in async/await code.
.. coroutinemethod:: loop.create_datagram_endpoint(protocol_factory, \ .. method:: loop.create_datagram_endpoint(protocol_factory, \
local_addr=None, remote_addr=None, *, \ local_addr=None, remote_addr=None, *, \
family=0, proto=0, flags=0, \ family=0, proto=0, flags=0, \
reuse_port=None, \ reuse_port=None, \
allow_broadcast=None, sock=None) allow_broadcast=None, sock=None)
:async:
Create a datagram connection. Create a datagram connection.
@ -632,10 +636,11 @@ Opening network connections
The *reuse_address* parameter, disabled since Python 3.8.1, The *reuse_address* parameter, disabled since Python 3.8.1,
3.7.6 and 3.6.10, has been entirely removed. 3.7.6 and 3.6.10, has been entirely removed.
.. coroutinemethod:: loop.create_unix_connection(protocol_factory, \ .. method:: loop.create_unix_connection(protocol_factory, \
path=None, *, ssl=None, sock=None, \ path=None, *, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None, \ server_hostname=None, ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None) ssl_shutdown_timeout=None)
:async:
Create a Unix connection. Create a Unix connection.
@ -668,7 +673,7 @@ Creating network servers
.. _loop_create_server: .. _loop_create_server:
.. coroutinemethod:: loop.create_server(protocol_factory, \ .. method:: loop.create_server(protocol_factory, \
host=None, port=None, *, \ host=None, port=None, *, \
family=socket.AF_UNSPEC, \ family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, \ flags=socket.AI_PASSIVE, \
@ -678,6 +683,7 @@ Creating network servers
ssl_handshake_timeout=None, \ ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None, \ ssl_shutdown_timeout=None, \
start_serving=True) start_serving=True)
:async:
Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening Create a TCP server (socket type :const:`~socket.SOCK_STREAM`) listening
on *port* of the *host* address. on *port* of the *host* address.
@ -785,11 +791,12 @@ Creating network servers
that can be used in an async/await code. that can be used in an async/await code.
.. coroutinemethod:: loop.create_unix_server(protocol_factory, path=None, \ .. method:: loop.create_unix_server(protocol_factory, path=None, \
*, sock=None, backlog=100, ssl=None, \ *, sock=None, backlog=100, ssl=None, \
ssl_handshake_timeout=None, \ ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None, \ ssl_shutdown_timeout=None, \
start_serving=True, cleanup_socket=True) start_serving=True, cleanup_socket=True)
:async:
Similar to :meth:`loop.create_server` but works with the Similar to :meth:`loop.create_server` but works with the
:py:const:`~socket.AF_UNIX` socket family. :py:const:`~socket.AF_UNIX` socket family.
@ -822,9 +829,10 @@ Creating network servers
Added the *cleanup_socket* parameter. Added the *cleanup_socket* parameter.
.. coroutinemethod:: loop.connect_accepted_socket(protocol_factory, \ .. method:: loop.connect_accepted_socket(protocol_factory, \
sock, *, ssl=None, ssl_handshake_timeout=None, \ sock, *, ssl=None, ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None) ssl_shutdown_timeout=None)
:async:
Wrap an already accepted connection into a transport/protocol pair. Wrap an already accepted connection into a transport/protocol pair.
@ -872,8 +880,9 @@ Creating network servers
Transferring files Transferring files
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
.. coroutinemethod:: loop.sendfile(transport, file, \ .. method:: loop.sendfile(transport, file, \
offset=0, count=None, *, fallback=True) offset=0, count=None, *, fallback=True)
:async:
Send a *file* over a *transport*. Return the total number of bytes Send a *file* over a *transport*. Return the total number of bytes
sent. sent.
@ -902,10 +911,11 @@ Transferring files
TLS Upgrade TLS Upgrade
^^^^^^^^^^^ ^^^^^^^^^^^
.. coroutinemethod:: loop.start_tls(transport, protocol, \ .. method:: loop.start_tls(transport, protocol, \
sslcontext, *, server_side=False, \ sslcontext, *, server_side=False, \
server_hostname=None, ssl_handshake_timeout=None, \ server_hostname=None, ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None) ssl_shutdown_timeout=None)
:async:
Upgrade an existing transport-based connection to TLS. Upgrade an existing transport-based connection to TLS.
@ -999,7 +1009,8 @@ However, there are some use cases when performance is not critical, and
working with :class:`~socket.socket` objects directly is more working with :class:`~socket.socket` objects directly is more
convenient. convenient.
.. coroutinemethod:: loop.sock_recv(sock, nbytes) .. method:: loop.sock_recv(sock, nbytes)
:async:
Receive up to *nbytes* from *sock*. Asynchronous version of Receive up to *nbytes* from *sock*. Asynchronous version of
:meth:`socket.recv() <socket.socket.recv>`. :meth:`socket.recv() <socket.socket.recv>`.
@ -1013,7 +1024,8 @@ convenient.
method, releases before Python 3.7 returned a :class:`Future`. method, releases before Python 3.7 returned a :class:`Future`.
Since Python 3.7 this is an ``async def`` method. 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 Receive data from *sock* into the *buf* buffer. Modeled after the blocking
:meth:`socket.recv_into() <socket.socket.recv_into>` method. :meth:`socket.recv_into() <socket.socket.recv_into>` method.
@ -1024,7 +1036,8 @@ convenient.
.. versionadded:: 3.7 .. 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 Receive a datagram of up to *bufsize* from *sock*. Asynchronous version of
:meth:`socket.recvfrom() <socket.socket.recvfrom>`. :meth:`socket.recvfrom() <socket.socket.recvfrom>`.
@ -1035,7 +1048,8 @@ convenient.
.. versionadded:: 3.11 .. 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*. Receive a datagram of up to *nbytes* from *sock* into *buf*.
Asynchronous version of Asynchronous version of
@ -1047,7 +1061,8 @@ convenient.
.. versionadded:: 3.11 .. 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 Send *data* to the *sock* socket. Asynchronous version of
:meth:`socket.sendall() <socket.socket.sendall>`. :meth:`socket.sendall() <socket.socket.sendall>`.
@ -1065,7 +1080,8 @@ convenient.
method, before Python 3.7 it returned a :class:`Future`. method, before Python 3.7 it returned a :class:`Future`.
Since Python 3.7, this is an ``async def`` method. 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*. Send a datagram from *sock* to *address*.
Asynchronous version of Asynchronous version of
@ -1077,7 +1093,8 @@ convenient.
.. versionadded:: 3.11 .. versionadded:: 3.11
.. coroutinemethod:: loop.sock_connect(sock, address) .. method:: loop.sock_connect(sock, address)
:async:
Connect *sock* to a remote socket at *address*. Connect *sock* to a remote socket at *address*.
@ -1098,7 +1115,8 @@ convenient.
and :func:`asyncio.open_connection() <open_connection>`. 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 Accept a connection. Modeled after the blocking
:meth:`socket.accept() <socket.socket.accept>` method. :meth:`socket.accept() <socket.socket.accept>` method.
@ -1120,8 +1138,9 @@ convenient.
:meth:`loop.create_server` and :func:`start_server`. :meth:`loop.create_server` and :func:`start_server`.
.. coroutinemethod:: loop.sock_sendfile(sock, file, offset=0, count=None, \ .. method:: loop.sock_sendfile(sock, file, offset=0, count=None, \
*, fallback=True) *, fallback=True)
:async:
Send a file using high-performance :mod:`os.sendfile` if possible. Send a file using high-performance :mod:`os.sendfile` if possible.
Return the total number of bytes sent. Return the total number of bytes sent.
@ -1155,12 +1174,14 @@ convenient.
DNS DNS
^^^ ^^^
.. coroutinemethod:: loop.getaddrinfo(host, port, *, family=0, \ .. method:: loop.getaddrinfo(host, port, *, family=0, \
type=0, proto=0, flags=0) type=0, proto=0, flags=0)
:async:
Asynchronous version of :meth:`socket.getaddrinfo`. 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`. Asynchronous version of :meth:`socket.getnameinfo`.
@ -1182,7 +1203,8 @@ DNS
Working with pipes 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. Register the read end of *pipe* in the event loop.
@ -1198,7 +1220,8 @@ Working with pipes
With :class:`SelectorEventLoop` event loop, the *pipe* is set to With :class:`SelectorEventLoop` event loop, the *pipe* is set to
non-blocking mode. 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. Register the write end of *pipe* in the event loop.
@ -1463,9 +1486,10 @@ async/await code consider using the high-level
.. _loop_subprocess_exec: .. _loop_subprocess_exec:
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \ .. method:: loop.subprocess_exec(protocol_factory, *args, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \ stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, **kwargs) stderr=subprocess.PIPE, **kwargs)
:async:
Create a subprocess from one or more string arguments specified by Create a subprocess from one or more string arguments specified by
*args*. *args*.
@ -1545,9 +1569,10 @@ async/await code consider using the high-level
conforms to the :class:`asyncio.SubprocessTransport` base class and conforms to the :class:`asyncio.SubprocessTransport` base class and
*protocol* is an object instantiated by the *protocol_factory*. *protocol* is an object instantiated by the *protocol_factory*.
.. coroutinemethod:: loop.subprocess_shell(protocol_factory, cmd, *, \ .. method:: loop.subprocess_shell(protocol_factory, cmd, *, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \ stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
stderr=subprocess.PIPE, **kwargs) stderr=subprocess.PIPE, **kwargs)
:async:
Create a subprocess from *cmd*, which can be a :class:`str` or a Create a subprocess from *cmd*, which can be a :class:`str` or a
:class:`bytes` string encoded to the :class:`bytes` string encoded to the
@ -1692,7 +1717,8 @@ Do not instantiate the :class:`Server` class directly.
.. versionadded:: 3.7 .. versionadded:: 3.7
.. coroutinemethod:: start_serving() .. method:: start_serving()
:async:
Start accepting connections. Start accepting connections.
@ -1708,7 +1734,8 @@ Do not instantiate the :class:`Server` class directly.
.. versionadded:: 3.7 .. versionadded:: 3.7
.. coroutinemethod:: serve_forever() .. method:: serve_forever()
:async:
Start accepting connections until the coroutine is cancelled. Start accepting connections until the coroutine is cancelled.
Cancellation of ``serve_forever`` task causes the server Cancellation of ``serve_forever`` task causes the server
@ -1740,7 +1767,8 @@ Do not instantiate the :class:`Server` class directly.
.. versionadded:: 3.7 .. versionadded:: 3.7
.. coroutinemethod:: wait_closed() .. method:: wait_closed()
:async:
Wait until the :meth:`close` method completes and all active Wait until the :meth:`close` method completes and all active
connections have finished. connections have finished.

9
Doc/library/asyncio-queue.rst
View file

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

33
Doc/library/asyncio-stream.rst
View file

@ -48,12 +48,13 @@ The following top-level asyncio functions can be used to create
and work with streams: and work with streams:
.. coroutinefunction:: open_connection(host=None, port=None, *, \ .. function:: open_connection(host=None, port=None, *, \
limit=None, ssl=None, family=0, proto=0, \ limit=None, ssl=None, family=0, proto=0, \
flags=0, sock=None, local_addr=None, \ flags=0, sock=None, local_addr=None, \
server_hostname=None, ssl_handshake_timeout=None, \ server_hostname=None, ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None, \ ssl_shutdown_timeout=None, \
happy_eyeballs_delay=None, interleave=None) happy_eyeballs_delay=None, interleave=None)
:async:
Establish a network connection and return a pair of Establish a network connection and return a pair of
``(reader, writer)`` objects. ``(reader, writer)`` objects.
@ -87,7 +88,7 @@ and work with streams:
Added the *ssl_shutdown_timeout* parameter. Added the *ssl_shutdown_timeout* parameter.
.. coroutinefunction:: start_server(client_connected_cb, host=None, \ .. function:: start_server(client_connected_cb, host=None, \
port=None, *, limit=None, \ port=None, *, limit=None, \
family=socket.AF_UNSPEC, \ family=socket.AF_UNSPEC, \
flags=socket.AI_PASSIVE, sock=None, \ flags=socket.AI_PASSIVE, sock=None, \
@ -95,6 +96,7 @@ and work with streams:
reuse_port=None, keep_alive=None, \ reuse_port=None, keep_alive=None, \
ssl_handshake_timeout=None, \ ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None, start_serving=True) ssl_shutdown_timeout=None, start_serving=True)
:async:
Start a socket server. Start a socket server.
@ -135,9 +137,10 @@ and work with streams:
.. rubric:: Unix Sockets .. rubric:: Unix Sockets
.. coroutinefunction:: open_unix_connection(path=None, *, limit=None, \ .. function:: open_unix_connection(path=None, *, limit=None, \
ssl=None, sock=None, server_hostname=None, \ ssl=None, sock=None, server_hostname=None, \
ssl_handshake_timeout=None, ssl_shutdown_timeout=None) ssl_handshake_timeout=None, ssl_shutdown_timeout=None)
:async:
Establish a Unix socket connection and return a pair of Establish a Unix socket connection and return a pair of
``(reader, writer)``. ``(reader, writer)``.
@ -165,10 +168,11 @@ and work with streams:
Added the *ssl_shutdown_timeout* parameter. Added the *ssl_shutdown_timeout* parameter.
.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \ .. function:: start_unix_server(client_connected_cb, path=None, \
*, limit=None, sock=None, backlog=100, ssl=None, \ *, limit=None, sock=None, backlog=100, ssl=None, \
ssl_handshake_timeout=None, \ ssl_handshake_timeout=None, \
ssl_shutdown_timeout=None, start_serving=True) ssl_shutdown_timeout=None, start_serving=True)
:async:
Start a Unix socket server. Start a Unix socket server.
@ -212,7 +216,8 @@ StreamReader
Acknowledge the EOF. Acknowledge the EOF.
.. coroutinemethod:: read(n=-1) .. method:: read(n=-1)
:async:
Read up to *n* bytes from the stream. Read up to *n* bytes from the stream.
@ -228,7 +233,8 @@ StreamReader
If EOF is received before any byte is read, return an empty If EOF is received before any byte is read, return an empty
``bytes`` object. ``bytes`` object.
.. coroutinemethod:: readline() .. method:: readline()
:async:
Read one line, where "line" is a sequence of bytes Read one line, where "line" is a sequence of bytes
ending with ``\n``. ending with ``\n``.
@ -239,7 +245,8 @@ StreamReader
If EOF is received and the internal buffer is empty, If EOF is received and the internal buffer is empty,
return an empty ``bytes`` object. return an empty ``bytes`` object.
.. coroutinemethod:: readexactly(n) .. method:: readexactly(n)
:async:
Read exactly *n* bytes. Read exactly *n* bytes.
@ -247,7 +254,8 @@ StreamReader
can be read. Use the :attr:`IncompleteReadError.partial` can be read. Use the :attr:`IncompleteReadError.partial`
attribute to get the partially read data. attribute to get the partially read data.
.. coroutinemethod:: readuntil(separator=b'\n') .. method:: readuntil(separator=b'\n')
:async:
Read data from the stream until *separator* is found. Read data from the stream until *separator* is found.
@ -347,7 +355,8 @@ StreamWriter
Access optional transport information; see Access optional transport information; see
:meth:`BaseTransport.get_extra_info` for details. :meth:`BaseTransport.get_extra_info` for details.
.. coroutinemethod:: drain() .. method:: drain()
:async:
Wait until it is appropriate to resume writing to the stream. Wait until it is appropriate to resume writing to the stream.
Example:: Example::
@ -362,8 +371,9 @@ StreamWriter
be resumed. When there is nothing to wait for, the :meth:`drain` be resumed. When there is nothing to wait for, the :meth:`drain`
returns immediately. returns immediately.
.. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ .. method:: start_tls(sslcontext, *, server_hostname=None, \
ssl_handshake_timeout=None, ssl_shutdown_timeout=None) ssl_handshake_timeout=None, ssl_shutdown_timeout=None)
:async:
Upgrade an existing stream-based connection to TLS. Upgrade an existing stream-based connection to TLS.
@ -395,7 +405,8 @@ StreamWriter
.. versionadded:: 3.7 .. versionadded:: 3.7
.. coroutinemethod:: wait_closed() .. method:: wait_closed()
:async:
Wait until the stream is closed. Wait until the stream is closed.

14
Doc/library/asyncio-subprocess.rst
View file

@ -61,8 +61,9 @@ See also the `Examples`_ subsection.
Creating Subprocesses Creating Subprocesses
===================== =====================
.. coroutinefunction:: create_subprocess_exec(program, *args, stdin=None, \ .. function:: create_subprocess_exec(program, *args, stdin=None, \
stdout=None, stderr=None, limit=None, **kwds) stdout=None, stderr=None, limit=None, **kwds)
:async:
Create a subprocess. Create a subprocess.
@ -79,8 +80,9 @@ Creating Subprocesses
Removed the *loop* parameter. Removed the *loop* parameter.
.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, \ .. function:: create_subprocess_shell(cmd, stdin=None, \
stdout=None, stderr=None, limit=None, **kwds) stdout=None, stderr=None, limit=None, **kwds)
:async:
Run the *cmd* shell command. Run the *cmd* shell command.
@ -188,7 +190,8 @@ their completion.
See also the :ref:`Subprocess and Threads <asyncio-subprocess-threads>` See also the :ref:`Subprocess and Threads <asyncio-subprocess-threads>`
section. section.
.. coroutinemethod:: wait() .. method:: wait()
:async:
Wait for the child process to terminate. Wait for the child process to terminate.
@ -202,7 +205,8 @@ their completion.
more data. Use the :meth:`communicate` method when using pipes more data. Use the :meth:`communicate` method when using pipes
to avoid this condition. to avoid this condition.
.. coroutinemethod:: communicate(input=None) .. method:: communicate(input=None)
:async:
Interact with process: Interact with process:
@ -232,7 +236,7 @@ their completion.
.. versionchanged:: 3.12 .. versionchanged:: 3.12
*stdin* gets closed when `input=None` too. *stdin* gets closed when ``input=None`` too.
.. method:: send_signal(signal) .. method:: send_signal(signal)

27
Doc/library/asyncio-sync.rst
View file

@ -67,7 +67,8 @@ Lock
.. versionchanged:: 3.10 .. versionchanged:: 3.10
Removed the *loop* parameter. Removed the *loop* parameter.
.. coroutinemethod:: acquire() .. method:: acquire()
:async:
Acquire the lock. Acquire the lock.
@ -137,7 +138,8 @@ Event
asyncio.run(main()) asyncio.run(main())
.. coroutinemethod:: wait() .. method:: wait()
:async:
Wait until the event is set. Wait until the event is set.
@ -207,7 +209,8 @@ Condition
finally: finally:
cond.release() cond.release()
.. coroutinemethod:: acquire() .. method:: acquire()
:async:
Acquire the underlying lock. Acquire the underlying lock.
@ -245,7 +248,8 @@ Condition
When invoked on an unlocked lock, a :exc:`RuntimeError` is When invoked on an unlocked lock, a :exc:`RuntimeError` is
raised. raised.
.. coroutinemethod:: wait() .. method:: wait()
:async:
Wait until notified. Wait until notified.
@ -262,7 +266,8 @@ Condition
and be prepared to :meth:`~Condition.wait` again. For this reason, you may and be prepared to :meth:`~Condition.wait` again. For this reason, you may
prefer to use :meth:`~Condition.wait_for` instead. prefer to use :meth:`~Condition.wait_for` instead.
.. coroutinemethod:: wait_for(predicate) .. method:: wait_for(predicate)
:async:
Wait until a predicate becomes *true*. Wait until a predicate becomes *true*.
@ -312,7 +317,8 @@ Semaphore
finally: finally:
sem.release() sem.release()
.. coroutinemethod:: acquire() .. method:: acquire()
:async:
Acquire a semaphore. Acquire a semaphore.
@ -400,7 +406,8 @@ Barrier
.. versionadded:: 3.11 .. versionadded:: 3.11
.. coroutinemethod:: wait() .. method:: wait()
:async:
Pass the barrier. When all the tasks party to the barrier have called Pass the barrier. When all the tasks party to the barrier have called
this function, they are all unblocked simultaneously. this function, they are all unblocked simultaneously.
@ -424,14 +431,16 @@ Barrier
barrier is broken or reset while a task is waiting. barrier is broken or reset while a task is waiting.
It could raise a :exc:`CancelledError` if a task is cancelled. It could raise a :exc:`CancelledError` if a task is cancelled.
.. coroutinemethod:: reset() .. method:: reset()
:async:
Return the barrier to the default, empty state. Any tasks waiting on it Return the barrier to the default, empty state. Any tasks waiting on it
will receive the :class:`BrokenBarrierError` exception. will receive the :class:`BrokenBarrierError` exception.
If a barrier is broken it may be better to just leave it and create a new one. If a barrier is broken it may be better to just leave it and create a new one.
.. coroutinemethod:: abort() .. method:: abort()
:async:
Put the barrier into a broken state. This causes any active or future Put the barrier into a broken state. This causes any active or future
calls to :meth:`~Barrier.wait` to fail with the :class:`BrokenBarrierError`. calls to :meth:`~Barrier.wait` to fail with the :class:`BrokenBarrierError`.

12
Doc/library/asyncio-task.rst
View file

@ -464,7 +464,8 @@ Expected output:
Sleeping Sleeping
======== ========
.. coroutinefunction:: sleep(delay, result=None) .. function:: sleep(delay, result=None)
:async:
Block for *delay* seconds. Block for *delay* seconds.
@ -819,7 +820,8 @@ Timeouts
.. versionadded:: 3.11 .. versionadded:: 3.11
.. coroutinefunction:: wait_for(aw, timeout) .. function:: wait_for(aw, timeout)
:async:
Wait for the *aw* :ref:`awaitable <asyncio-awaitables>` Wait for the *aw* :ref:`awaitable <asyncio-awaitables>`
to complete with a timeout. to complete with a timeout.
@ -879,7 +881,8 @@ Timeouts
Waiting Primitives Waiting Primitives
================== ==================
.. coroutinefunction:: wait(aws, *, timeout=None, return_when=ALL_COMPLETED) .. function:: wait(aws, *, timeout=None, return_when=ALL_COMPLETED)
:async:
Run :class:`~asyncio.Future` and :class:`~asyncio.Task` instances in the *aws* Run :class:`~asyncio.Future` and :class:`~asyncio.Task` instances in the *aws*
iterable concurrently and block until the condition specified iterable concurrently and block until the condition specified
@ -998,7 +1001,8 @@ Waiting Primitives
Running in Threads Running in Threads
================== ==================
.. coroutinefunction:: to_thread(func, /, *args, **kwargs) .. function:: to_thread(func, /, *args, **kwargs)
:async:
Asynchronously run function *func* in a separate thread. Asynchronously run function *func* in a separate thread.

6
Doc/library/contextlib.rst
View file

@ -629,7 +629,8 @@ Functions and classes provided:
The :meth:`~ExitStack.close` method is not implemented; :meth:`aclose` must be used The :meth:`~ExitStack.close` method is not implemented; :meth:`aclose` must be used
instead. instead.
.. coroutinemethod:: enter_async_context(cm) .. method:: enter_async_context(cm)
:async:
Similar to :meth:`ExitStack.enter_context` but expects an asynchronous context Similar to :meth:`ExitStack.enter_context` but expects an asynchronous context
manager. manager.
@ -647,7 +648,8 @@ Functions and classes provided:
Similar to :meth:`ExitStack.callback` but expects a coroutine function. Similar to :meth:`ExitStack.callback` but expects a coroutine function.
.. coroutinemethod:: aclose() .. method:: aclose()
:async:
Similar to :meth:`ExitStack.close` but properly handles awaitables. Similar to :meth:`ExitStack.close` but properly handles awaitables.

9
Doc/library/unittest.rst
View file

@ -1579,7 +1579,8 @@ Test cases
.. versionadded:: 3.13 .. versionadded:: 3.13
.. coroutinemethod:: asyncSetUp() .. method:: asyncSetUp()
:async:
Method called to prepare the test fixture. This is called after :meth:`setUp`. Method called to prepare the test fixture. This is called after :meth:`setUp`.
This is called immediately before calling the test method; other than This is called immediately before calling the test method; other than
@ -1587,7 +1588,8 @@ Test cases
will be considered an error rather than a test failure. The default implementation will be considered an error rather than a test failure. The default implementation
does nothing. does nothing.
.. coroutinemethod:: asyncTearDown() .. method:: asyncTearDown()
:async:
Method called immediately after the test method has been called and the Method called immediately after the test method has been called and the
result recorded. This is called before :meth:`tearDown`. This is called even if result recorded. This is called before :meth:`tearDown`. This is called even if
@ -1603,7 +1605,8 @@ Test cases
This method accepts a coroutine that can be used as a cleanup function. This method accepts a coroutine that can be used as a cleanup function.
.. coroutinemethod:: enterAsyncContext(cm) .. method:: enterAsyncContext(cm)
:async:
Enter the supplied :term:`asynchronous context manager`. If successful, Enter the supplied :term:`asynchronous context manager`. If successful,
also add its :meth:`~object.__aexit__` method as a cleanup function by also add its :meth:`~object.__aexit__` method as a cleanup function by

12
Doc/reference/expressions.rst
View file

@ -752,7 +752,8 @@ which are used to control the execution of a generator function.
.. index:: pair: exception; StopAsyncIteration .. index:: pair: exception; StopAsyncIteration
.. coroutinemethod:: agen.__anext__() .. method:: agen.__anext__()
:async:
Returns an awaitable which when run starts to execute the asynchronous Returns an awaitable which when run starts to execute the asynchronous
generator or resumes it at the last executed yield expression. When an generator or resumes it at the last executed yield expression. When an
@ -769,7 +770,8 @@ which are used to control the execution of a generator function.
This method is normally called implicitly by a :keyword:`async for` loop. This method is normally called implicitly by a :keyword:`async for` loop.
.. coroutinemethod:: agen.asend(value) .. method:: agen.asend(value)
:async:
Returns an awaitable which when run resumes the execution of the Returns an awaitable which when run resumes the execution of the
asynchronous generator. As with the :meth:`~generator.send` method for a asynchronous generator. As with the :meth:`~generator.send` method for a
@ -784,8 +786,9 @@ which are used to control the execution of a generator function.
because there is no yield expression that could receive the value. because there is no yield expression that could receive the value.
.. coroutinemethod:: agen.athrow(value) .. method:: agen.athrow(value)
agen.athrow(type[, value[, traceback]]) agen.athrow(type[, value[, traceback]])
:async:
Returns an awaitable that raises an exception of type ``type`` at the point Returns an awaitable that raises an exception of type ``type`` at the point
where the asynchronous generator was paused, and returns the next value where the asynchronous generator was paused, and returns the next value
@ -805,7 +808,8 @@ which are used to control the execution of a generator function.
.. index:: pair: exception; GeneratorExit .. index:: pair: exception; GeneratorExit
.. coroutinemethod:: agen.aclose() .. method:: agen.aclose()
:async:
Returns an awaitable that when run will throw a :exc:`GeneratorExit` into Returns an awaitable that when run will throw a :exc:`GeneratorExit` into
the asynchronous generator function at the point where it was paused. the asynchronous generator function at the point where it was paused.

21
Doc/tools/extensions/pyspecific.py
View file

@ -71,13 +71,6 @@ def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
return [refnode], [] return [refnode], []
class PyCoroutineMixin(object):
def handle_signature(self, sig, signode):
ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
return ret
class PyAwaitableMixin(object): class PyAwaitableMixin(object):
def handle_signature(self, sig, signode): def handle_signature(self, sig, signode):
ret = super(PyAwaitableMixin, self).handle_signature(sig, signode) ret = super(PyAwaitableMixin, self).handle_signature(sig, signode)
@ -85,18 +78,6 @@ class PyAwaitableMixin(object):
return ret return ret
class PyCoroutineFunction(PyCoroutineMixin, PyFunction):
def run(self):
self.name = 'py:function'
return PyFunction.run(self)
class PyCoroutineMethod(PyCoroutineMixin, PyMethod):
def run(self):
self.name = 'py:method'
return PyMethod.run(self)
class PyAwaitableFunction(PyAwaitableMixin, PyFunction): class PyAwaitableFunction(PyAwaitableMixin, PyFunction):
def run(self): def run(self):
self.name = 'py:function' self.name = 'py:function'
@ -254,8 +235,6 @@ def setup(app):
app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature) app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command) app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command)
app.add_object_type('monitoring-event', 'monitoring-event', '%s (monitoring event)', parse_monitoring_event) app.add_object_type('monitoring-event', 'monitoring-event', '%s (monitoring event)', parse_monitoring_event)
app.add_directive_to_domain('py', 'coroutinefunction', PyCoroutineFunction)
app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction) app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod) app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
app.connect('env-check-consistency', patch_pairindextypes) app.connect('env-check-consistency', patch_pairindextypes)