gh-141186: Document asyncio Task cancellation propagation behavior #141249
+6
−2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mohsinm-dev
requested review from
1st1,
asvetlov,
kumaraditya303 and
willingc
as code owners
bedevere-app
bot
added
awaiting review
docs
Doc/library/asyncio-task.rst
Outdated
| discouraged. Should the coroutine nevertheless decide to suppress | ||
| the cancellation, it needs to call :meth:`Task.uncancel` in addition | ||
| to catching the exception. | ||
|
|
Member
There was a problem hiding this comment.
You have trailing whitespace here.
Contributor
Author
There was a problem hiding this comment.
Just removed it.
mohsinm-dev
force-pushed
the
fix-gh-141186-asyncio-only
branch
from
743e34a to
f4bb1e8
Compare
Doc/library/asyncio-task.rst
Outdated
| 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. | ||
| or Task object during cancellation, the awaited object will be cancelled. |
Contributor
There was a problem hiding this comment.
It actually supports any future-like objects, you can say it like "if coroutine is awaiting on future-like object then that will be cancelled", with sphinx markers as necessary
Doc/library/asyncio-task.rst
Outdated
| the cancellation, it needs to call :meth:`Task.uncancel` in addition | ||
| to catching the exception. | ||
|
|
||
| If the Task being cancelled is currently awaiting another Task or |
mohsinm-dev
force-pushed
the
fix-gh-141186-asyncio-only
branch
from
f4bb1e8 to
2811031
Compare
Doc/library/asyncio-task.rst
Outdated
| :class:`asyncio.Task` inherits from :class:`Future` all of its | ||
| APIs except :meth:`Future.set_result` and | ||
| :meth:`Future.set_exception`. | ||
| :meth:`Future.set_exception`. This includes the cancellation |
Contributor
There was a problem hiding this comment.
This is redundant, the exceptions are already noted rest are same by default
Doc/library/asyncio-task.rst
Outdated
| the cancellation, it needs to call :meth:`Task.uncancel` in addition | ||
| to catching the exception. | ||
|
|
||
| If the Task being cancelled is currently awaiting a future-like |
Contributor
There was a problem hiding this comment.
Suggested change
| If the Task being cancelled is currently awaiting a future-like | |
| If the Task being cancelled is currently awaiting on a future-like |
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 python#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.
mohsinm-dev
force-pushed
the
fix-gh-141186-asyncio-only
branch
from
2811031 to
448d070
Compare
kumaraditya303
approved these changes
Nov 8, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes issue #141186 by documenting that cancelling a Task cancels what it's waiting for.
Problem
The docs said cancelling a coroutine waiting on a Future cancels the Future, but didn't mention this also happens with Tasks. Users didn't know Tasks work the same way.
Solution
Testing
Ran the exact code from the issue - it works as expected. Tested multiple scenarios to confirm the behavior.
Documentation-only change. No code was modified.
📚 Documentation preview 📚: https://cpython-previews--141249.org.readthedocs.build/