gh-141186: Document asyncio Task cancellation propagation behavior by mohsinm-dev · Pull Request #141247 · python/cpython

added 4 commits

November 8, 2025 10:24
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.

StanFromIreland