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

[miss-islington]

• • 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]

• Issue: Documentation enhancement proposal: explainer for asyncio #137026

---

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