-
-
Notifications
You must be signed in to change notification settings - Fork 32.5k
[3.13] gh-137026: Add an explainer guide for asyncio (GH-137215) #137582
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
+617
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* - 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>
This was referenced Aug 9, 2025
willingc
approved these changes
Aug 9, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Fix linter errors.
Add reference to subinterpreters.
Align section-header lengths with section names.
Lint fix.
Update language comparing await and yield from.
Update Doc/howto/a-conceptual-overview-of-asyncio.rst
Co-authored-by: Peter Bierma zintensitydev@gmail.com
Co-authored-by: Peter Bierma zintensitydev@gmail.com
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
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
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
Co-authored-by: Peter Bierma zintensitydev@gmail.com
Co-authored-by: Peter Bierma zintensitydev@gmail.com
Co-authored-by: Peter Bierma zintensitydev@gmail.com
add conclusion
nits
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
Phrasing
nit
ungendered octopus
teammates
jobs
rework fella to penguin
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.
phrasing.
phrasing nit.
Apply suggestions from code review
Co-authored-by: Peter Bierma zintensitydev@gmail.com
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
clarity nit
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
📚 Documentation preview 📚: https://cpython-previews--137582.org.readthedocs.build/