GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — gh-137026: Add an explainer guide for asyncio by anordin95 · Pull Request #137215 · python/cpython

Conversation

@anordin95

@anordin95 anordin95 commented Jul 29, 2025 •
edited by AA-Turner
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Contributor

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

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

Object905 reacted with heart emoji
All reactions
  • ❤️ 1 reaction
@anordin95
- Add an explainer guide (aka HOWTO, not how-to) for asyncio.
05b35b0
@anordin95
anordin95 requested review from 1st1, asvetlov, kumaraditya303 and willingc as code owners July 29, 2025 18:19
@bedevere-app bedevere-app Bot added the awaiting review label Jul 29, 2025
@python-cla-bot

This comment was marked as resolved.

Sign in to view
@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 added this to Docs PRs Jul 29, 2025
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Jul 29, 2025
anordin95
anordin95 commented Jul 29, 2025
View reviewed changes
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

anordin95
anordin95 commented Jul 29, 2025
View reviewed changes
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

@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
@bedevere-app bedevere-app Bot mentioned this pull request Jul 29, 2025
Documentation enhancement proposal: explainer for asyncio #137026
Closed
@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
@anordin95
Fix linter errors.
446534c
@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
AA-Turner
AA-Turner reviewed Jul 29, 2025
View reviewed changes
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

AA-Turner
AA-Turner reviewed Jul 29, 2025
View reviewed changes
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner AA-Turner added the topic-asyncio label Jul 29, 2025
StanFromIreland
StanFromIreland reviewed Jul 29, 2025
View reviewed changes

@StanFromIreland StanFromIreland left a comment •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

There was a problem hiding this 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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

StanFromIreland
StanFromIreland reviewed Jul 29, 2025
View reviewed changes
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

anordin95 added 5 commits July 29, 2025 12:49
@anordin95
- Enforce max line length of roughly 79 chars.
176096d
- Start sentences on new lines to minimize disruption of diffs.
@anordin95
Add reference to subinterpreters.
b745f88
@anordin95
- Significantly reduce article size. Remove both example sections & "…
0f2b8db
…Which concurrency do I want" section.
@anordin95
Align section-header lengths with section names.
27d1dcd
@anordin95
- Remove reference to deleted section.
3852bb1
ZeroIntensity
ZeroIntensity reviewed Jul 31, 2025
View reviewed changes

@ZeroIntensity ZeroIntensity left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this 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!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

AA-Turner, willingc, and anordin95 reacted with heart emoji
All reactions
  • ❤️ 3 reactions
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

StanFromIreland
StanFromIreland reviewed Jul 31, 2025
View reviewed changes

@StanFromIreland StanFromIreland left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this 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.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

Comment thread Doc/howto/a-conceptual-overview-of-asyncio.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.

anordin95 added 4 commits August 8, 2025 13:50
@anordin95
nit
ac87e24
@anordin95
nit
7e48175
@anordin95
nit
f881bfd
@anordin95
nit
2227e4b
willingc
willingc approved these changes Aug 9, 2025
View reviewed changes

@willingc willingc left a comment

Copy link
Copy Markdown
Contributor

There was a problem hiding this 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!

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

anordin95 reacted with hooray emoji anordin95, StanFromIreland, and ZeroIntensity reacted with heart emoji
All reactions
  • 🎉 1 reaction
  • ❤️ 3 reactions
@willingc willingc added needs backport to 3.13 only 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
@miss-islington-app

miss-islington-app Bot commented Aug 9, 2025

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot removed the awaiting merge label Aug 9, 2025
@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
@anordin95 @ZeroIntensity
@webknjaz @willingc @kumaraditya303 @StanFromIreland @miss-islington
pythongh-137026: Add an explainer guide for asyncio (pythonGH-137215)
a296903
* - 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 <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* - 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 <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* small phrasing.

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nit.

* style nits

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nit

* Fix misnaming of async generator.

* phrasing nits.

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* consistent spacing

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nits

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* 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 (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>

* - 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 <[email protected]>

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

Co-authored-by: Carol Willing <[email protected]>

* nit

* Apply suggestions from code review

Co-authored-by: Carol Willing <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* rework task gc example.

* phrasing tweak.

* tewak.

* nit

* nit

* nit

* nit

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

Co-authored-by: Alexander Nordin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Kumar Aditya <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 9, 2025
@anordin95 @ZeroIntensity
@webknjaz @willingc @kumaraditya303 @StanFromIreland @miss-islington
pythongh-137026: Add an explainer guide for asyncio (pythonGH-137215)
37b2bf9
* - 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 <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* - 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 <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* small phrasing.

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nit.

* style nits

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nit

* Fix misnaming of async generator.

* phrasing nits.

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* consistent spacing

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nits

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* 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 (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>

* - 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 <[email protected]>

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

Co-authored-by: Carol Willing <[email protected]>

* nit

* Apply suggestions from code review

Co-authored-by: Carol Willing <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* rework task gc example.

* phrasing tweak.

* tewak.

* nit

* nit

* nit

* nit

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

Co-authored-by: Alexander Nordin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Kumar Aditya <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
@bedevere-app

bedevere-app Bot commented Aug 9, 2025

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

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

bedevere-app Bot commented Aug 9, 2025

Copy link
Copy Markdown

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

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 only security fixes label Aug 9, 2025
willingc added a commit that referenced this pull request Aug 9, 2025
@miss-islington @anordin95
@ZeroIntensity @webknjaz @willingc @kumaraditya303 @StanFromIreland
[3.13] gh-137026: Add an explainer guide for asyncio (GH-137215) (#13…
ddf951c
…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 <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Kumar Aditya <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
@anordin95

anordin95 commented Aug 9, 2025

Copy link
Copy Markdown
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.

ZeroIntensity and danielhollas reacted with heart emoji
All reactions
  • ❤️ 2 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@anordin95

anordin95 commented Aug 9, 2025

Copy link
Copy Markdown
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!!

ZeroIntensity reacted with heart emoji
All reactions
  • ❤️ 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Aug 9, 2025

Copy link
Copy Markdown
Member

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

A

anordin95 and willingc reacted with hooray emoji anordin95 reacted with heart emoji
All reactions
  • 🎉 2 reactions
  • ❤️ 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@Yhg1s

Yhg1s commented Aug 14, 2025

Copy link
Copy Markdown
Member

One minor nit, as I run across this PR while reviewing changes in 3.13: When merging a change, please, please, please do not use the default github merge message. Replace it with the PR description or a similarly focused, singular message -- or at the very least remove the long list of commits from the message. The merge message is the one that shows up in the git log and it's much more useful if it's focused and short.

AA-Turner, ambv, willingc, and ZeroIntensity reacted with thumbs up emoji
All reactions
  • 👍 4 reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@Dreamsorcerer

Dreamsorcerer commented Aug 14, 2025

Copy link
Copy Markdown
Contributor

When merging a change, please, please, please do not use the default github merge message.

Isn't this configurable? i.e. An admin should be able to change the default under general settings:
image

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@AA-Turner

AA-Turner commented Aug 14, 2025

Copy link
Copy Markdown
Member

We have it set to PR title & commit details, because the PR description often contains clutter we don't want in commit messages. This PR is an edge-case of having lots of individual commits, though!

It's long been noted that the inability to review/pre-decide commit messages is a drawback/missing feature of the GitHub platform.

A

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

@willingc

willingc commented Aug 14, 2025

Copy link
Copy Markdown
Contributor

Thanks for the reminder @Yhg1s. Sorry about the long message.

All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

hugovk pushed a commit that referenced this pull request Aug 15, 2025
@miss-islington @anordin95
@ZeroIntensity @webknjaz @willingc @kumaraditya303 @StanFromIreland
[3.14] gh-137026: Add an explainer guide for asyncio (GH-137215) (#13…
36a1e1a
…7581)

Co-authored-by: Alexander Nordin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Kumar Aditya <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025
@anordin95 @ZeroIntensity
@webknjaz @willingc @kumaraditya303 @StanFromIreland @Agent-Hellboy
pythongh-137026: Add an explainer guide for asyncio (pythonGH-137215)
0d1f828
* - 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 <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* - 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 <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* small phrasing.

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nit.

* style nits

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nit

* Fix misnaming of async generator.

* phrasing nits.

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* consistent spacing

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

Co-authored-by: Peter Bierma <[email protected]>

* phrasing nits

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

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

Co-authored-by: Peter Bierma <[email protected]>

* 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 (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>

* - 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 <[email protected]>

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

Co-authored-by: Carol Willing <[email protected]>

* nit

* Apply suggestions from code review

Co-authored-by: Carol Willing <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* rework task gc example.

* phrasing tweak.

* tewak.

* nit

* nit

* nit

* nit

---------

Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Kumar Aditya <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
kumaraditya303 added a commit to miss-islington/cpython that referenced this pull request Sep 9, 2025
@miss-islington @anordin95
@ZeroIntensity @webknjaz @willingc @kumaraditya303 @StanFromIreland
[3.14] pythongh-137026: Add an explainer guide for asyncio (pythonGH-…
4f2f95f
…137215) (python#137581)

Co-authored-by: Alexander Nordin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
Co-authored-by: Carol Willing <[email protected]>
Co-authored-by: Kumar Aditya <[email protected]>
Co-authored-by: Stan Ulbrych <[email protected]>
@ZeroIntensity ZeroIntensity mentioned this pull request Feb 8, 2026
Asyncio Tutorial #79012
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@webknjaz webknjaz webknjaz left review comments
@AA-Turner AA-Turner AA-Turner left review comments
@picnixz picnixz picnixz left review comments
@ZeroIntensity ZeroIntensity ZeroIntensity approved these changes
@kumaraditya303 kumaraditya303 kumaraditya303 left review comments
@StanFromIreland StanFromIreland StanFromIreland left review comments
@willingc willingc willingc approved these changes
@1st1 1st1 Awaiting requested review from 1st1 1st1 is a code owner
@asvetlov asvetlov Awaiting requested review from asvetlov asvetlov is a code owner
+1 more reviewer
@Dreamsorcerer Dreamsorcerer Dreamsorcerer left review comments
Reviewers whose approvals may not affect merge requirements

Uh oh!

There was an error while loading. Please reload this page.

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news topic-asyncio

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

10 participants

@anordin95 @willingc @ZeroIntensity @kumaraditya303 @AA-Turner @Yhg1s @Dreamsorcerer @webknjaz @picnixz @StanFromIreland
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.