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 3964f97489)
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>
gh-132354: document return value for `asyncio.Task.cancel` (GH-132374)
(cherry picked from commit 64b066ad29)
Co-authored-by: Felix Scherz <felixwscherz@gmail.com>
gh-125289: Update sample code in asyncio-task.rst (GH-125292)
* Update sample code in asyncio-task.rst
This will change **coroutines** sample code in the **Awaitables** section and make the example clearer.
* Update Doc/library/asyncio-task.rst
Revert the added print
* Update Doc/library/asyncio-task.rst
---------
(cherry picked from commit fa52b82c91)
Co-authored-by: Ghorban M. Tavakoly <58617996+galmyk@users.noreply.github.com>
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
gh-108951: Document how to terminate an asyncio.TaskGroup (GH-123837)
We don't want to add another API, since the recipe is straightforward and rarely needed.
The advantage is that we could backport this to the earliest Python version that has taskgroups (3.11, alas in security mode already, so we'll just do 3.12 and 3.13).
(cherry picked from commit ef05801ba0)
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Docs: spelling and grammar fixes (GH-122084)
Corrected some grammar and spelling issues in documentation.
(cherry picked from commit bc264eac3a)
Co-authored-by: Ville Skyttä <ville.skytta@iki.fi>
Co-authored-by: Russell Keith-Magee <russell@keith-magee.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This prevents external cancellations of a task group's parent task to
be dropped when an internal cancellation happens at the same time.
Also strengthen the semantics of uncancel() to clear self._must_cancel
when the cancellation count reaches zero.
Co-Authored-By: Tin Tvrtković <tinchester@gmail.com>
Co-Authored-By: Arthur Tacca
* as_completed returns object that is both iterator and async iterator
* Existing tests adjusted to test both the old and new style
* New test to ensure iterator can be resumed
* New test to ensure async iterator yields any passed-in Futures as-is
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Guido van Rossum <gvanrossum@gmail.com>
Also use `raise TimeOut from <CancelledError instance>` so that the CancelledError is set
in the `__cause__` field rather than in the `__context__` field.
Co-authored-by: Guido van Rossum <gvanrossum@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Once the task group is shutting down, it should not be possible to create a new task.
Here "shutting down" means `self._aborting` is set, indicating that at least one task
has failed and we have cancelled all others.
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
After a long deliberation we ended up feeling that the message argument for Future.cancel(), added in 3.9, was a bad idea, so we're deprecating it in 3.11 and plan to remove it in 3.13.
