From 081cc42a739bb40e5af98eed999370582480d38f Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sat, 22 Feb 2025 11:09:38 +0300 Subject: [PATCH 1/3] gh-121970: Replace `.. coroutine{method,function}` with `:async:` --- Doc/library/asyncio-eventloop.rst | 83 ++++++++++++++++++++---------- Doc/library/asyncio-queue.rst | 9 ++-- Doc/library/asyncio-stream.rst | 33 ++++++++---- Doc/library/asyncio-subprocess.rst | 12 +++-- Doc/library/asyncio-sync.rst | 27 ++++++---- Doc/library/asyncio-task.rst | 12 +++-- Doc/library/contextlib.rst | 6 ++- Doc/library/unittest.rst | 9 ++-- Doc/reference/expressions.rst | 12 +++-- Doc/tools/extensions/pyspecific.py | 21 -------- 10 files changed, 135 insertions(+), 89 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 15ef33e195904d..c8f08cb901b68b 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,7 +406,7 @@ Creating Futures and Tasks Opening network connections ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. coroutinemethod:: loop.create_connection(protocol_factory, \ +.. 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, \ @@ -412,6 +414,7 @@ Opening network connections 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,7 +560,7 @@ 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, \ +.. method:: loop.create_datagram_endpoint(protocol_factory, \ local_addr=None, remote_addr=None, *, \ family=0, proto=0, flags=0, \ reuse_port=None, \ @@ -642,10 +645,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, \ +.. 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,7 +682,7 @@ 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, \ @@ -688,6 +692,7 @@ Creating network servers 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 +800,12 @@ Creating network servers 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, \ 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 +838,10 @@ Creating network servers 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, \ ssl_shutdown_timeout=None) + :async: Wrap an already accepted connection into a transport/protocol pair. @@ -882,8 +889,9 @@ Creating network servers Transferring files ^^^^^^^^^^^^^^^^^^ -.. coroutinemethod:: loop.sendfile(transport, file, \ +.. 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 +920,11 @@ Transferring files TLS Upgrade ^^^^^^^^^^^ -.. coroutinemethod:: loop.start_tls(transport, protocol, \ +.. 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 +1018,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 +1033,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 +1045,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 +1057,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 +1070,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 +1089,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 +1102,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 +1124,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 +1147,9 @@ convenient. :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) + :async: Send a file using high-performance :mod:`os.sendfile` if possible. Return the total number of bytes sent. @@ -1165,12 +1183,14 @@ convenient. DNS ^^^ -.. coroutinemethod:: loop.getaddrinfo(host, port, *, family=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 +1212,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 +1229,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 +1502,10 @@ async/await code consider using the high-level .. _loop_subprocess_exec: -.. coroutinemethod:: loop.subprocess_exec(protocol_factory, *args, \ +.. 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 +1585,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, *, \ +.. 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 +1733,8 @@ Do not instantiate the :class:`Server` class directly. .. versionadded:: 3.7 - .. coroutinemethod:: start_serving() + .. method:: start_serving() + :async: Start accepting connections. @@ -1725,7 +1750,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 +1783,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..061a2516bedfa6 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, *, \ +.. 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,7 +88,7 @@ and work with streams: 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, \ family=socket.AF_UNSPEC, \ flags=socket.AI_PASSIVE, sock=None, \ @@ -95,6 +96,7 @@ and work with streams: 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, \ +.. 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, \ +.. 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, \ + .. 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..8bc0b414e8da6e 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, \ +.. 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, \ +.. 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: 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/reference/expressions.rst b/Doc/reference/expressions.rst index 7c95b207b1aed2..a4e2591ac9c08c 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) +.. 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 ada3eefb1f3698caa4ff84cc896d5397d1ff9352 Mon Sep 17 00:00:00 2001 From: sobolevn Date: Sat, 22 Feb 2025 11:15:33 +0300 Subject: [PATCH 2/3] Fix lint --- Doc/library/asyncio-subprocess.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 8bc0b414e8da6e..0473b7a602a8d8 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -236,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) From d3efa3cdcf799516303a0c03c4042826894b513e Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sat, 22 Feb 2025 17:47:39 +0000 Subject: [PATCH 3/3] Fix problems --- Doc/library/asyncio-eventloop.rst | 79 +++++++++++++++--------------- Doc/library/asyncio-stream.rst | 36 +++++++------- Doc/library/asyncio-subprocess.rst | 4 +- Doc/reference/expressions.rst | 2 +- 4 files changed, 61 insertions(+), 60 deletions(-) diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index c8f08cb901b68b..fdb75fe9e63a88 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -407,13 +407,13 @@ Opening network connections ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. 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) + 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 @@ -561,10 +561,11 @@ Opening network connections that can be used directly in async/await code. .. 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) + 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. @@ -646,9 +647,9 @@ Opening network connections 3.7.6 and 3.6.10, has been entirely removed. .. method:: loop.create_unix_connection(protocol_factory, \ - path=None, *, ssl=None, sock=None, \ - server_hostname=None, ssl_handshake_timeout=None, \ - ssl_shutdown_timeout=None) + path=None, *, ssl=None, sock=None, \ + server_hostname=None, ssl_handshake_timeout=None, \ + ssl_shutdown_timeout=None) :async: Create a Unix connection. @@ -683,15 +684,15 @@ Creating network servers .. _loop_create_server: .. 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) + 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 @@ -801,10 +802,10 @@ Creating network servers .. 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) + *, 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 @@ -839,8 +840,8 @@ Creating network servers .. method:: loop.connect_accepted_socket(protocol_factory, \ - sock, *, ssl=None, ssl_handshake_timeout=None, \ - ssl_shutdown_timeout=None) + sock, *, ssl=None, ssl_handshake_timeout=None, \ + ssl_shutdown_timeout=None) :async: Wrap an already accepted connection into a transport/protocol pair. @@ -890,7 +891,7 @@ Transferring files ^^^^^^^^^^^^^^^^^^ .. 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 @@ -921,9 +922,9 @@ TLS Upgrade ^^^^^^^^^^^ .. method:: loop.start_tls(transport, protocol, \ - sslcontext, *, server_side=False, \ - server_hostname=None, ssl_handshake_timeout=None, \ - ssl_shutdown_timeout=None) + sslcontext, *, server_side=False, \ + server_hostname=None, ssl_handshake_timeout=None, \ + ssl_shutdown_timeout=None) :async: Upgrade an existing transport-based connection to TLS. @@ -1148,7 +1149,7 @@ convenient. :meth:`loop.create_server` and :func:`start_server`. .. 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. @@ -1184,7 +1185,7 @@ DNS ^^^ .. 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`. @@ -1503,8 +1504,8 @@ async/await code consider using the high-level .. _loop_subprocess_exec: .. method:: loop.subprocess_exec(protocol_factory, *args, \ - stdin=subprocess.PIPE, stdout=subprocess.PIPE, \ - stderr=subprocess.PIPE, **kwargs) + stdin=subprocess.PIPE, stdout=subprocess.PIPE, \ + stderr=subprocess.PIPE, **kwargs) :async: Create a subprocess from one or more string arguments specified by @@ -1586,8 +1587,8 @@ async/await code consider using the high-level *protocol* is an object instantiated by the *protocol_factory*. .. method:: loop.subprocess_shell(protocol_factory, cmd, *, \ - stdin=subprocess.PIPE, stdout=subprocess.PIPE, \ - stderr=subprocess.PIPE, **kwargs) + stdin=subprocess.PIPE, stdout=subprocess.PIPE, \ + stderr=subprocess.PIPE, **kwargs) :async: Create a subprocess from *cmd*, which can be a :class:`str` or a diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 061a2516bedfa6..c56166cabb9093 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -49,11 +49,11 @@ and work with streams: .. 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) + 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 @@ -89,13 +89,13 @@ and work with streams: .. 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) + 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. @@ -138,8 +138,8 @@ and work with streams: .. rubric:: Unix Sockets .. function:: open_unix_connection(path=None, *, limit=None, \ - ssl=None, sock=None, server_hostname=None, \ - ssl_handshake_timeout=None, ssl_shutdown_timeout=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 @@ -169,9 +169,9 @@ and work with streams: .. 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) + *, 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. @@ -372,7 +372,7 @@ StreamWriter returns immediately. .. 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. diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 0473b7a602a8d8..3e543a45e6525f 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -62,7 +62,7 @@ Creating Subprocesses ===================== .. 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. @@ -81,7 +81,7 @@ Creating Subprocesses .. 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. diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index a4e2591ac9c08c..8837344e5ddca1 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -786,7 +786,7 @@ which are used to control the execution of a generator function. .. 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