Skip to content

Commit 448d070

Browse files
committed
gh-141186: Document asyncio Task cancellation propagation behavior
Clarifies that cancelling a Task awaiting another Task or Future will also cancel the awaited object. This behavior was undocumented despite being fundamental to asyncio's cancellation architecture. Changes: - Updated general Task description to mention Task cancellation propagation - Added explicit explanation in Task.cancel() method documentation - Clarified that Tasks inherit Future's cancellation behavior Addresses issue #141186 where users were unaware this cancellation propagation was intentional architectural behavior, not a side effect. The fix uses the exact wording suggested by the issue reporter and documents the _fut_waiter implementation behavior that enables the propagation down entire await chains.
1 parent d13ee0a commit 448d070

File tree

1 file changed

+6
-2
lines changed

1 file changed

+6
-2
lines changed

Doc/library/asyncio-task.rst

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1221,8 +1221,8 @@ Task Object
12211221

12221222
To cancel a running Task use the :meth:`cancel` method. Calling it
12231223
will cause the Task to throw a :exc:`CancelledError` exception into
1224-
the wrapped coroutine. If a coroutine is awaiting on a Future
1225-
object during cancellation, the Future object will be cancelled.
1224+
the wrapped coroutine. If a coroutine is awaiting on a future-like
1225+
object during cancellation, the awaited object will be cancelled.
12261226

12271227
:meth:`cancelled` can be used to check if the Task was cancelled.
12281228
The method returns ``True`` if the wrapped coroutine did not
@@ -1411,6 +1411,10 @@ Task Object
14111411
the cancellation, it needs to call :meth:`Task.uncancel` in addition
14121412
to catching the exception.
14131413

1414+
If the Task being cancelled is currently awaiting on a future-like
1415+
object, that awaited object will also be cancelled. This cancellation
1416+
propagates down the entire chain of awaited objects.
1417+
14141418
.. versionchanged:: 3.9
14151419
Added the *msg* parameter.
14161420

0 commit comments

Comments
 (0)