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

picnixz · 2024-09-08T11:39:23Z

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/

sobolevn

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 :)

picnixz · 2024-09-08T13:13:45Z

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)

Doc/library/asyncio-task.rst

picnixz · 2024-09-08T18:28:44Z

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

picnixz · 2024-09-09T12:54:24Z

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.

gvanrossum

Almost there! It looks nice and simple now.

Doc/library/asyncio-task.rst

picnixz

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...).

Doc/library/asyncio-task.rst

willingc

Thanks! I've added some suggestions.

Doc/library/asyncio-task.rst

picnixz · 2024-09-11T11:23:57Z

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").

picnixz · 2024-09-11T11:36:17Z

@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.

willingc

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.

gvanrossum

Excellent! I will merge.

miss-islington-app · 2024-09-11T15:43:27Z

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 <[email protected]>

bedevere-app · 2024-09-11T15:43:37Z

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 <[email protected]>

bedevere-app · 2024-09-11T15:43:44Z

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

gvanrossum · 2024-09-11T15:45:28Z

(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 <[email protected]>

…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 <[email protected]>

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

Open

sobolevn reviewed Sep 8, 2024

View reviewed changes

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

gvanrossum reviewed Sep 8, 2024

View reviewed changes

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

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

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

picnixz commented Sep 10, 2024

View reviewed changes

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

Update Doc/library/asyncio-task.rst

4e1c6bc

gvanrossum reviewed Sep 10, 2024

View reviewed changes

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

willingc reviewed Sep 10, 2024

View reviewed changes

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

Doc/library/asyncio-task.rst Outdated Show resolved Hide resolved

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
25 checks passed

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

bedevere-app bot removed the needs backport to 3.13 bugs and 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

Uh oh!

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

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

Uh oh!

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!

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!

Uh oh!

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

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

picnixz commented Sep 8, 2024 •

edited

Loading

picnixz commented Sep 11, 2024 •

edited

Loading