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

Co-authored-by: Alex Grönholm <alex.gronholm@nextday.fi>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index f0fe91b363d95e3f785289e727c9a2b3792bf3d8..2e17d0dc70c7a5c3645643e5cfc5a720455a3982 100644 (file)
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -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.
 

diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
index 6f0f7021de8e7ad5c6bb4249f6a5da33e5b9db99..eb08f8c4ed69e72b2d238f523267dc1a722a0df0 100644 (file)
--- a/Doc/whatsnew/3.15.rst
+++ b/Doc/whatsnew/3.15.rst
@@ -741,6 +741,17 @@ ast
   (Contributed by Stan Ulbrych in :gh:`148981`.)
 
 
+asyncio
+-------
+
+* Added :meth:`TaskGroup.cancel <asyncio.TaskGroup.cancel>` to allow early
+  termination of a task group, for instance, when the goal of the tasks has
+  been achieved or their services are no longer needed.
+  Previously this would involve unintuitive boilerplate such as an extra task
+  raising a custom exception which is then suppressed as it exits the task group.
+  (Contributed by John Belmonte in :gh:`127214`.)
+
+
 base64
 ------
 

diff --git a/Misc/NEWS.d/next/Library/2024-11-24-07-18-40.gh-issue-108951.jyKygP.rst b/Misc/NEWS.d/next/Library/2024-11-24-07-18-40.gh-issue-108951.jyKygP.rst
index 1696a2dd1728edc0934bc72f1524ad479393683e..0e0280c9b6b0e74f6b0b7470aaa723ec34676cb1 100644 (file)
--- a/Misc/NEWS.d/next/Library/2024-11-24-07-18-40.gh-issue-108951.jyKygP.rst
+++ b/Misc/NEWS.d/next/Library/2024-11-24-07-18-40.gh-issue-108951.jyKygP.rst
@@ -1 +1,2 @@
-Add :meth:`~asyncio.TaskGroup.cancel` which cancels unfinished tasks and exits the group without error.
+:mod:`asyncio`: Add :meth:`TaskGroup.cancel <asyncio.TaskGroup.cancel>` which cancels
+unfinished tasks and exits the group without raising :exc:`asyncio.CancelledError`.