Skip to content

gh-144277: Fix usage of free-threaded terminology in the documentation #144333

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
ZeroIntensity wants to merge 4 commits into
base: main
Choose a base branch
from
+19 −12
Open

gh-144277: Fix usage of free-threaded terminology in the documentation #144333

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
58161c7
Add a "free-threaded build" term.
ZeroIntensity Jan 30, 2026
c45a3ef
Use the term in a bunch of places.
ZeroIntensity Jan 30, 2026
a5c6c98
Fix a few other instances.
ZeroIntensity Jan 30, 2026
4ee440f
Fix Sphinx errors.
ZeroIntensity Jan 30, 2026
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
8 changes: 4 additions & 4 deletions Doc/c-api/object.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -711,10 +711,10 @@ Object Protocol

:c:func:`PyUnstable_EnableTryIncRef` must have been called
earlier on *obj* or this function may spuriously return ``0`` in the
:term:`free threading` build.
:term:`free-threaded build`.

This function is logically equivalent to the following C code, except that
it behaves atomically in the :term:`free threading` build::
it behaves atomically in the :term:`free-threaded build`::

if (Py_REFCNT(op) > 0) {
Py_INCREF(op);
Expand Down Expand Up @@ -791,10 +791,10 @@ Object Protocol
On GIL-enabled builds, this function is equivalent to
:c:expr:`Py_REFCNT(op) == 1`.

On a :term:`free threaded <free threading>` build, this checks if *op*'s
On a :term:`free-threaded build`, this checks if *op*'s
:term:`reference count` is equal to one and additionally checks if *op*
is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not**
thread-safe on free threaded builds; prefer this function.
thread-safe on free-threaded builds; prefer this function.

The caller must hold an :term:`attached thread state`, despite the fact
that this function doesn't call into the Python interpreter. This function
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/refcounting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ of Python objects.

.. note::

On :term:`free threaded <free threading>` builds of Python, returning 1
On :term:`free-threaded builds <free-threaded build>` of Python, returning 1
isn't sufficient to determine if it's safe to treat *o* as having no
access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced`
for that instead.
Expand Down
13 changes: 10 additions & 3 deletions Doc/glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,9 +160,9 @@ Glossary
On most builds of Python, having an attached thread state implies that the
caller holds the :term:`GIL` for the current interpreter, so only
one OS thread can have an attached thread state at a given moment. In
:term:`free-threaded <free threading>` builds of Python, threads can concurrently
hold an attached thread state, allowing for true parallelism of the bytecode
interpreter.
:term:`free-threaded builds <free-threaded build>` of Python, threads can
concurrently hold an attached thread state, allowing for true parallelism of
the bytecode interpreter.

attribute
A value associated with an object which is usually referenced by name
Expand Down Expand Up @@ -580,6 +580,13 @@ Glossary
the :term:`global interpreter lock` which allows only one thread to
execute Python bytecode at a time. See :pep:`703`.

free-threaded build

A build of :term:`CPython` that supports :term:`free threading`,
configured using the :option:`--disable-gil` option before compilation.

See :ref:`freethreading-python-howto`.

free variable
Formally, as defined in the :ref:`language execution model <bind_names>`, a free
variable is any variable used in a namespace which is not a local variable in that
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/ctypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -896,7 +896,7 @@ invalid non-\ ``NULL`` pointers would crash Python)::
Thread safety without the GIL
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

From Python 3.13 onward, the :term:`GIL` can be disabled on :term:`free threaded <free threading>` builds.
From Python 3.13 onward, the :term:`GIL` can be disabled on the :term:`free-threaded build`.
In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects:

.. code-block:: pycon
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/io.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -720,7 +720,7 @@ than raw I/O does.
contains initial data.

Methods may be used from multiple threads without external locking in
:term:`free threading` builds.
:term:`free-threaded builds <free-threaded build>`.

:class:`BytesIO` provides or overrides these methods in addition to those
from :class:`BufferedIOBase` and :class:`IOBase`:
Expand Down
2 changes: 1 addition & 1 deletion Doc/library/site.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ For the head part, it uses ``sys.prefix`` and ``sys.exec_prefix``; empty heads
are skipped. For the tail part, it uses the empty string and then
:file:`lib/site-packages` (on Windows) or
:file:`lib/python{X.Y[t]}/site-packages` (on Unix and macOS). (The
optional suffix "t" indicates the :term:`free threading` build, and is
optional suffix "t" indicates the :term:`free-threaded build`, and is
appended if ``"t"`` is present in the :data:`sys.abiflags` constant.)
For each
of the distinct head-tail combinations, it sees if it refers to an existing
Expand Down
2 changes: 1 addition & 1 deletion Doc/using/configure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -421,7 +421,7 @@ General Options
:no-typesetting:

Enables support for running Python without the :term:`global interpreter
lock` (GIL): free threading build.
lock` (GIL): :term:`free-threaded build`.

Defines the ``Py_GIL_DISABLED`` macro and adds ``"t"`` to
:data:`sys.abiflags`.
Expand Down
Loading