From 58f59a962180123a6d29ece512d198b365726b33 Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Mon, 20 Jul 2020 02:00:51 -0700 Subject: [PATCH] bpo-37703: improve asyncio.gather documentation regarding cancellation (GH-15312) These changes updates the doc to comprehensively mention the behaviour of gather.cancel() Automerge-Triggered-By: @asvetlov (cherry picked from commit d42528a3a2c7d79fd2e6c9f2a02f3ce12d44c8cc) Co-authored-by: Vinay Sharma --- Doc/library/asyncio-task.rst | 8 ++++++++ Lib/asyncio/tasks.py | 7 +++++++ .../2019-08-16-20-25-42.bpo-37703.Qm_l_H.rst | 2 ++ 3 files changed, 17 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2019-08-16-20-25-42.bpo-37703.Qm_l_H.rst diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 00ce5d4b72bd..c96dde2dde92 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -385,6 +385,14 @@ Running Tasks Concurrently # Task C: Compute factorial(4)... # Task C: factorial(4) = 24 + .. note:: + If *return_exceptions* is False, cancelling gather() after it + has been marked done won't cancel any submitted awaitables. + For instance, gather can be marked done after propagating an + exception to the caller, therefore, calling ``gather.cancel()`` + after catching an exception (raised by one of the awaitables) from + gather won't cancel any other awaitables. + .. versionchanged:: 3.7 If the *gather* itself is cancelled, the cancellation is propagated regardless of *return_exceptions*. diff --git a/Lib/asyncio/tasks.py b/Lib/asyncio/tasks.py index 38d982716d46..66e81f9200a3 100644 --- a/Lib/asyncio/tasks.py +++ b/Lib/asyncio/tasks.py @@ -736,6 +736,13 @@ def gather(*coros_or_futures, loop=None, return_exceptions=False): the outer Future is *not* cancelled in this case. (This is to prevent the cancellation of one child to cause other children to be cancelled.) + + If *return_exceptions* is False, cancelling gather() after it + has been marked done won't cancel any submitted awaitables. + For instance, gather can be marked done after propagating an + exception to the caller, therefore, calling ``gather.cancel()`` + after catching an exception (raised by one of the awaitables) from + gather won't cancel any other awaitables. """ if not coros_or_futures: if loop is None: diff --git a/Misc/NEWS.d/next/Documentation/2019-08-16-20-25-42.bpo-37703.Qm_l_H.rst b/Misc/NEWS.d/next/Documentation/2019-08-16-20-25-42.bpo-37703.Qm_l_H.rst new file mode 100644 index 000000000000..a1a1c354b168 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-08-16-20-25-42.bpo-37703.Qm_l_H.rst @@ -0,0 +1,2 @@ +Updated Documentation to comprehensively elaborate on the behaviour of +gather.cancel() -- 2.47.3