https://github.com/python/cpython/commit/d2deb8fdef1ac5e54564448677cdb1522f1b776d
commit: d2deb8fdef1ac5e54564448677cdb1522f1b776d
branch: main
author: Stan Ulbrych <[email protected]>
committer: hugovk <[email protected]>
date: 2025-10-09T12:34:35+03:00
summary:
gh-101100: Fix reference warnings in `c-api/init.rst` documenting
`PyGILState_STATE` (#139572)
files:
M Doc/c-api/init.rst
M Doc/tools/.nitignore
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index ccf85e627f9b5f..7a501ea22be64b 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1113,7 +1113,7 @@ code, or when embedding the Python interpreter:
This function is safe to call without an :term:`attached thread state`; it
will simply return ``NULL`` indicating that there was no prior thread state.
- .. seealso:
+ .. seealso::
:c:func:`PyEval_ReleaseThread`
.. note::
@@ -1124,6 +1124,19 @@ code, or when embedding the Python interpreter:
The following functions use thread-local storage, and are not compatible
with sub-interpreters:
+.. c:type:: PyGILState_STATE
+
+ The type of the value returned by :c:func:`PyGILState_Ensure` and passed to
+ :c:func:`PyGILState_Release`.
+
+ .. c:enumerator:: PyGILState_LOCKED
+
+ The GIL was already held when :c:func:`PyGILState_Ensure` was called.
+
+ .. c:enumerator:: PyGILState_UNLOCKED
+
+ The GIL was not held when :c:func:`PyGILState_Ensure` was called.
+
.. c:function:: PyGILState_STATE PyGILState_Ensure()
Ensure that the current thread is ready to call the Python C API regardless
@@ -1174,12 +1187,12 @@ with sub-interpreters:
made on the main thread. This is mainly a helper/diagnostic function.
.. note::
- This function does not account for :term:`thread states <thread state>`
created
- by something other than :c:func:`PyGILState_Ensure` (such as
:c:func:`PyThreadState_New`).
+ This function may return non-``NULL`` even when the :term:`thread state`
+ is detached.
Prefer :c:func:`PyThreadState_Get` or
:c:func:`PyThreadState_GetUnchecked`
for most cases.
- .. seealso: :c:func:`PyThreadState_Get``
+ .. seealso:: :c:func:`PyThreadState_Get`
.. c:function:: int PyGILState_Check()
@@ -1278,11 +1291,11 @@ All of the following functions must be called after
:c:func:`Py_Initialize`.
must be :term:`attached <attached thread state>`
.. versionchanged:: 3.9
- This function now calls the :c:member:`PyThreadState.on_delete` callback.
+ This function now calls the :c:member:`!PyThreadState.on_delete`
callback.
Previously, that happened in :c:func:`PyThreadState_Delete`.
.. versionchanged:: 3.13
- The :c:member:`PyThreadState.on_delete` callback was removed.
+ The :c:member:`!PyThreadState.on_delete` callback was removed.
.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 4ee09c6bbaa069..827c5808fa5865 100644
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -4,7 +4,6 @@
Doc/c-api/descriptor.rst
Doc/c-api/float.rst
-Doc/c-api/init.rst
Doc/c-api/init_config.rst
Doc/c-api/intro.rst
Doc/c-api/module.rst
_______________________________________________
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]
