gh-108951: document how to terminate an `asyncio.TaskGroup` by picnixz · Pull Request #123837 · python/cpython · GitHub

Credits to @sobolevn for the original implementation. I just reformulated a bit the way the tasks are created for the docs to make it a bit simpler (I think?)

Issue: Add an asyncio.TaskGroup.cancel method #108951

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

Thank you for polishing this! I am still not sure if this is worth adding to the docs or not. But, this is, luckily, up to asyncio maintainers to decide :)

Yeah, I feel the same because the example is a bit artificial. Your example with randomness was probably closer to what people expect in practice, namely tasks that complete in a non-deterministic order and maybe one of them would want to cancel the entire group, but this also means a non-deterministic output (which I don't really want to have in the docs...).

As for playing the devil's advocate for this case, I don't see how we can "badly" use the helper, except if one explicitly changes the CancellableTaskGroup implementation (devil's advocates are welcomed by the way)

Yeah, I feel the same because the example is a bit artificial

I knew it. When I was writing it I was like "hum... it's too long", so I wanted someone else's eyes, so thanks a lot for the comments Guido. I'll address them tomorrow

I kept the output because not everyone wants to run the code (sometimes, they just want to see the output). If you feel that neither the output nor the intermediate printing jobs are needed, please tell me. However, I think it's nice for the users to see a standalone working example.

Almost there! It looks nice and simple now.

A last bike-shedding question: would it make sense to also rename CancelTaskGroup into StopTaskGroup? strictly speaking, the exception serves as a signal to cancel/stop the task group (in the English sense) but we neither use CancelledError nor .cancel().

We would still use cancel in the docstring but to highlight the non-use of CancelledError, having a visually different name could be helpful for users (but it could also be confusing because they are close to each other...).

Thanks! I've added some suggestions.

Maybe it's because I'm not an English native / asyncio expert, but I feel a slight difference with "terminate", "cancel", "stop" and "abort":

Cancel is kind of generic and can be used to convene the intent of "stopping" whatever is going on. In other words, it can mean "stop", "terminate", "abort" even though it does not use the cancellation in the asyncio sense.
Stop hints me that I could perhaps resume it later (though you could say it would have been a pause/resume). (A bit like SIGSTOP/SIGCONT).
Abort hints me that it's something abrupt and "not good". Like "abort the mission" or SIGABRT. It's more for an unexpected event.

I will go for terminate because:

it terminates/ends/cancels/finishes something,
it can be thought as SIGTERM which, when emitted, can be caught for a graceful exit (which is the case here, we literally catch the exception), and
it could be thought as the signal for reaching a "terminal" state where you wouldn't continue (in contrast to "stop").

@willingc I took the liberty of rewording a bit the introductory paragraph. I quite like the While <some-unfortunate-thing>, we can <some-solution> construction.

Thanks @picnixz. I appreciate your work on this. I think this is ready for merge, but I will give other folks a little time for reviewing.

Excellent! I will merge.

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

…onGH-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 ef05801) Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

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

…onGH-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 ef05801) Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

GH-123957 is a backport of this pull request to the 3.12 branch.

(Presumably the 3.13 backport will be held up by the upcoming release, unless the release manager deems doc PRs harmless. :-)

…123837) (#123956) 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 ef05801) Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

…123837) (#123957) 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 ef05801) Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

picnixz requested review from 1st1, asvetlov, gvanrossum, kumaraditya303 and willingc as code owners September 8, 2024 11:39

bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Sep 8, 2024

bedevere-app Bot mentioned this pull request Sep 8, 2024

Add an asyncio.TaskGroup.cancel method #108951

Closed

sobolevn reviewed Sep 8, 2024

View reviewed changes

Eclips4 added needs backport to 3.12 only security fixes needs backport to 3.13 only security fixes labels Sep 8, 2024

gvanrossum reviewed Sep 8, 2024

View reviewed changes

Comment thread Doc/library/asyncio-task.rst Outdated

Comment thread Doc/library/asyncio-task.rst Outdated

Comment thread Doc/library/asyncio-task.rst Outdated

Comment thread Doc/library/asyncio-task.rst Outdated

picnixz force-pushed the docs/asyncio-task-group-cancel-108951 branch from 76942ed to 7c709b4 Compare September 9, 2024 12:51

Document how to cancel an asynchronous task group.

b4dc0bb

picnixz force-pushed the docs/asyncio-task-group-cancel-108951 branch from 7c709b4 to b4dc0bb Compare September 9, 2024 12:52

gvanrossum reviewed Sep 9, 2024

View reviewed changes

Comment thread Doc/library/asyncio-task.rst Outdated

picnixz commented Sep 10, 2024

View reviewed changes

Comment thread Doc/library/asyncio-task.rst

Update Doc/library/asyncio-task.rst

4e1c6bc

gvanrossum reviewed Sep 10, 2024

View reviewed changes

Comment thread Doc/library/asyncio-task.rst Outdated

willingc reviewed Sep 10, 2024

View reviewed changes

Comment thread Doc/library/asyncio-task.rst Outdated

Comment thread Doc/library/asyncio-task.rst Outdated

address review

cf21e18

willingc approved these changes Sep 11, 2024

View reviewed changes

bedevere-app Bot removed the awaiting review label Sep 11, 2024

bedevere-app Bot added the awaiting merge label Sep 11, 2024

gvanrossum approved these changes Sep 11, 2024

View reviewed changes

gvanrossum merged commit ef05801 into python:main Sep 11, 2024

bedevere-app Bot removed the awaiting merge label Sep 11, 2024

bedevere-app Bot removed the needs backport to 3.13 only security fixes label Sep 11, 2024

bedevere-app Bot removed the needs backport to 3.12 only security fixes label Sep 11, 2024

picnixz deleted the docs/asyncio-task-group-cancel-108951 branch September 11, 2024 15:47

picnixz changed the title gh-108951: document how to cancel an asyncio.TaskGroup gh-108951: document how to terminate an asyncio.TaskGroup Sep 11, 2024

gh-108951: document how to terminate an `asyncio.TaskGroup` by picnixz · Pull Request #123837 · python/cpython · GitHub

Repository navigation

gh-108951: document how to terminate an asyncio.TaskGroup - #123837

gh-108951: document how to terminate an asyncio.TaskGroup#123837gvanrossum merged 3 commits intopython:mainpython/cpython:mainfrom picnixz:docs/asyncio-task-group-cancel-108951picnixz/cpython:docs/asyncio-task-group-cancel-108951Copy head branch name to clipboard

Conversation

picnixz commented Sep 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sobolevn left a comment

Choose a reason for hiding this comment

Uh oh!

picnixz commented Sep 8, 2024

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

picnixz commented Sep 8, 2024

Uh oh!

picnixz commented Sep 9, 2024

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

picnixz commented Sep 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz commented Sep 11, 2024

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

miss-islington-app Bot commented Sep 11, 2024

Uh oh!

bedevere-app Bot commented Sep 11, 2024

Uh oh!

bedevere-app Bot commented Sep 11, 2024

Uh oh!

gvanrossum commented Sep 11, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

gh-108951: document how to terminate an asyncio.TaskGroup#123837
gvanrossum merged 3 commits into
python:mainfrom
picnixz:docs/asyncio-task-group-cancel-108951

picnixz commented Sep 8, 2024 •
edited
Loading

picnixz commented Sep 11, 2024 •
edited
Loading