From 81931c7c537eef3c4da53feacafecf7d54414e64 Mon Sep 17 00:00:00 2001 From: mohsinm-dev Date: Sat, 8 Nov 2025 10:24:23 +0500 Subject: [PATCH 1/4] gh-141218: Fix inaccurate object comparison documentation 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. --- Doc/library/stdtypes.rst | 2 +- .../2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 97e7e08364e0bd..e329fe271b2ab4 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -164,7 +164,7 @@ This table summarizes the comparison operations: pair: object; numeric pair: objects; comparing -Objects of different types, except different numeric types, never compare equal. +Objects of different types, unless documented otherwise, never compare equal. The ``==`` operator is always defined but for some object types (for example, class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=`` operators are only defined where they make sense; for example, they raise a diff --git a/Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst b/Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst new file mode 100644 index 00000000000000..78662ce0e2c0a8 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst @@ -0,0 +1,4 @@ +Fix inaccurate documentation about object comparison. 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. \ No newline at end of file From 37bb2829691d018e4e57ac19edd9bb479bd3f2ca Mon Sep 17 00:00:00 2001 From: mohsinm-dev Date: Sat, 8 Nov 2025 18:04:45 +0500 Subject: [PATCH 2/4] Remove news entry for documentation-only change --- .../2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst | 4 ---- 1 file changed, 4 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst diff --git a/Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst b/Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst deleted file mode 100644 index 78662ce0e2c0a8..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2025-11-08-12-00-00.gh-issue-141218.kL3mNx.rst +++ /dev/null @@ -1,4 +0,0 @@ -Fix inaccurate documentation about object comparison. 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. \ No newline at end of file From 372b843ed650372bf6f93d1b9a23ba994b070788 Mon Sep 17 00:00:00 2001 From: mohsinm-dev Date: Sat, 8 Nov 2025 18:24:05 +0500 Subject: [PATCH 3/4] gh-141196: Fix threading.Semaphore documentation inconsistency 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). --- Doc/library/threading.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 19cc4f191dff8d..b149a222115ec4 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -1144,9 +1144,11 @@ Semaphores also support the :ref:`context management protocol `. one and return ``True`` immediately. * If the internal counter is zero on entry, block until awoken by a call to :meth:`~Semaphore.release`. Once awoken (and the counter is greater - than 0), decrement the counter by 1 and return ``True``. Exactly one - thread will be awoken by each call to :meth:`~Semaphore.release`. The - order in which threads are awoken should not be relied on. + than 0), decrement the counter by 1 and return ``True``. Each call to + :meth:`~Semaphore.release` will wake up threads according to its *n* + parameter (default 1): if *j* threads are waiting and ``release(n)`` + is called, ``min(j, n)`` threads will be awoken. The order in which + threads are awoken should not be relied on. When invoked with *blocking* set to ``False``, do not block. If a call without an argument would block, return ``False`` immediately; otherwise, do @@ -1166,7 +1168,8 @@ Semaphores also support the :ref:`context management protocol `. Release a semaphore, incrementing the internal counter by *n*. When it was zero on entry and other threads are waiting for it to become larger - than zero again, wake up *n* of those threads. + than zero again, wake up to *n* of those threads (or all of them if + fewer than *n* are waiting). .. versionchanged:: 3.9 Added the *n* parameter to release multiple waiting threads at once. From 61deac8280be93e9aab2bbae55ff30ad9cf318b4 Mon Sep 17 00:00:00 2001 From: mohsinm-dev Date: Sat, 8 Nov 2025 19:28:29 +0500 Subject: [PATCH 4/4] gh-141186: Document asyncio Task cancellation propagation behavior 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 #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. --- Doc/library/asyncio-task.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index f825ae92ec7471..18f4476e367904 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -1222,7 +1222,7 @@ Task Object To cancel a running Task use the :meth:`cancel` method. Calling it 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, the Future object will be cancelled. + or Task object during cancellation, the awaited object will be cancelled. :meth:`cancelled` can be used to check if the Task was cancelled. The method returns ``True`` if the wrapped coroutine did not @@ -1231,7 +1231,8 @@ Task Object :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 + behavior: Tasks can be cancelled in the same way as Futures. An optional keyword-only *context* argument allows specifying a custom :class:`contextvars.Context` for the *coro* to run in. @@ -1410,6 +1411,10 @@ Task Object discouraged. Should the coroutine nevertheless decide to suppress 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 + Future, that awaited object will also be cancelled. This cancellation + propagates down the entire chain of awaited objects. .. versionchanged:: 3.9 Added the *msg* parameter.