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

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

Author: 6 people