Skip to content

gh-137026: Add an explainer guide for asyncio #137215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 116 commits into from
Aug 9, 2025
Merged

Conversation

anordin95
Copy link
Contributor

@anordin95 anordin95 commented Jul 29, 2025

Explainer guide for asyncio

gh-137026: HOWTO article for asyncio, and a reference to it from the main page of the asyncio docs.


Hi!

I've used Python's asyncio a couple times now, but never really felt confident in my mental model of how it fundamentally works and therefore how I can best leverage it. The official docs provide good documentation for each specific function in the package, but, in my opinion, are missing a cohesive overview of the systems design and architecture. Something that could help the user understand the why and how behind the recommended patterns. And a way to help the user make informed decisions about which tool in the asyncio toolkit they ought to grab, or to recognize when asyncio is the entirely wrong toolkit. I thought I'd take a stab at filling that gap and contributing back to a community that's given so much!


📚 Documentation preview 📚: https://cpython-previews--137215.org.readthedocs.build/en/137215/howto/a-conceptual-overview-of-asyncio.html

@python-cla-bot

This comment was marked as resolved.

@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news labels Jul 29, 2025
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs Jul 29, 2025
@anordin95 anordin95 changed the title - Add an explainer guide for asyncio. Add an explainer guide for asyncio [gh-137026](https://github.com/python/cpython/issues/137026) Jul 29, 2025
@anordin95 anordin95 changed the title Add an explainer guide for asyncio [gh-137026](https://github.com/python/cpython/issues/137026) Add an explainer guide for asyncio [gh-137026] Jul 29, 2025
@AA-Turner AA-Turner changed the title Add an explainer guide for asyncio [gh-137026] gh-137026: Add an explainer guide for asyncio Jul 29, 2025
Copy link
Member

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will review further once the lines are wrapped, as now it will invalidate suggestions.

Copy link
Member

@ZeroIntensity ZeroIntensity left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to commit to reviewing this if nobody else has the time. I think is generally an improvement to the documentation, but definitely needs some work still. Thanks for working on this!

Copy link
Member

@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are still many minor infringements of the Style guide (e.g. simple English) which could be addressed in one pass.

You can also use Sphinx cross references when discussing specific keywords, functions etc.

Copy link
Contributor

@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @anordin95 for being responsive to everyone's feedback. It's appreciated. I'm grateful for @ZeroIntensity's thoughtful review and shepherding this PR. I'm going to approve and merge. Any additional changes can be done in future PRs. Thanks and congrats!

@willingc willingc added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes and removed DO-NOT-MERGE labels Aug 9, 2025
@willingc willingc merged commit 3964f97 into python:main Aug 9, 2025
31 of 32 checks passed
@miss-islington-app
Copy link

Thanks @anordin95 for the PR, and @willingc for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs Aug 9, 2025
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 9, 2025
* - Add an explainer guide (aka HOWTO, not how-to) for asyncio.

* Fix linter errors.

* - Enforce max line length of roughly 79 chars.
- Start sentences on new lines to minimize disruption of diffs.

* Add reference to subinterpreters.

* - Significantly reduce article size. Remove both example sections & "Which concurrency do I want" section.

* Align section-header lengths with section names.

* - Remove reference to deleted section.

* - Fix a variety of rote style guide items like title-alignment, use of ie and $, and so forth.
- Add links to other parts of the docs for keywords and objects like await, coro, task, future, etc.

* - One last title alignment.

* - Style nit.

* - Rework a variety of I statements.

* Lint fix.

* - Firm up commentary on yield from in corotuines.

* Update language comparing await and yield from.

* - Remove await-ing Tasks and futures section

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* - Address comments related to style & writing flow.

* per-thread event loop note.

* Add section describing coroutines roots in generators.

* Phrasing tweak.

* Use asyncio.create_task instead of asyncio.Task

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* small phrasing.

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* phrasing nit.

* style nits

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* phrasing nit

* Fix misnaming of async generator.

* phrasing nits.

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* consistent spacing

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* phrasing nits

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* add conclusion

* nits

* - Variety of style & grammar improvements thanks to ZeroIntensity's comments.

* - Make all directives start with a 3 space indent. Then 4 thereafter.

* - Use :linenos: instead of manually writing the line numbers.

* - Fix label typo for article.

* fix label link.

* Apply suggestions from code review

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* - introduce async-sleep name

* Phrasing

* nit

* ungendered octopus

* teammates

* jobs

* rework fella to penguin

* - remove byline; add seealso

* Change ref from asyncio to use seealso block.

* Remove typehints. Fix indentation in one code example.

* Slight rephrase for clarity.

* Make references point to asyncio. Wrap some long lines.

* - Variety of style/phrasing improvements based on PR feedback.

* phrasing.

* phrasing nit.

* Apply suggestions from code review

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

* nit

* Apply suggestions from code review

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

* fix backticks.

* nits

* nit

* add section on asyncio.run

* title change under the hood.

* modify task coro example.

* howtos article link.

* prefer await without backticks.

* phrasing tweak.

* Rework phrasing around how await tasks pauses and returns control in the await section.

* move code block to beforfe explanation in coroutine under the hood.

* phrasing.

* link to yield from.

* style nits

* nit

* - Modify language re: event-loop cycling endlessly.
- Discuss why await was designed to not yield for coros.

* - Add a note about debug=True on asyncio.run to await coro section.

* clarity nit

* - Add two other references in seealso block.

* nit

* Language simplification

* Apply suggestions from code review

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* nit

* grammar fix.

* fix

* worker bees

* rework event loop paragraph to significantly deemphasize queues

* remove all references to queue besides the initial analogy.

* add note about garbage collection of tasks

* add practical note re: garbage collection

* phrasing nits

* re arrange note on task gc.

* line wrap nit

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Kumar Aditya <kumaraditya@python.org>

* link to debug mode docs.

* readd part2 prefix.

* simplify title.

* fix titles. tihnk I messed this up earlier.

* avoid idiom in title.

* fix titles once agian.

* Apply suggestions from code review

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

* rework task gc example.

* phrasing tweak.

* tewak.

* nit

* nit

* nit

* nit

---------
(cherry picked from commit 3964f974894eff1653913dda437971e0bbfa8ccc)

Co-authored-by: Alexander Nordin <alexander.f.nordin@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Kumar Aditya <kumaraditya@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 9, 2025
* - Add an explainer guide (aka HOWTO, not how-to) for asyncio.

* Fix linter errors.

* - Enforce max line length of roughly 79 chars.
- Start sentences on new lines to minimize disruption of diffs.

* Add reference to subinterpreters.

* - Significantly reduce article size. Remove both example sections & "Which concurrency do I want" section.

* Align section-header lengths with section names.

* - Remove reference to deleted section.

* - Fix a variety of rote style guide items like title-alignment, use of ie and $, and so forth.
- Add links to other parts of the docs for keywords and objects like await, coro, task, future, etc.

* - One last title alignment.

* - Style nit.

* - Rework a variety of I statements.

* Lint fix.

* - Firm up commentary on yield from in corotuines.

* Update language comparing await and yield from.

* - Remove await-ing Tasks and futures section

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* - Address comments related to style & writing flow.

* per-thread event loop note.

* Add section describing coroutines roots in generators.

* Phrasing tweak.

* Use asyncio.create_task instead of asyncio.Task

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* small phrasing.

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* phrasing nit.

* style nits

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* phrasing nit

* Fix misnaming of async generator.

* phrasing nits.

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* consistent spacing

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* phrasing nits

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* add conclusion

* nits

* - Variety of style & grammar improvements thanks to ZeroIntensity's comments.

* - Make all directives start with a 3 space indent. Then 4 thereafter.

* - Use :linenos: instead of manually writing the line numbers.

* - Fix label typo for article.

* fix label link.

* Apply suggestions from code review

Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* - introduce async-sleep name

* Phrasing

* nit

* ungendered octopus

* teammates

* jobs

* rework fella to penguin

* - remove byline; add seealso

* Change ref from asyncio to use seealso block.

* Remove typehints. Fix indentation in one code example.

* Slight rephrase for clarity.

* Make references point to asyncio. Wrap some long lines.

* - Variety of style/phrasing improvements based on PR feedback.

* phrasing.

* phrasing nit.

* Apply suggestions from code review

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

* nit

* Apply suggestions from code review

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

* fix backticks.

* nits

* nit

* add section on asyncio.run

* title change under the hood.

* modify task coro example.

* howtos article link.

* prefer await without backticks.

* phrasing tweak.

* Rework phrasing around how await tasks pauses and returns control in the await section.

* move code block to beforfe explanation in coroutine under the hood.

* phrasing.

* link to yield from.

* style nits

* nit

* - Modify language re: event-loop cycling endlessly.
- Discuss why await was designed to not yield for coros.

* - Add a note about debug=True on asyncio.run to await coro section.

* clarity nit

* - Add two other references in seealso block.

* nit

* Language simplification

* Apply suggestions from code review

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>

* nit

* grammar fix.

* fix

* worker bees

* rework event loop paragraph to significantly deemphasize queues

* remove all references to queue besides the initial analogy.

* add note about garbage collection of tasks

* add practical note re: garbage collection

* phrasing nits

* re arrange note on task gc.

* line wrap nit

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst

Co-authored-by: Kumar Aditya <kumaraditya@python.org>

* link to debug mode docs.

* readd part2 prefix.

* simplify title.

* fix titles. tihnk I messed this up earlier.

* avoid idiom in title.

* fix titles once agian.

* Apply suggestions from code review

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

* rework task gc example.

* phrasing tweak.

* tewak.

* nit

* nit

* nit

* nit

---------
(cherry picked from commit 3964f97)

Co-authored-by: Alexander Nordin <alexander.f.nordin@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Kumar Aditya <kumaraditya@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@bedevere-app
Copy link

bedevere-app bot commented Aug 9, 2025

GH-137581 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Aug 9, 2025
@bedevere-app
Copy link

bedevere-app bot commented Aug 9, 2025

GH-137582 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Aug 9, 2025
willingc added a commit that referenced this pull request Aug 9, 2025
…7582)

gh-137026: Add an explainer guide for asyncio (GH-137215)

* - Add an explainer guide (aka HOWTO, not how-to) for asyncio.

* Fix linter errors.

* - Enforce max line length of roughly 79 chars.
- Start sentences on new lines to minimize disruption of diffs.

* Add reference to subinterpreters.

* - Significantly reduce article size. Remove both example sections & "Which concurrency do I want" section.

* Align section-header lengths with section names.

* - Remove reference to deleted section.

* - Fix a variety of rote style guide items like title-alignment, use of ie and $, and so forth.
- Add links to other parts of the docs for keywords and objects like await, coro, task, future, etc.

* - One last title alignment.

* - Style nit.

* - Rework a variety of I statements.

* Lint fix.

* - Firm up commentary on yield from in corotuines.

* Update language comparing await and yield from.

* - Remove await-ing Tasks and futures section

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* - Address comments related to style & writing flow.

* per-thread event loop note.

* Add section describing coroutines roots in generators.

* Phrasing tweak.

* Use asyncio.create_task instead of asyncio.Task

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* small phrasing.

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* phrasing nit.

* style nits

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* phrasing nit

* Fix misnaming of async generator.

* phrasing nits.

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* consistent spacing

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* phrasing nits

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* add conclusion

* nits

* - Variety of style & grammar improvements thanks to ZeroIntensity's comments.

* - Make all directives start with a 3 space indent. Then 4 thereafter.

* - Use :linenos: instead of manually writing the line numbers.

* - Fix label typo for article.

* fix label link.

* Apply suggestions from code review





* - introduce async-sleep name

* Phrasing

* nit

* ungendered octopus

* teammates

* jobs

* rework fella to penguin

* - remove byline; add seealso

* Change ref from asyncio to use seealso block.

* Remove typehints. Fix indentation in one code example.

* Slight rephrase for clarity.

* Make references point to asyncio. Wrap some long lines.

* - Variety of style/phrasing improvements based on PR feedback.

* phrasing.

* phrasing nit.

* Apply suggestions from code review



* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* nit

* Apply suggestions from code review



* fix backticks.

* nits

* nit

* add section on asyncio.run

* title change under the hood.

* modify task coro example.

* howtos article link.

* prefer await without backticks.

* phrasing tweak.

* Rework phrasing around how await tasks pauses and returns control in the await section.

* move code block to beforfe explanation in coroutine under the hood.

* phrasing.

* link to yield from.

* style nits

* nit

* - Modify language re: event-loop cycling endlessly.
- Discuss why await was designed to not yield for coros.

* - Add a note about debug=True on asyncio.run to await coro section.

* clarity nit

* - Add two other references in seealso block.

* nit

* Language simplification

* Apply suggestions from code review



* nit

* grammar fix.

* fix

* worker bees

* rework event loop paragraph to significantly deemphasize queues

* remove all references to queue besides the initial analogy.

* add note about garbage collection of tasks

* add practical note re: garbage collection

* phrasing nits

* re arrange note on task gc.

* line wrap nit

* Update Doc/howto/a-conceptual-overview-of-asyncio.rst



* link to debug mode docs.

* readd part2 prefix.

* simplify title.

* fix titles. tihnk I messed this up earlier.

* avoid idiom in title.

* fix titles once agian.

* Apply suggestions from code review



* rework task gc example.

* phrasing tweak.

* tewak.

* nit

* nit

* nit

* nit

---------
(cherry picked from commit 3964f97)

Co-authored-by: Alexander Nordin <alexander.f.nordin@gmail.com>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
Co-authored-by: Kumar Aditya <kumaraditya@python.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@anordin95
Copy link
Contributor Author

Many of these comments were thoughtful, respectful and justified. However, I experienced some of them as more commanding or condescending rather than collaborative. They ultimately made the process a tad unpleasant and I’m hesitant to return for a second contribution. Both things are certainly far from the end of the world! I just wanted to offer my candid perspective and feedback.

@anordin95
Copy link
Contributor Author

Thank you everyone for contributing your time and knowledge to this piece! I’d like to especially commend @ZeroIntensity for his thorough, diligent & thoughtful effort!!

@AA-Turner
Copy link
Member

Congratulations @anordin95; a special thank you to @ZeroIntensity, @willingc, and the other reviewers for getting this over the line!

A

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news topic-asyncio
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

9 participants
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy