Skip to content

gh-108951: document addition of TaskGroup.cancel() #149031

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gvanrossum merged 5 commits into from
Apr 28, 2026
Merged

gh-108951: document addition of TaskGroup.cancel() #149031

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2bf9185
gh-108951: Whatsnew and doc tweaks for TaskGroup.cancel()
belm0 Apr 26, 2026
e6a42b9
formatting
belm0 Apr 27, 2026
ccdc58e
Update Doc/whatsnew/3.15.rst
picnixz Apr 28, 2026
c67dbab
Wrap lines under 80 characters.
picnixz Apr 28, 2026
305ad78
Use `TaskGroup.cancel` in NEWS entry for the link
picnixz Apr 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Doc/library/asyncio-task.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,8 +394,8 @@ Example::
The ``async with`` statement will wait for all tasks in the group to finish.
While waiting, new tasks may still be added to the group
(for example, by passing ``tg`` into one of the coroutines
and calling ``tg.create_task()`` in that coroutine). There is also opportunity
to short-circuit the entire task group with ``tg.cancel()``, based on some condition.
and calling ``tg.create_task()`` in that coroutine). There is also opportunity to
request termination of the entire task group with ``tg.cancel()``, based on some condition.
Once the last task has finished and the ``async with`` block is exited,
no new tasks may be added to the group.

Expand Down
8 changes: 8 additions & 0 deletions Doc/whatsnew/3.15.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -717,6 +717,14 @@ ast
This can be :ref:`controlled using environment variables <using-on-controlling-color>`.
(Contributed by Stan Ulbrych in :gh:`148981`.)

asyncio
-------

* Added :meth:`~asyncio.TaskGroup.cancel` to allow early termination of a task group --
Comment thread
gvanrossum marked this conversation as resolved.
Resolved
e.g. when the goal of the tasks has been achieved or their services no longer needed.
Comment thread
picnixz marked this conversation as resolved.
Resolved
Previously this would involve unintuitive boilerplate such as an extra task raising
a custom exception which is then suppressed as it exits TaskGroup.
(Contributed by John Belmonte in :gh:`127214`.)

base64
Comment thread
picnixz marked this conversation as resolved.
Resolved
------
Expand Down
2 changes: 1 addition & 1 deletion Misc/NEWS.d/next/Library/2024-11-24-07-18-40.gh-issue-108951.jyKygP.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
Add :meth:`~asyncio.TaskGroup.cancel` which cancels unfinished tasks and exits the group without error.
Add :meth:`~asyncio.TaskGroup.cancel` which cancels unfinished tasks and exits the group without raising :exc:`asyncio.CancelledError`.

@agronholm agronholm Apr 26, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'm still not sure if the explicit "and exits the group without raising :exc:asyncio.CancelledError" makes sense. All this does is 1) cancel all current tasks in the group and 2) set the task group into aborted mode which causes creation of further tasks to fail. With that in mind, I'm not sure why you chose to explicitly mention exiting the task group.

@agronholm agronholm Apr 26, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Further, this still begs to question why you said "without raising :exc:asyncio.CancelledError". This implies that otherwise it would raise a CancelledError, yes?

@belm0 belm0 Apr 27, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

well, if you check the long discussions in the impl PR, there was quite a bit made about possible confusion from expecting TaskGroup.cancel() to behave like Task.cancel(). So this is being explicit that unlike the latter, TaskGroup.cancel() does not cause anything to raise CancelledError.

@agronholm agronholm Apr 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think this could be reworded:

Add :meth:~asyncio.TaskGroup.cancel which cancels unfinished tasks in the group and prevents new ones from being created. If this requires cancellation of the host task, the task group will swallow the :exc:asyncio.CancelledError, unless the task was also cancelled from elsewhere.

Thoughts?

Comment thread
picnixz marked this conversation as resolved.
Resolved
Loading