Skip to content

Commit 11242b4

Browse files
Apply suggestions from code review
Co-authored-by: Guido van Rossum <gvanrossum@gmail.com>
1 parent 99f148c commit 11242b4

File tree

1 file changed

+11
-12
lines changed

1 file changed

+11
-12
lines changed

Doc/library/asyncio-dev.rst

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -254,21 +254,20 @@ Asynchronous generators best practices
254254
======================================
255255

256256
By :term:`asynchronous generator` in this section we will mean
257-
an :term:`asynchronous generator iterator` that returned by
257+
an :term:`asynchronous generator iterator` that is returned by an
258258
:term:`asynchronous generator` function.
259259

260260
Manually close the generator
261261
----------------------------
262262

263263
If an asynchronous generator happens to exit early by :keyword:`break`, the caller
264264
task being cancelled, or other exceptions, the generator's async cleanup code
265-
will run and possibly raise exceptions or access context variables in an
266-
unexpected context--perhaps after the lifetime of tasks it depends, or
265+
will run in an unexpected context -- perhaps after the lifetime of tasks it depends on, or
267266
during the event loop shutdown when the async-generator garbage collection hook
268267
is called.
269268

270269
To prevent this, it is recommended to explicitly close the async generator by
271-
calling :meth:`~agen.aclose` method, or using :func:`contextlib.aclosing` context
270+
calling the :meth:`~agen.aclose` method, or using a :func:`contextlib.aclosing` context
272271
manager::
273272

274273
import asyncio
@@ -281,7 +280,7 @@ manager::
281280
async def func():
282281
async with contextlib.aclosing(gen()) as g:
283282
async for x in g:
284-
break
283+
break # Don't iterate until the end
285284

286285
asyncio.run(func())
287286

@@ -290,20 +289,20 @@ Only create a generator when a loop is already running
290289

291290
As said above, if an asynchronous generator is not resumed before it is
292291
finalized, then any finalization procedures will be delayed. The event loop
293-
handles this situation and doing it best to call async generator-iterator's
294-
:meth:`~agen.aclose` at the proper moment, thus allowing any pending
295-
:keyword:`!finally` clauses to execute.
292+
handles this situation and doing its best to call the async generator-iterator's
293+
:meth:`~agen.aclose` method at the proper moment, thus allowing any pending
294+
:keyword:`!finally` clauses to run.
296295

297296
Then it is recomended to create async generators only after the event loop
298297
has already been created.
299298

300299
Avoid iterating and closing the same generator concurrently
301300
-----------------------------------------------------------
302301

303-
The async generators allow to be reentered while another
302+
Async generators may to be reentered while another
304303
:meth:`~agen.aclose`/:meth:`~agen.aclose`/:meth:`~agen.aclose` call is in
305304
progress. This may lead to an inconsistent state of the async generator
306-
and cause errors.
305+
and can cause errors.
307306

308307
Let's consider following example::
309308

@@ -347,5 +346,5 @@ Output::
347346
RuntimeError: anext(): asynchronous generator is already running
348347

349348

350-
Therefore, it is recommended to avoid using the async generators in parallel
351-
tasks or in the multiple event loops.
349+
Therefore, it is recommended to avoid using async generators in parallel
350+
tasks or from multiple event loops.

0 commit comments

Comments
 (0)