GH-100108: Add async generators best practices section #141885

sergey-miryanov · 2025-11-23T21:16:12Z

Added section about best practices for async generators.

Issue: Add a section about async generators in asyncio docs #100108

📚 Documentation preview 📚: https://cpython-previews--141885.org.readthedocs.build/

sergey-miryanov · 2025-11-23T21:16:32Z

@kumaraditya303 Could you please take a look?

Doc/library/asyncio-dev.rst

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

kumaraditya303 · 2025-11-25T09:31:27Z

Doc/library/asyncio-dev.rst

+Asynchronous generators best practices
+======================================
+
+By :term:`asynchronous generator` in this section we will mean


This seems obvious, by generator we typically mean the generator object not the function.

I saw this clarification in few places (e.g. https://docs.python.org/3/glossary.html#term-asynchronous-generator), so I thought it was worth mentioning. I'm OK to remove this if you think so.

In my experience, the term "generator" is used equally for a generator function and for the iterator returned by calling a generator function. If you really only use it for the latter, then this clarification makes sense.

kumaraditya303 · 2025-11-25T09:33:28Z

Doc/library/asyncio-dev.rst

+Manually close the generator
+----------------------------
+
+If an asynchronous generator happens to exit early by :keyword:`break`, the caller


This feels too heavy for start, I would start it as "It is recommended to manually close the generator... " then in second para describe the issue with breaking early.

Thanks, will fix this.

IIUC the scenario(s) you are trying to describe is where the code iterating over the generator doesn't iterate till the end. If you're iterating over it using a for-loop (there are other ways!) that could be a break in that for-loop, or the task containing that for-loop getting canceled, or indeed an exception being raised in the for-loop body. But I'm not sure it's helpful to try to list all the reasons why this can happen -- maybe the most useful one to mention is an exception being raised during that for-loop?

(The example code clarifies a lot!)

kumaraditya303 · 2025-11-25T09:35:21Z

I would appreciate a review from @willingc and @gvanrossum on this.

gvanrossum

It's great to add these explicitly to the docs!

I hope you don't mind that I have tried to correct your English grammar somewhat (mostly adding or subtracting "the").

gvanrossum · 2025-11-26T00:52:17Z

Doc/library/asyncio-dev.rst

+======================================
+
+By :term:`asynchronous generator` in this section we will mean
+an :term:`asynchronous generator iterator` that returned by


Suggested change

an :term:`asynchronous generator iterator` that returned by

an :term:`asynchronous generator iterator` that is returned by an

gvanrossum · 2025-11-26T00:55:39Z

Doc/library/asyncio-dev.rst

+Asynchronous generators best practices
+======================================
+
+By :term:`asynchronous generator` in this section we will mean


In my experience, the term "generator" is used equally for a generator function and for the iterator returned by calling a generator function. If you really only use it for the latter, then this clarification makes sense.

gvanrossum · 2025-11-26T01:10:12Z

Doc/library/asyncio-dev.rst

+
+
+Asynchronous generators best practices
+======================================


I'd insert some friendly words here introducing the reader to the purpose of this section. Right now it looks rather stern.

gvanrossum · 2025-11-26T01:22:34Z

Doc/library/asyncio-dev.rst

+Manually close the generator
+----------------------------
+
+If an asynchronous generator happens to exit early by :keyword:`break`, the caller


IIUC the scenario(s) you are trying to describe is where the code iterating over the generator doesn't iterate till the end. If you're iterating over it using a for-loop (there are other ways!) that could be a break in that for-loop, or the task containing that for-loop getting canceled, or indeed an exception being raised in the for-loop body. But I'm not sure it's helpful to try to list all the reasons why this can happen -- maybe the most useful one to mention is an exception being raised during that for-loop?

(The example code clarifies a lot!)

gvanrossum · 2025-11-26T01:24:47Z

Doc/library/asyncio-dev.rst

+will run and possibly raise exceptions or access context variables in an
+unexpected context--perhaps after the lifetime of tasks it depends, or


Suggested change

will run and possibly raise exceptions or access context variables in an

unexpected context--perhaps after the lifetime of tasks it depends, or

will run in an unexpected context -- perhaps after the lifetime of tasks it depends on, or

gvanrossum · 2025-11-26T01:31:48Z

Doc/library/asyncio-dev.rst

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


I'm not sure I follow how it follows from the previous paragraph (which describes that finalization of an async generator-iterator may be delayed if its body hasn't finished yet) to the recommendation of creating them only after an event loop exists.

gvanrossum · 2025-11-26T01:41:35Z

Doc/library/asyncio-dev.rst

+Avoid iterating and closing the same generator concurrently
+-----------------------------------------------------------
+
+The async generators allow to be reentered while another


Suggested change

The async generators allow to be reentered while another

Async generators may to be reentered while another

gvanrossum · 2025-11-26T01:42:42Z

Doc/library/asyncio-dev.rst

+-----------------------------------------------------------
+
+The async generators allow to be reentered while another
+:meth:`~agen.aclose`/:meth:`~agen.aclose`/:meth:`~agen.aclose` call is in


Why is :meth:`~agen.aclose` repeated three times here?

gvanrossum · 2025-11-26T01:43:12Z

Doc/library/asyncio-dev.rst

+The async generators allow to be reentered while another
+:meth:`~agen.aclose`/:meth:`~agen.aclose`/:meth:`~agen.aclose` call is in
+progress. This may lead to an inconsistent state of the async generator
+and cause errors.


Suggested change

and cause errors.

and can cause errors.

gvanrossum · 2025-11-26T01:48:25Z

Doc/library/asyncio-dev.rst

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


Suggested change

Therefore, it is recommended to avoid using the async generators in parallel

tasks or in the multiple event loops.

Therefore, it is recommended to avoid using async generators in parallel

tasks or from multiple event loops.

bedevere-app · 2025-11-26T01:50:24Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

gvanrossum · 2025-11-26T01:51:24Z

I'd also love to get @willingc's view on how to make this section have the right tone so as not to scare beginners away.

Add async generators best practices section

8fb10ee

sergey-miryanov requested review from 1st1, asvetlov, kumaraditya303 and willingc as code owners November 23, 2025 21:16

bedevere-app bot added awaiting review docs Documentation in the Doc dir skip news labels Nov 23, 2025

github-project-automation bot added this to Docs PRs Nov 23, 2025

github-project-automation bot moved this to Todo in Docs PRs Nov 23, 2025

bedevere-app bot mentioned this pull request Nov 23, 2025

Add a section about async generators in asyncio docs #100108

Open

StanFromIreland reviewed Nov 23, 2025

View reviewed changes

Doc/library/asyncio-dev.rst Outdated Show resolved Hide resolved

StanFromIreland reviewed Nov 23, 2025

View reviewed changes

Doc/library/asyncio-dev.rst Outdated Show resolved Hide resolved

sergey-miryanov and others added 2 commits November 24, 2025 10:32

Update Doc/library/asyncio-dev.rst

ae50f3f

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Fix spacing between sections

99f148c

kumaraditya303 self-assigned this Nov 24, 2025

kumaraditya303 reviewed Nov 25, 2025

View reviewed changes

gvanrossum requested changes Nov 26, 2025

View reviewed changes

bedevere-app bot removed the awaiting review label Nov 26, 2025

bedevere-app bot added the awaiting changes label Nov 26, 2025

	an :term:`asynchronous generator iterator` that returned by
	an :term:`asynchronous generator iterator` that is returned by an



		Asynchronous generators best practices
		======================================

		will run and possibly raise exceptions or access context variables in an
		unexpected context--perhaps after the lifetime of tasks it depends, or

	will run and possibly raise exceptions or access context variables in an
	unexpected context--perhaps after the lifetime of tasks it depends, or
	will run in an unexpected context -- perhaps after the lifetime of tasks it depends on, or

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

	The async generators allow to be reentered while another
	Async generators may to be reentered while another

		Therefore, it is recommended to avoid using the async generators in parallel
		tasks or in the multiple event loops.

Uh oh!

GH-100108: Add async generators best practices section #141885

Are you sure you want to change the base?

GH-100108: Add async generators best practices section #141885

Conversation

sergey-miryanov commented Nov 23, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sergey-miryanov commented Nov 23, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kumaraditya303 commented Nov 25, 2025

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Nov 26, 2025

Uh oh!

gvanrossum commented Nov 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sergey-miryanov commented Nov 23, 2025 •

edited by github-actions bot

Loading