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.

Updated acquire() docs to reflect that release(n) wakes min(j,n) threads where j = waiting threads, and clarified release() docs to specify 'up to n threads' are awakened.

The fix aligns documentation with actual behavior: Semaphore.release(n) calls Condition.notify(n), which wakes exactly min(n, waiting_threads) threads.

Documentation-only change, no code modifications required.

Issue:threading.Semaphore documentation is not internally consistent #141196

📚 Documentation preview 📚:https://cpython-previews--141244.org.readthedocs.build/

mohsinm-dev added3 commits

November 8, 2025 10:24

pythongh-141218: Fix inaccurate object comparison documentation

81931c7

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.

Remove news entry for documentation-only change

37bb282

pythongh-141196: Fix threading.Semaphore documentation inconsistency

372b843

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).