Skip to content

gh-89554: Document _thread.LockType as a class #150684

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gaborbernat wants to merge 1 commit into
base: main
Choose a base branch
from
+41 −38
Open

gh-89554: Document _thread.LockType as a class #150684

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 41 additions & 38 deletions Doc/library/_thread.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -162,58 +157,66 @@ This module defines the following constants and functions:
.. versionadded:: 3.2


Lock objects have the following methods:
.. raw:: html

<!-- Keep the old URL fragments working (see gh-89554) -->
<span id='thread.lock.acquire'></span>
<span id='thread.lock.release'></span>
<span id='thread.lock.locked'></span>

.. class:: LockType

.. method:: lock.acquire(blocking=True, timeout=-1)
This is the type of lock objects.

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).
Lock objects have the following methods:

Copy link
Copy Markdown
Member

@vstinner vstinner Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You should add an indentation of 3 spaces on the methods below, and replace .. method:: lock.xxx(...) with .. method:: xxx(...) (remove the lock. prefix).

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.
.. method:: acquire(blocking=True, timeout=-1)

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

The return value is ``True`` if the lock is acquired successfully,
``False`` if not.
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
The *timeout* parameter is new.
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.2
Lock acquires can now be interrupted by signals on POSIX.
The return value is ``True`` if the lock is acquired successfully,
``False`` if not.

.. versionchanged:: 3.14
Lock acquires can now be interrupted by signals on Windows.
.. versionchanged:: 3.2
The *timeout* parameter is new.

.. versionchanged:: 3.2
Lock acquires can now be interrupted by signals on POSIX.

.. method:: lock.release()
.. versionchanged:: 3.14
Lock acquires can now be interrupted by signals on Windows.

Releases the lock. The lock must have been acquired earlier, but not
necessarily by the same thread.
.. method:: release()

Releases the lock. The lock must have been acquired earlier, but not
necessarily by the same thread.

.. method:: lock.locked()
.. method:: locked()

Return the status of the lock: ``True`` if it has been acquired by some thread,
``False`` if not.
Return the status of the lock: ``True`` if it has been acquired by some thread,
``False`` if not.

In addition to these methods, lock objects can also be used via the
:keyword:`with` statement, e.g.::
In addition to these methods, lock objects can also be used via the
:keyword:`with` statement, e.g.::

import _thread
import _thread

a_lock = _thread.allocate_lock()
a_lock = _thread.allocate_lock()

with a_lock:
print("a_lock is locked while this executes")
with a_lock:
print("a_lock is locked while this executes")

**Caveats:**

Expand Down
Loading