https://github.com/python/cpython/commit/3a0e1835563e6acfa3059a7d9777260cb2b6717d
commit: 3a0e1835563e6acfa3059a7d9777260cb2b6717d
branch: main
author: Peter Bierma <[email protected]>
committer: ZeroIntensity <[email protected]>
date: 2026-02-01T20:39:26-05:00
summary:
gh-144277: Fix usage of free-threaded terminology in the documentation
(GH-144333)
files:
M Doc/c-api/object.rst
M Doc/c-api/refcounting.rst
M Doc/glossary.rst
M Doc/library/ctypes.rst
M Doc/library/io.rst
M Doc/library/site.rst
M Doc/using/configure.rst
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 127b50ac479638..992a4383f97241 100644
--- a/Doc/c-api/object.rst
+++ b/Doc/c-api/object.rst
@@ -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);
@@ -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
diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst
index 57a0728d4e9af4..4d56a92bf2af79 100644
--- a/Doc/c-api/refcounting.rst
+++ b/Doc/c-api/refcounting.rst
@@ -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.
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 68035c2dfb57d4..7c41f5bc27b070 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -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
@@ -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
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
index 6038af99009d02..d2f4da08327323 100644
--- a/Doc/library/ctypes.rst
+++ b/Doc/library/ctypes.rst
@@ -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
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index dfebccb5a9cb91..d1a9132db81602 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -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`:
diff --git a/Doc/library/site.rst b/Doc/library/site.rst
index d93e4dc7c75f1a..ca2ac3b0098c46 100644
--- a/Doc/library/site.rst
+++ b/Doc/library/site.rst
@@ -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
diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 26322045879cb2..50812358a690c3 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -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`.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
