From fc22f58b1940fd401873275e0a024bfe469386e9 Mon Sep 17 00:00:00 2001 From: Jonathan Dung Date: Fri, 8 May 2026 09:08:31 +0800 Subject: [PATCH 1/5] Fix grammatical errors in asyncio-dev.rst --- Doc/library/asyncio-dev.rst | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst index 713b40d746680a..2039cf5a982d5b 100644 --- a/Doc/library/asyncio-dev.rst +++ b/Doc/library/asyncio-dev.rst @@ -19,7 +19,7 @@ Debug Mode ========== By default asyncio runs in production mode. In order to ease -the development asyncio has a *debug mode*. +development, asyncio has a *debug mode*. There are several ways to enable asyncio debug mode: @@ -31,11 +31,11 @@ There are several ways to enable asyncio debug mode: * Calling :meth:`loop.set_debug`. -In addition to enabling the debug mode, consider also: +In addition to enabling debug mode, consider also: * setting the log level of the :ref:`asyncio logger ` to - :py:const:`logging.DEBUG`, for example the following snippet of code - can be run at startup of the application:: + :py:const:`logging.DEBUG`, such as by running the following snippet of + code at startup of the application:: logging.basicConfig(level=logging.DEBUG) @@ -44,7 +44,7 @@ In addition to enabling the debug mode, consider also: using the :option:`-W` ``default`` command line option. -When the debug mode is enabled: +When debug mode is enabled: * Many non-threadsafe asyncio APIs (such as :meth:`loop.call_soon` and :meth:`loop.call_at` methods) raise an exception if they are called @@ -95,7 +95,7 @@ To schedule a coroutine object from a different OS thread, the # Wait for the result: result = future.result() -To handle signals the event loop must be +To handle signals, the event loop must be run in the main thread. The :meth:`loop.run_in_executor` method can be used with a @@ -126,10 +126,9 @@ all concurrent asyncio Tasks and IO operations would be delayed by 1 second. An executor can be used to run a task in a different thread, -including in a different interpreter, or even in -a different process to avoid blocking the OS thread with the -event loop. See the :meth:`loop.run_in_executor` method for more -details. +a different interpreter, or even a different process to avoid +blocking the OS thread with the event loop. See the +:meth:`loop.run_in_executor` method for more details. .. _asyncio-logger: @@ -260,13 +259,12 @@ This section outlines essential best practices that can save you hours of debugg Close asynchronous generators explicitly ---------------------------------------- -It is recommended to manually close the +It is recommended to manually close an :term:`asynchronous generator `. If a generator exits early - for example, due to an exception raised in the body of an ``async for`` loop - its asynchronous cleanup code may run in an unexpected context. This can occur after the tasks it depends on have completed, -or during the event loop shutdown when the async-generator's garbage collection -hook is called. +or during the event loop shutdown when the its garbage collection hook is called. To avoid this, explicitly close the generator by calling its :meth:`~agen.aclose` method, or use the :func:`contextlib.aclosing` @@ -423,8 +421,7 @@ Avoid concurrent iteration and closure of the same generator Async generators may be reentered while another :meth:`~agen.__anext__` / :meth:`~agen.athrow` / :meth:`~agen.aclose` call is in -progress. This may lead to an inconsistent state of the async generator and can -cause errors. +progress. This may lead to inconsistent state and can cause errors. Let's consider the following example:: From 02a6c0f4bb2abe91fb1810f0509b4f53dc7497ca Mon Sep 17 00:00:00 2001 From: Jonathan Dung Date: Fri, 8 May 2026 09:17:05 +0800 Subject: [PATCH 2/5] commit 2 --- Doc/library/asyncio-queue.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index a9735ae80652df..5cab069950bb8a 100644 --- a/Doc/library/asyncio-queue.rst +++ b/Doc/library/asyncio-queue.rst @@ -15,8 +15,8 @@ asyncio queues are designed to be similar to classes of the they are designed to be used specifically in async/await code. Note that methods of asyncio queues don't have a *timeout* parameter; -use :func:`asyncio.wait_for` function to do queue operations with a -timeout. +use :func:`asyncio.wait_for` function to perform queue operations with a +timeouts. See also the `Examples`_ section below. @@ -55,7 +55,8 @@ Queue Return ``True`` if there are :attr:`maxsize` items in the queue. If the queue was initialized with ``maxsize=0`` (the default), - then :meth:`full` never returns ``True``. + or a negative :attr:`maxsize:, then :meth:`full` never returns + ``True``. .. method:: get() :async: @@ -109,7 +110,7 @@ Queue Currently blocked callers of :meth:`~Queue.put` will be unblocked and will raise :exc:`QueueShutDown` in the formerly awaiting task. - If *immediate* is false (the default), the queue can be wound + If *immediate* is ``False`` (the default), the queue can be wound down normally with :meth:`~Queue.get` calls to extract tasks that have already been loaded. @@ -119,17 +120,17 @@ Queue Once the queue is empty, future calls to :meth:`~Queue.get` will raise :exc:`QueueShutDown`. - If *immediate* is true, the queue is terminated immediately. + If *immediate* is ``True``, the queue is terminated immediately. The queue is drained to be completely empty and the count of unfinished tasks is reduced by the number of tasks drained. - If unfinished tasks is zero, callers of :meth:`~Queue.join` - are unblocked. Also, blocked callers of :meth:`~Queue.get` - are unblocked and will raise :exc:`QueueShutDown` because the + If the count reaches zero, callers of :meth:`~Queue.join` are + unblocked. Also, blocked callers of :meth:`~Queue.get` are + unblocked and will raise :exc:`QueueShutDown` because the queue is empty. - Use caution when using :meth:`~Queue.join` with *immediate* set - to true. This unblocks the join even when no work has been done - on the tasks, violating the usual invariant for joining a queue. + Exercise caution when using :meth:`~Queue.join` in the above case. + The join may be unblocked even when no work has been done on the + tasks, violating the usual invariant for joining a queue. .. versionadded:: 3.13 From 3b359ff6ea8f1e368490eae801d324291c0da62b Mon Sep 17 00:00:00 2001 From: Jonathan Dung Date: Fri, 8 May 2026 09:29:34 +0800 Subject: [PATCH 3/5] commit 3 --- Doc/library/asyncio-queue.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index 5cab069950bb8a..b1c0ef17b0d1bc 100644 --- a/Doc/library/asyncio-queue.rst +++ b/Doc/library/asyncio-queue.rst @@ -15,10 +15,10 @@ asyncio queues are designed to be similar to classes of the they are designed to be used specifically in async/await code. Note that methods of asyncio queues don't have a *timeout* parameter; -use :func:`asyncio.wait_for` function to perform queue operations with a +use :func:`asyncio.wait_for` function to perform queue operations with timeouts. -See also the `Examples`_ section below. +Also see the `Examples`_ section below. Queue ===== @@ -78,7 +78,7 @@ Queue Block until all items in the queue have been received and processed. The count of unfinished tasks goes up whenever an item is added - to the queue. The count goes down whenever a consumer coroutine calls + to the queue. The count goes down whenever a consumer calls :meth:`task_done` to indicate that the item was retrieved and all work on it is complete. When the count of unfinished tasks drops to zero, :meth:`join` unblocks. @@ -114,8 +114,9 @@ Queue down normally with :meth:`~Queue.get` calls to extract tasks that have already been loaded. - And if :meth:`~Queue.task_done` is called for each remaining task, a - pending :meth:`~Queue.join` will be unblocked normally. + In this case, if :meth:`~Queue.task_done` is called for each + remaining task, a pending :meth:`~Queue.join` will be unblocked + normally. Once the queue is empty, future calls to :meth:`~Queue.get` will raise :exc:`QueueShutDown`. @@ -213,7 +214,7 @@ concurrent tasks:: # Get a "work item" out of the queue. sleep_for = await queue.get() - # Sleep for the "sleep_for" seconds. + # Sleep "sleep_for" seconds. await asyncio.sleep(sleep_for) # Notify the queue that the "work item" has been processed. From a92bcdb6637ffe726d5eefef413fb0eb265b8365 Mon Sep 17 00:00:00 2001 From: Jonathan Dung Date: Fri, 8 May 2026 09:47:44 +0800 Subject: [PATCH 4/5] Fix argument name discrepancies in asyncio tasks documentation --- Doc/library/asyncio-task.rst | 55 ++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 28 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index cc833b80d52542..1f5b170a5bd3b9 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -649,7 +649,7 @@ Eager task factory Shielding from cancellation =========================== -.. awaitablefunction:: shield(aw) +.. awaitablefunction:: shield(arg) Protect an :ref:`awaitable object ` from being :meth:`cancelled `. @@ -686,7 +686,7 @@ Shielding from cancellation .. important:: - Save a reference to tasks passed to this function, to avoid + Save a reference to tasks passed to this function to avoid a task disappearing mid-execution. The event loop only keeps weak references to tasks. A task that isn't referenced elsewhere may get garbage collected at any time, even before it's done. @@ -708,10 +708,10 @@ Timeouts that can be used to limit the amount of time spent waiting on something. - *delay* can either be ``None``, or a float/int number of - seconds to wait. If *delay* is ``None``, no time limit will - be applied; this can be useful if the delay is unknown when - the context manager is created. + *delay* can either be ``None``, or a float/int representing + the number of seconds to wait. If *delay* is ``None``, no time + limit will be applied; this can be useful if the delay is + unknown when the context manager is created. In either case, the context manager can be rescheduled after creation using :meth:`Timeout.reschedule`. @@ -826,9 +826,9 @@ Timeouts If *aw* is a coroutine it is automatically scheduled as a Task. - *timeout* can either be ``None`` or a float or int number of seconds - to wait for. If *timeout* is ``None``, block until the future - completes. + *timeout* can either be ``None`` or a float or int representing + the number of seconds to wait for. If *timeout* is ``None``, + block until the future completes. If a timeout occurs, it cancels the task and raises :exc:`TimeoutError`. @@ -879,14 +879,14 @@ Timeouts Waiting primitives ================== -.. function:: wait(aws, *, timeout=None, return_when=ALL_COMPLETED) +.. function:: wait(fs, *, 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 *fs* iterable concurrently and block until the condition specified - by *return_when*. + by *return_when* is satisfied. - The *aws* iterable must not be empty. + The *fs* iterable must not be empty. Returns two sets of Tasks/Futures: ``(done, pending)``. @@ -928,19 +928,19 @@ Waiting primitives Removed the *loop* parameter. .. versionchanged:: 3.11 - Passing coroutine objects to ``wait()`` directly is forbidden. + Forbade passing coroutine objects to ``wait()`` directly. .. versionchanged:: 3.12 Added support for generators yielding tasks. -.. function:: as_completed(aws, *, timeout=None) +.. function:: as_completed(fs, *, timeout=None) - Run :ref:`awaitable objects ` in the *aws* iterable + Run :ref:`awaitable objects ` in the *fs* iterable concurrently. The returned object can be iterated to obtain the results of the awaitables as they finish. - The object returned by ``as_completed()`` can be iterated as an + The object returned by ``as_completed()`` can be iterated over as an :term:`asynchronous iterator` or a plain :term:`iterator`. When asynchronous iteration is used, the originally-supplied awaitables are yielded if they are tasks or futures. This makes it easy to correlate previously-scheduled @@ -985,7 +985,7 @@ Waiting primitives Removed the *loop* parameter. .. deprecated:: 3.10 - Deprecation warning is emitted if not all awaitable objects in the *aws* + Deprecation warning is emitted if not all awaitable objects in the *fs* iterable are Future-like objects and there is no running event loop. .. versionchanged:: 3.12 @@ -1011,7 +1011,7 @@ Running in threads Return a coroutine that can be awaited to get the eventual result of *func*. - This coroutine function is primarily intended to be used for executing + This coroutine function is primarily intended to be used to execute IO-bound functions/methods that would otherwise block the event loop if they were run in the main thread. For example:: @@ -1061,13 +1061,13 @@ Scheduling from other threads .. function:: run_coroutine_threadsafe(coro, loop) - Submit a coroutine to the given event loop. Thread-safe. + Submit a coroutine to the given event loop. Thread-safe. Return a :class:`concurrent.futures.Future` to wait for the result from another OS thread. This function is meant to be called from a different OS thread - than the one where the event loop is running. Example:: + than the one where the event loop is running. Example:: def in_thread(loop: asyncio.AbstractEventLoop) -> None: # Run some blocking IO @@ -1089,7 +1089,7 @@ Scheduling from other threads # Run something in a thread await asyncio.to_thread(in_thread, loop) - It's also possible to run the other way around. Example:: + It's also possible to run the other way around. Example:: @contextlib.contextmanager def loop_in_thread() -> Generator[asyncio.AbstractEventLoop]: @@ -1140,7 +1140,7 @@ Scheduling from other threads See the :ref:`concurrency and multithreading ` section of the documentation. - Unlike other asyncio functions this function requires the *loop* + Unlike other asyncio functions, this function requires the *loop* argument to be passed explicitly. .. versionadded:: 3.5.1 @@ -1225,10 +1225,10 @@ Task object An optional keyword-only *eager_start* argument allows eagerly starting the execution of the :class:`asyncio.Task` at task creation time. - If set to ``True`` and the event loop is running, the task will start + If set to ``True`` with the event loop running, the task will start executing the coroutine immediately, until the first time the coroutine blocks. If the coroutine returns or raises without blocking, the task - will be finished eagerly and will skip scheduling to the event loop. + will be finished eagerly and the event loop scheduling step is skipped. .. versionchanged:: 3.7 Added support for the :mod:`contextvars` module. @@ -1359,8 +1359,7 @@ Task object Return the name of the Task. If no name has been explicitly assigned to the Task, the default - asyncio Task implementation generates a default name during - instantiation. + implementation generates a default name during instantiation. .. versionadded:: 3.8 @@ -1514,6 +1513,6 @@ Task object cancellation requests go down to zero. This method is used by asyncio's internals and isn't expected to be - used by end-user code. See :meth:`uncancel` for more details. + used by end-user code. See :meth:`uncancel` for more details. .. versionadded:: 3.11 From 47aebb6f48dc140b7d2def2f7c8fd42645bf4027 Mon Sep 17 00:00:00 2001 From: Jonathan Dung Date: Fri, 8 May 2026 17:39:22 +0800 Subject: [PATCH 5/5] fix typo --- Doc/library/asyncio-queue.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index b1c0ef17b0d1bc..1458d668410ce0 100644 --- a/Doc/library/asyncio-queue.rst +++ b/Doc/library/asyncio-queue.rst @@ -28,7 +28,7 @@ Queue A first in, first out (FIFO) queue. If *maxsize* is less than or equal to zero, the queue size is - infinite. If it is an integer greater than ``0``, then + infinite. If it is an integer greater than ``0``, then ``await put()`` blocks when the queue reaches *maxsize* until an item is removed by :meth:`get`. @@ -54,8 +54,8 @@ Queue Return ``True`` if there are :attr:`maxsize` items in the queue. - If the queue was initialized with ``maxsize=0`` (the default), - or a negative :attr:`maxsize:, then :meth:`full` never returns + If the queue was initialized with ``maxsize=0`` (the default) + or a negative ``maxsize``, then :meth:`full` never returns ``True``. .. method:: get()