From 48cb5b55e58076d17774f8c956c9d28e125666e8 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sat, 22 Feb 2025 20:54:43 +0300 Subject: [PATCH 1/3] gh-121970: Replace `.. coroutine{method,function}` with `:async:` (#130448) Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com> gh-130461: Fix locations of `.. index::` directives usage in `Doc/library/uuid.rst` gh-130461: Fix locations of `.. index::` in `getnode()` --- Doc/library/asyncio-eventloop.rst | 162 +++++++++++++++++------------ Doc/library/asyncio-queue.rst | 9 +- Doc/library/asyncio-stream.rst | 69 ++++++------ Doc/library/asyncio-subprocess.rst | 18 ++-- Doc/library/asyncio-sync.rst | 27 +++-- Doc/library/asyncio-task.rst | 12 ++- Doc/library/contextlib.rst | 6 +- Doc/library/unittest.rst | 9 +- Doc/library/uuid.rst | 18 ++-- Doc/reference/expressions.rst | 14 ++- Doc/tools/extensions/pyspecific.py | 21 ---- 11 files changed, 203 insertions(+), 162 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 15ef33e195904d..fdb75fe9e63a88 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/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() `. @@ -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() ` 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() `. @@ -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() `. @@ -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() `. -.. coroutinemethod:: loop.sock_accept(sock) +.. method:: loop.sock_accept(sock) + :async: Accept a connection. Modeled after the blocking :meth:`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. diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index 066edd424d150e..d99213aa81d53e 100644 --- a/Doc/library/asyncio-queue.rst +++ b/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. diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 48f2890c5eef8c..c56166cabb9093 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -48,12 +48,13 @@ The following top-level asyncio functions can be used to create and work with streams: -.. coroutinefunction:: open_connection(host=None, port=None, *, \ - limit=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) +.. function:: open_connection(host=None, port=None, *, \ + limit=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) + :async: Establish a network connection and return a pair of ``(reader, writer)`` objects. @@ -87,14 +88,15 @@ and work with streams: Added the *ssl_shutdown_timeout* parameter. -.. coroutinefunction:: start_server(client_connected_cb, host=None, \ - port=None, *, limit=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) +.. function:: start_server(client_connected_cb, host=None, \ + port=None, *, limit=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: Start a socket server. @@ -135,9 +137,10 @@ and work with streams: .. rubric:: Unix Sockets -.. coroutinefunction:: open_unix_connection(path=None, *, limit=None, \ - ssl=None, sock=None, server_hostname=None, \ - ssl_handshake_timeout=None, ssl_shutdown_timeout=None) +.. function:: open_unix_connection(path=None, *, limit=None, \ + ssl=None, sock=None, server_hostname=None, \ + ssl_handshake_timeout=None, ssl_shutdown_timeout=None) + :async: Establish a Unix socket connection and return a pair of ``(reader, writer)``. @@ -165,10 +168,11 @@ and work with streams: Added the *ssl_shutdown_timeout* parameter. -.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \ - *, limit=None, sock=None, backlog=100, ssl=None, \ - ssl_handshake_timeout=None, \ - ssl_shutdown_timeout=None, start_serving=True) +.. function:: start_unix_server(client_connected_cb, path=None, \ + *, limit=None, sock=None, backlog=100, ssl=None, \ + ssl_handshake_timeout=None, \ + ssl_shutdown_timeout=None, start_serving=True) + :async: Start a Unix socket server. @@ -212,7 +216,8 @@ StreamReader Acknowledge the EOF. - .. coroutinemethod:: read(n=-1) + .. method:: read(n=-1) + :async: 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 ``bytes`` object. - .. coroutinemethod:: readline() + .. method:: readline() + :async: Read one line, where "line" is a sequence of bytes ending with ``\n``. @@ -239,7 +245,8 @@ StreamReader If EOF is received and the internal buffer is empty, return an empty ``bytes`` object. - .. coroutinemethod:: readexactly(n) + .. method:: readexactly(n) + :async: Read exactly *n* bytes. @@ -247,7 +254,8 @@ StreamReader can be read. Use the :attr:`IncompleteReadError.partial` 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. @@ -347,7 +355,8 @@ StreamWriter Access optional transport information; see :meth:`BaseTransport.get_extra_info` for details. - .. coroutinemethod:: drain() + .. method:: drain() + :async: Wait until it is appropriate to resume writing to the stream. Example:: @@ -362,8 +371,9 @@ StreamWriter be resumed. When there is nothing to wait for, the :meth:`drain` returns immediately. - .. coroutinemethod:: start_tls(sslcontext, *, server_hostname=None, \ - ssl_handshake_timeout=None, ssl_shutdown_timeout=None) + .. method:: start_tls(sslcontext, *, server_hostname=None, \ + ssl_handshake_timeout=None, ssl_shutdown_timeout=None) + :async: Upgrade an existing stream-based connection to TLS. @@ -395,7 +405,8 @@ StreamWriter .. versionadded:: 3.7 - .. coroutinemethod:: wait_closed() + .. method:: wait_closed() + :async: Wait until the stream is closed. diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index b477a7fa2d37ef..3e543a45e6525f 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -61,8 +61,9 @@ See also the `Examples`_ subsection. Creating Subprocesses ===================== -.. coroutinefunction:: create_subprocess_exec(program, *args, stdin=None, \ - stdout=None, stderr=None, limit=None, **kwds) +.. function:: create_subprocess_exec(program, *args, stdin=None, \ + stdout=None, stderr=None, limit=None, **kwds) + :async: Create a subprocess. @@ -79,8 +80,9 @@ Creating Subprocesses Removed the *loop* parameter. -.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, \ - stdout=None, stderr=None, limit=None, **kwds) +.. function:: create_subprocess_shell(cmd, stdin=None, \ + stdout=None, stderr=None, limit=None, **kwds) + :async: Run the *cmd* shell command. @@ -188,7 +190,8 @@ their completion. See also the :ref:`Subprocess and Threads ` section. - .. coroutinemethod:: wait() + .. method:: wait() + :async: Wait for the child process to terminate. @@ -202,7 +205,8 @@ their completion. more data. Use the :meth:`communicate` method when using pipes to avoid this condition. - .. coroutinemethod:: communicate(input=None) + .. method:: communicate(input=None) + :async: Interact with process: @@ -232,7 +236,7 @@ their completion. .. versionchanged:: 3.12 - *stdin* gets closed when `input=None` too. + *stdin* gets closed when ``input=None`` too. .. method:: send_signal(signal) diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index 77c2e97da11990..968c812ee3c8e6 100644 --- a/Doc/library/asyncio-sync.rst +++ b/Doc/library/asyncio-sync.rst @@ -67,7 +67,8 @@ Lock .. versionchanged:: 3.10 Removed the *loop* parameter. - .. coroutinemethod:: acquire() + .. method:: acquire() + :async: Acquire the lock. @@ -137,7 +138,8 @@ Event asyncio.run(main()) - .. coroutinemethod:: wait() + .. method:: wait() + :async: Wait until the event is set. @@ -207,7 +209,8 @@ Condition finally: cond.release() - .. coroutinemethod:: acquire() + .. method:: acquire() + :async: Acquire the underlying lock. @@ -245,7 +248,8 @@ Condition When invoked on an unlocked lock, a :exc:`RuntimeError` is raised. - .. coroutinemethod:: wait() + .. method:: wait() + :async: Wait until notified. @@ -262,7 +266,8 @@ Condition and be prepared to :meth:`~Condition.wait` again. For this reason, you may prefer to use :meth:`~Condition.wait_for` instead. - .. coroutinemethod:: wait_for(predicate) + .. method:: wait_for(predicate) + :async: Wait until a predicate becomes *true*. @@ -312,7 +317,8 @@ Semaphore finally: sem.release() - .. coroutinemethod:: acquire() + .. method:: acquire() + :async: Acquire a semaphore. @@ -400,7 +406,8 @@ Barrier .. versionadded:: 3.11 - .. coroutinemethod:: wait() + .. method:: wait() + :async: Pass the barrier. When all the tasks party to the barrier have called this function, they are all unblocked simultaneously. @@ -424,14 +431,16 @@ Barrier barrier is broken or reset while a task is waiting. 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 will receive the :class:`BrokenBarrierError` exception. 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 calls to :meth:`~Barrier.wait` to fail with the :class:`BrokenBarrierError`. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 4541cf28de0605..b6ae443860843b 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -464,7 +464,8 @@ Expected output: Sleeping ======== -.. coroutinefunction:: sleep(delay, result=None) +.. function:: sleep(delay, result=None) + :async: Block for *delay* seconds. @@ -819,7 +820,8 @@ Timeouts .. versionadded:: 3.11 -.. coroutinefunction:: wait_for(aw, timeout) +.. function:: wait_for(aw, timeout) + :async: Wait for the *aw* :ref:`awaitable ` to complete with a timeout. @@ -879,7 +881,8 @@ Timeouts 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* iterable concurrently and block until the condition specified @@ -998,7 +1001,8 @@ Waiting Primitives Running in Threads ================== -.. coroutinefunction:: to_thread(func, /, *args, **kwargs) +.. function:: to_thread(func, /, *args, **kwargs) + :async: Asynchronously run function *func* in a separate thread. diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index e8f264f949807d..9fb80c0cb4e30d 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -629,7 +629,8 @@ Functions and classes provided: The :meth:`~ExitStack.close` method is not implemented; :meth:`aclose` must be used instead. - .. coroutinemethod:: enter_async_context(cm) + .. method:: enter_async_context(cm) + :async: Similar to :meth:`ExitStack.enter_context` but expects an asynchronous context manager. @@ -647,7 +648,8 @@ Functions and classes provided: Similar to :meth:`ExitStack.callback` but expects a coroutine function. - .. coroutinemethod:: aclose() + .. method:: aclose() + :async: Similar to :meth:`ExitStack.close` but properly handles awaitables. diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 5bb7f88d585e3b..61022fe052ca80 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1635,7 +1635,8 @@ Test cases .. versionadded:: 3.13 - .. coroutinemethod:: asyncSetUp() + .. method:: asyncSetUp() + :async: Method called to prepare the test fixture. This is called after :meth:`setUp`. This is called immediately before calling the test method; other than @@ -1643,7 +1644,8 @@ Test cases will be considered an error rather than a test failure. The default implementation does nothing. - .. coroutinemethod:: asyncTearDown() + .. method:: asyncTearDown() + :async: 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 @@ -1659,7 +1661,8 @@ Test cases 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, also add its :meth:`~object.__aexit__` method as a cleanup function by diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst index bff6b9dcdc57ca..a5ce6ad6845a03 100644 --- a/Doc/library/uuid.rst +++ b/Doc/library/uuid.rst @@ -167,6 +167,7 @@ which relays any information about the UUID's safety, using this enumeration: The :mod:`uuid` module defines the following functions: +.. index:: single: getnode .. function:: getnode() Get the hardware address as a 48-bit positive integer. The first time this @@ -184,9 +185,8 @@ The :mod:`uuid` module defines the following functions: administered MAC addresses, since the former are guaranteed to be globally unique, while the latter are not. -.. index:: single: getnode - +.. index:: single: uuid1 .. function:: uuid1(node=None, clock_seq=None) Generate a UUID from a host ID, sequence number, and the current time. If *node* @@ -194,34 +194,30 @@ The :mod:`uuid` module defines the following functions: *clock_seq* is given, it is used as the sequence number; otherwise a random 14-bit sequence number is chosen. -.. index:: single: uuid1 - +.. index:: single: uuid3 .. function:: uuid3(namespace, name) Generate a UUID based on the MD5 hash of a namespace identifier (which is a UUID) and a name (which is a :class:`bytes` object or a string that will be encoded using UTF-8). -.. index:: single: uuid3 - +.. index:: single: uuid4 .. function:: uuid4() Generate a random UUID. -.. index:: single: uuid4 - +.. index:: single: uuid5 .. function:: uuid5(namespace, name) Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a UUID) and a name (which is a :class:`bytes` object or a string that will be encoded using UTF-8). -.. index:: single: uuid5 - +.. index:: single: uuid8 .. function:: uuid8(a=None, b=None, c=None) Generate a pseudo-random UUID according to @@ -235,8 +231,6 @@ The :mod:`uuid` module defines the following functions: .. versionadded:: 3.14 -.. index:: single: uuid8 - The :mod:`uuid` module defines the following namespace identifiers for use with :func:`uuid3` or :func:`uuid5`. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 7c95b207b1aed2..8837344e5ddca1 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -751,7 +751,8 @@ which are used to control the execution of a generator function. .. index:: pair: exception; StopAsyncIteration -.. coroutinemethod:: agen.__anext__() +.. method:: agen.__anext__() + :async: Returns an awaitable which when run starts to execute the asynchronous generator or resumes it at the last executed yield expression. When an @@ -768,7 +769,8 @@ which are used to control the execution of a generator function. 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 asynchronous generator. As with the :meth:`~generator.send` method for a @@ -783,8 +785,9 @@ which are used to control the execution of a generator function. because there is no yield expression that could receive the value. -.. coroutinemethod:: agen.athrow(value) - agen.athrow(type[, value[, traceback]]) +.. method:: agen.athrow(value) + agen.athrow(type[, value[, traceback]]) + :async: Returns an awaitable that raises an exception of type ``type`` at the point where the asynchronous generator was paused, and returns the next value @@ -804,7 +807,8 @@ which are used to control the execution of a generator function. .. index:: pair: exception; GeneratorExit -.. coroutinemethod:: agen.aclose() +.. method:: agen.aclose() + :async: Returns an awaitable that when run will throw a :exc:`GeneratorExit` into the asynchronous generator function at the point where it was paused. diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 26241a001e7cc2..68247d40f682d1 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -65,13 +65,6 @@ def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): 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): def handle_signature(self, sig, signode): ret = super(PyAwaitableMixin, self).handle_signature(sig, signode) @@ -79,18 +72,6 @@ def handle_signature(self, sig, signode): 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): def run(self): self.name = 'py:function' @@ -184,8 +165,6 @@ def setup(app): 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('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', 'awaitablemethod', PyAwaitableMethod) app.connect('env-check-consistency', patch_pairindextypes) From 69ae854ffc19c0337c5678b76b75445192394e9c Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Tue, 25 Feb 2025 03:42:05 +0530 Subject: [PATCH 2/3] gh-130461: Remove unnecessary usages of .. index:: directives in Doc/library/uuid.rst --- Doc/library/uuid.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst index a5ce6ad6845a03..c661fa2e52565c 100644 --- a/Doc/library/uuid.rst +++ b/Doc/library/uuid.rst @@ -167,7 +167,6 @@ which relays any information about the UUID's safety, using this enumeration: The :mod:`uuid` module defines the following functions: -.. index:: single: getnode .. function:: getnode() Get the hardware address as a 48-bit positive integer. The first time this @@ -186,7 +185,6 @@ The :mod:`uuid` module defines the following functions: globally unique, while the latter are not. -.. index:: single: uuid1 .. function:: uuid1(node=None, clock_seq=None) Generate a UUID from a host ID, sequence number, and the current time. If *node* @@ -195,7 +193,6 @@ The :mod:`uuid` module defines the following functions: 14-bit sequence number is chosen. -.. index:: single: uuid3 .. function:: uuid3(namespace, name) Generate a UUID based on the MD5 hash of a namespace identifier (which is a @@ -203,13 +200,11 @@ The :mod:`uuid` module defines the following functions: that will be encoded using UTF-8). -.. index:: single: uuid4 .. function:: uuid4() Generate a random UUID. -.. index:: single: uuid5 .. function:: uuid5(namespace, name) Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a @@ -217,7 +212,6 @@ The :mod:`uuid` module defines the following functions: that will be encoded using UTF-8). -.. index:: single: uuid8 .. function:: uuid8(a=None, b=None, c=None) Generate a pseudo-random UUID according to From 36daa795b93bee1bbedd40b267ffce57f170a4e7 Mon Sep 17 00:00:00 2001 From: Kanishk Pachauri Date: Tue, 25 Feb 2025 04:07:30 +0530 Subject: [PATCH 3/3] chore: add NEWS entry for the change --- .../Library/2025-02-25-03-53-00.gh-issue-130461.asr2dg.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/Library/2025-02-25-03-53-00.gh-issue-130461.asr2dg.rst diff --git a/Misc/NEWS.d/next/Library/2025-02-25-03-53-00.gh-issue-130461.asr2dg.rst b/Misc/NEWS.d/next/Library/2025-02-25-03-53-00.gh-issue-130461.asr2dg.rst new file mode 100644 index 00000000000000..a1004b5ccc20da --- /dev/null +++ b/Misc/NEWS.d/next/Library/2025-02-25-03-53-00.gh-issue-130461.asr2dg.rst @@ -0,0 +1,3 @@ +* Removed ``.. index::`` directives from uuid module documentation. +* These directives previously created entries in the general index for functions like ``getnode``, ``uuid1``, ``uuid3``, ``uuid4``, ``uuid5``, and ``uuid8``. +* This change affects the intersphinx inventory. (GH-130461)