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@icloud.com>

1 files changed, 7 insertions, 0 deletions

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