@@ -254,21 +254,20 @@ Asynchronous generators best practices
254254======================================
255255
256256By :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
260260Manually close the generator
261261----------------------------
262262
263263If an asynchronous generator happens to exit early by :keyword: `break `, the caller
264264task 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
267266during the event loop shutdown when the async-generator garbage collection hook
268267is called.
269268
270269To 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
272271manager::
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
291290As said above, if an asynchronous generator is not resumed before it is
292291finalized, 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
297296Then it is recomended to create async generators only after the event loop
298297has already been created.
299298
300299Avoid 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
305304progress. This may lead to an inconsistent state of the async generator
306- and cause errors.
305+ and can cause errors.
307306
308307Let'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