Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork33.3k
gh-141186: Document asyncio Task cancellation propagation behavior#141249
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Conversation
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. | ||
StanFromIrelandNov 8, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
You have trailing whitespace here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Just removed it.
743e34a tof4bb1e8CompareDoc/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, theFuture object will be cancelled. | ||
| or Taskobject during cancellation, theawaited object will be cancelled. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Same
f4bb1e8 to2811031CompareDoc/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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| If the Task being cancelled is currently awaiting a future-like | |
| If the Task being cancelled is currently awaitingona future-like |
Clarifies that cancelling a Task awaiting another Task or Future willalso cancel the awaited object. This behavior was undocumented despitebeing 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 behaviorAddresses issuepython#141186 where users were unaware this cancellationpropagation was intentional architectural behavior, not a side effect.The fix uses the exact wording suggested by the issue reporter anddocuments the _fut_waiter implementation behavior that enables thepropagation down entire await chains.
2811031 to448d070Compareb36f01d intopython:mainUh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
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/