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 d42528a3a2)

Co-authored-by: Vinay Sharma <vinay04sharma@icloud.com>
This commit is contained in:
Miss Islington (bot) 2020-07-20 02:00:51 -07:00 committed by GitHub
parent 892fc8d328
commit 58f59a9621
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 17 additions and 0 deletions

View File

@ -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*.

View File

@ -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:

View File

@ -0,0 +1,2 @@
Updated Documentation to comprehensively elaborate on the behaviour of
gather.cancel()