[Python-checkins] bpo-37703: improve asyncio.gather documentation regarding cancellation (GH-15312)

[Miss Islington (bot)]

https://github.com/python/cpython/commit/58f59a962180123a6d29ece512d198b365726b33
commit: 58f59a962180123a6d29ece512d198b365726b33
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2020-07-20T02:00:51-07:00
summary:

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 <vinay04sharma at icloud.com>

files:
A Misc/NEWS.d/next/Documentation/2019-08-16-20-25-42.bpo-37703.Qm_l_H.rst
M Doc/library/asyncio-task.rst
M Lib/asyncio/tasks.py

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 00ce5d4b72bdd..c96dde2dde925 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 38d982716d46a..66e81f9200a36 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 0000000000000..a1a1c354b1688
--- /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()