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

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

Merged
gvanrossum merged 3 commits intopython:mainfrom
picnixz:docs/asyncio-task-group-cancel-108951
Sep 11, 2024
Merged

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

Conversation

@picnixz
Copy link
Copy Markdown
Member

@picnixz picnixz commented Sep 8, 2024 •
edited
Loading

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

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

@bedevere-app bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Sep 8, 2024
@bedevere-app bedevere-app Bot mentioned this pull request Sep 8, 2024
Closed
sobolevn
sobolevn reviewed Sep 8, 2024
View reviewed changes
Copy link
Copy Markdown
Member

@sobolevn sobolevn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Copy Markdown
Member Author

picnixz commented Sep 8, 2024

@Eclips4 Eclips4 added needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes labels Sep 8, 2024
gvanrossum
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
Copy link
Copy Markdown
Member Author

picnixz commented Sep 8, 2024

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 picnixz force-pushed the docs/asyncio-task-group-cancel-108951 branch from 76942ed to 7c709b4 Compare September 9, 2024 12:51
@picnixz picnixz force-pushed the docs/asyncio-task-group-cancel-108951 branch from 7c709b4 to b4dc0bb Compare September 9, 2024 12:52
@picnixz
Copy link
Copy Markdown
Member Author

picnixz commented Sep 9, 2024

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
gvanrossum reviewed Sep 9, 2024
View reviewed changes
Copy link
Copy Markdown
Member

@gvanrossum gvanrossum left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Almost there! It looks nice and simple now.

Comment thread Doc/library/asyncio-task.rst Outdated
picnixz
picnixz commented Sep 10, 2024
View reviewed changes
Copy link
Copy Markdown
Member Author

@picnixz picnixz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

picnixz
picnixz commented Sep 10, 2024
View reviewed changes
Comment thread Doc/library/asyncio-task.rst
gvanrossum
gvanrossum reviewed Sep 10, 2024
View reviewed changes
Comment thread Doc/library/asyncio-task.rst Outdated
willingc
willingc reviewed Sep 10, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I've added some suggestions.

Comment thread Doc/library/asyncio-task.rst Outdated
Comment thread Doc/library/asyncio-task.rst Outdated
@picnixz
Copy link
Copy Markdown
Member Author

picnixz commented Sep 11, 2024 •
edited
Loading

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
Copy link
Copy Markdown
Member Author

picnixz commented Sep 11, 2024

@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
willingc approved these changes Sep 11, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@willingc willingc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
gvanrossum approved these changes Sep 11, 2024
View reviewed changes
Copy link
Copy Markdown
Member

@gvanrossum gvanrossum left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent! I will merge.

@gvanrossum gvanrossum merged commit ef05801 into python:main Sep 11, 2024
@miss-islington-app
Copy link
Copy Markdown

miss-islington-app Bot commented Sep 11, 2024

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 11, 2024
@picnixz @miss-islington
pythongh-108951: Document how to terminate an asyncio.TaskGroup (pyth…
f4447ea 
…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>
@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented Sep 11, 2024

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Sep 11, 2024
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 11, 2024
@picnixz @miss-islington
pythongh-108951: Document how to terminate an asyncio.TaskGroup (pyth…
003b942 
…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>
@bedevere-app
Copy link
Copy Markdown

bedevere-app Bot commented Sep 11, 2024

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.12 only security fixes label Sep 11, 2024
@gvanrossum
Copy link
Copy Markdown
Member

gvanrossum commented Sep 11, 2024

@picnixz picnixz deleted the docs/asyncio-task-group-cancel-108951 branch September 11, 2024 15:47
@picnixz 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
Yhg1s pushed a commit that referenced this pull request Sep 24, 2024
@miss-islington @picnixz
[3.13] gh-108951: Document how to terminate an asyncio.TaskGroup (GH-…
951c7db 
…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>
kumaraditya303 pushed a commit that referenced this pull request Sep 25, 2024
@miss-islington @picnixz
[3.12] gh-108951: Document how to terminate an asyncio.TaskGroup (GH-…
13565f1 
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sobolevn sobolevn sobolevn left review comments

@willingc willingc willingc approved these changes

@gvanrossum gvanrossum gvanrossum approved these changes

@1st1 1st1 Awaiting requested review from 1st1 1st1 is a code owner

@asvetlov asvetlov Awaiting requested review from asvetlov asvetlov is a code owner

@kumaraditya303 kumaraditya303 Awaiting requested review from kumaraditya303 kumaraditya303 is a code owner

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@picnixz @gvanrossum @1st1 @willingc @sobolevn @Eclips4