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#141247
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
Closed
mohsinm-dev wants to merge4 commits intopython:mainfrommohsinm-dev:fix-gh-141186-task-cancellation-docs
Closed
gh-141186: Document asyncio Task cancellation propagation behavior#141247
mohsinm-dev wants to merge4 commits intopython:mainfrommohsinm-dev:fix-gh-141186-task-cancellation-docs
+15 −7
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
Changed "Objects of different types, except different numeric types, nevercompare equal" to "Objects of different types, unless documented otherwise,never compare equal" to account for documented exceptions like set/frozensetcomparisons.
The acquire() method documentation stated 'Exactly one thread will be awokenby each call to release()' which became incorrect when the n parameter wasadded to release() in Python 3.9.The release() method documentation was ambiguous about behavior whenn > waiting_threads.Changes:- acquire(): Updated to reflect that release(n) wakes min(j,n) threads where j = waiting threads- release(): Clarified that it wakes 'up to n' threads, or all available if fewer than n are waitingThe fix aligns documentation with actual implementation behavior inLib/threading.py where release(n) calls Condition.notify(n).
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.
Member
StanFromIreland left a comment
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 seem to have changes for three different issues in this PR, please remove the unrelated ones.
Author
mohsinm-dev commentedNov 8, 2025
Closing this PR due to mixed commits from multiple issues. Will create a clean PR with only the asyncio changes. |
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
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.
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--141247.org.readthedocs.build/