Address reviews

python · kumaraditya303 · Mar 21, 2026 · Nov 23, 2025 · Nov 24, 2025 · Nov 24, 2025
commit 52565087e44060611a2c84d02bf33d9329d6f916
@@ -253,23 +253,24 @@
 Asynchronous generators best practices
 ======================================
 
-By :term:`asynchronous generator` in this section we will mean
-an :term:`asynchronous generator iterator` that is returned by an
-:term:`asynchronous generator` function.
+Writing correct and efficient asyncio code requires avoiding some known gotchas.
+This section outlines the best practices you need to know.
+Following these practices will save you hours of debugging.
 
 
 Manually close the generator
 ----------------------------
 
-If an asynchronous generator happens to exit early by :keyword:`break`, the caller
-task being cancelled, or other exceptions, the generator's async cleanup code
-will run in an unexpected context -- perhaps after the lifetime of tasks it depends on, or
-during the event loop shutdown when the async-generator garbage collection hook
-is called.
+It is recommended to manually close the
+:term:`asynchronous generator <asynchronous generator iterator>`. If the generator
+exits early by exception raised in the for-loop body, for example,
+the generator's async cleanup code will run in an unexpected context. This could
+happen after the lifetime of tasks it depends on, or during the event loop
+shutdown when the async-generator garbage collection hook is called.
 
 To prevent this, it is recommended to explicitly close the async generator by
-calling the :meth:`~agen.aclose` method, or using a :func:`contextlib.aclosing` context
-manager::
+calling the :meth:`~agen.aclose` method, or by using a :func:`contextlib.aclosing`
+context manager::
 
   import asyncio
   import contextlib
@@ -289,8 +290,9 @@
 Only create a generator when a loop is already running
 ------------------------------------------------------
 
-It is recommended to create asynchronous generators only after the event loop
-has already been created.
+It is recommended to create
+:term:`asynchronous generators <asynchronous generator iterator>` only after
+the event loop has already been created.
 
 To ensure that asynchronous generators close reliably, the event loop uses the
 :func:`sys.set_asyncgen_hooks` function to register callback functions. These
@@ -314,7 +316,7 @@
 Avoid iterating and closing the same generator concurrently
 -----------------------------------------------------------

 Async generators may to 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.