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
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index bac99b7..99f0125 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -387,6 +387,14 @@
# 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 5e0692e..c37f0e1 100644
--- a/Lib/asyncio/tasks.py
+++ b/Lib/asyncio/tasks.py
@@ -729,6 +729,13 @@
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 0000000..a1a1c35
--- /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()