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 d42528a) Co-authored-by: Vinay Sharma <vinay04sharma@icloud.com>

Author: miss-islington

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

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:

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