From b36f01d03f8f89cadd8436a7261ca29e4030d30c Mon Sep 17 00:00:00 2001
From: Mohsin Mehmood <55545648+mohsinm-dev@users.noreply.github.com>
Date: Sun, 9 Nov 2025 09:49:29 +0500
Subject: [PATCH] gh-141186: document `asyncio.Task` cancellation propagation
 behavior (#141249)

---
 Doc/library/asyncio-task.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index f825ae92ec7..863b3e33657 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -1221,8 +1221,8 @@ Task Object
 
    To cancel a running Task use the :meth:`cancel` method.  Calling it
    will cause the Task to throw a :exc:`CancelledError` exception into
-   the wrapped coroutine.  If a coroutine is awaiting on a Future
-   object during cancellation, the Future object will be cancelled.
+   the wrapped coroutine.  If a coroutine is awaiting on a future-like
+   object during cancellation, the awaited object will be cancelled.
 
    :meth:`cancelled` can be used to check if the Task was cancelled.
    The method returns ``True`` if the wrapped coroutine did not
@@ -1411,6 +1411,10 @@ Task Object
       the cancellation, it needs to call :meth:`Task.uncancel` in addition
       to catching the exception.
 
+      If the Task being cancelled is currently awaiting on a future-like
+      object, that awaited object will also be cancelled. This cancellation
+      propagates down the entire chain of awaited objects.
+
       .. versionchanged:: 3.9
          Added the *msg* parameter.