GH-100108: Add async generators best practices section#141885
GH-100108: Add async generators best practices section#141885sergey-miryanov wants to merge 8 commits intopython:mainfrom
Conversation
sergey-miryanov
requested review from
1st1,
asvetlov,
kumaraditya303 and
willingc
as code owners
bedevere-app
bot
added
awaiting review
docs
|
@kumaraditya303 Could you please take a look? |
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Doc/library/asyncio-dev.rst
Outdated
| Manually close the generator | ||
| ---------------------------- | ||
|
|
||
| If an asynchronous generator happens to exit early by :keyword:`break`, the caller |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Thanks, will fix this.
There was a problem hiding this comment.
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!)
There was a problem hiding this comment.
Tried to rephrase.
|
I would appreciate a review from @willingc and @gvanrossum on this. |
gvanrossum
left a comment
gvanrossum
left a comment
There was a problem hiding this comment.
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").
Doc/library/asyncio-dev.rst
Outdated
| Manually close the generator | ||
| ---------------------------- | ||
|
|
||
| If an asynchronous generator happens to exit early by :keyword:`break`, the caller |
There was a problem hiding this comment.
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!)
Doc/library/asyncio-dev.rst
Outdated
| Then it is recomended to create async generators only after the event loop | ||
| has already been created. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
The explanation in this section is incorrect. I looked into it again and will rewrite it.
|
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'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. |
Thank you! I really appreciate it! |
Co-authored-by: Guido van Rossum <gvanrossum@gmail.com>
4 participants
Added section about best practices for async generators.
asynciodocs #100108📚 Documentation preview 📚: https://cpython-previews--141885.org.readthedocs.build/