From e37ce569773b5e4e5c0e6042d4adfde2e9608f13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Tue, 2 Jun 2026 05:55:01 -0700 Subject: [PATCH] gh-89554: Document _thread.LockType as a class (#150684) _thread.LockType is a class (the type of lock objects), but was documented with the ".. data::" directive, so ":class:" cross-references to it cannot resolve against a py:class target. Switch the entry to ".. class::", move it next to the lock methods, and document acquire(), release() and locked() as methods of the class. Keep the old _thread.lock.* URL fragments working with raw HTML anchors. --- Doc/library/_thread.rst | 79 +++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 38 deletions(-) diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst index 47f5eabb6f2..13f463a1e95 100644 --- a/Doc/library/_thread.rst +++ b/Doc/library/_thread.rst @@ -36,11 +36,6 @@ This module defines the following constants and functions: This is now a synonym of the built-in :exc:`RuntimeError`. -.. data:: LockType - - This is the type of lock objects. - - .. function:: start_new_thread(function, args[, kwargs]) Start a new thread and return its identifier. The thread executes the @@ -162,58 +157,66 @@ This module defines the following constants and functions: .. versionadded:: 3.2 -Lock objects have the following methods: +.. raw:: html + + + + -.. method:: lock.acquire(blocking=True, timeout=-1) +.. class:: LockType - Without any optional argument, this method acquires the lock unconditionally, if - necessary waiting until it is released by another thread (only one thread at a - time can acquire a lock --- that's their reason for existence). + This is the type of lock objects. - If the *blocking* argument is present, the action depends on its - value: if it is false, the lock is only acquired if it can be acquired - immediately without waiting, while if it is true, the lock is acquired - unconditionally as above. + Lock objects have the following methods: - If the floating-point *timeout* argument is present and positive, it - specifies the maximum wait time in seconds before returning. A negative - *timeout* argument specifies an unbounded wait. You cannot specify - a *timeout* if *blocking* is false. + .. method:: acquire(blocking=True, timeout=-1) - The return value is ``True`` if the lock is acquired successfully, - ``False`` if not. + Without any optional argument, this method acquires the lock unconditionally, if + necessary waiting until it is released by another thread (only one thread at a + time can acquire a lock --- that's their reason for existence). - .. versionchanged:: 3.2 - The *timeout* parameter is new. + If the *blocking* argument is present, the action depends on its + value: if it is false, the lock is only acquired if it can be acquired + immediately without waiting, while if it is true, the lock is acquired + unconditionally as above. - .. versionchanged:: 3.2 - Lock acquires can now be interrupted by signals on POSIX. + If the floating-point *timeout* argument is present and positive, it + specifies the maximum wait time in seconds before returning. A negative + *timeout* argument specifies an unbounded wait. You cannot specify + a *timeout* if *blocking* is false. - .. versionchanged:: 3.14 - Lock acquires can now be interrupted by signals on Windows. + The return value is ``True`` if the lock is acquired successfully, + ``False`` if not. + .. versionchanged:: 3.2 + The *timeout* parameter is new. -.. method:: lock.release() + .. versionchanged:: 3.2 + Lock acquires can now be interrupted by signals on POSIX. - Releases the lock. The lock must have been acquired earlier, but not - necessarily by the same thread. + .. versionchanged:: 3.14 + Lock acquires can now be interrupted by signals on Windows. + .. method:: release() -.. method:: lock.locked() + Releases the lock. The lock must have been acquired earlier, but not + necessarily by the same thread. - Return the status of the lock: ``True`` if it has been acquired by some thread, - ``False`` if not. + .. method:: locked() -In addition to these methods, lock objects can also be used via the -:keyword:`with` statement, e.g.:: + Return the status of the lock: ``True`` if it has been acquired by some thread, + ``False`` if not. - import _thread + In addition to these methods, lock objects can also be used via the + :keyword:`with` statement, e.g.:: - a_lock = _thread.allocate_lock() + import _thread - with a_lock: - print("a_lock is locked while this executes") + a_lock = _thread.allocate_lock() + + with a_lock: + print("a_lock is locked while this executes") **Caveats:**