gh-141186: Document asyncio Task cancellation propagation behavior #141247
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, never compare equal" to "Objects of different types, unless documented otherwise, never compare equal" to account for documented exceptions like set/frozenset comparisons.
The acquire() method documentation stated 'Exactly one thread will be awoken by each call to release()' which became incorrect when the n parameter was added to release() in Python 3.9. The release() method documentation was ambiguous about behavior when n > 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 waiting The fix aligns documentation with actual implementation behavior in Lib/threading.py where release(n) calls Condition.notify(n).
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
requested review from
1st1,
asvetlov,
kumaraditya303 and
willingc
as code owners
bedevere-app
bot
added
awaiting review
docs
Member
StanFromIreland
left a comment
StanFromIreland
left a comment
There was a problem hiding this comment.
You seem to have changes for three different issues in this PR, please remove the unrelated ones.
Contributor
Author
|
Closing this PR due to mixed commits from multiple issues. Will create a clean PR with only the asyncio changes. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 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--141247.org.readthedocs.build/