Move PyStatus to rejected ideas.

Author: ZeroIntensity

peps/pep-0788.rst

@@ -234,26 +234,15 @@ Rationale
 This PEP includes several new APIs that intend to fix all of the issues stated
 above.
 
-Bikeshedding and the ``PyThreadState`` namespace
-------------------------------------------------
-
-To solve the issue with "GIL" terminology, the new functions described by this
-PEP intended as replacements for ``PyGILState`` will go under the existing
-``PyThreadState`` namespace. In Python 3.14, the documentation has been
-updated to switch over to terms like
-:term:`"attached thread state" <attached thread state>` instead of
-:term:`"global interpreter lock" <global interpreter lock>`, so this namespace
-seems to fit well for the functions in this PEP.
-
-Full deprecation of old APIs
-----------------------------
+Replacing the old APIs
+----------------------
 
 As made clear in Motivation_, ``PyGILState`` is already pretty buggy, and
 even if it was magically fixed, the current behavior of hanging the thread is
-beyond repair. As such, this PEP intends to completely deprecate the existing
-``PyGILState`` APIs. However, even if this PEP is rejected, all of the APIs
-can be replaced with more correct ``PyThreadState`` functions in the current
-C API:
+beyond repair. In turn, this PEP intends to completely deprecate the existing
+``PyGILState`` APIs and provide better alternatives. However, even if this PEP
+is rejected, all of the APIs can be replaced with more correct ``PyThreadState``
+functions in the current C API:
 
 - :c:func:`PyGILState_Ensure`: :c:func:`PyThreadState_Swap` / :c:func:`PyThreadState_New`
 - :c:func:`PyGILState_Release`: :c:func:`PyThreadState_Clear` / :c:func:`PyThreadState_Delete`
@@ -263,12 +252,23 @@ C API:
 A light layer of magic
 ----------------------
 
-The APIs proposed by this PEP intentionally have a layer of "magic" that is
-kept from the user and offloads complexity onto CPython maintainers. This is
-done primarily to help ease the transition from ``PyGILState`` for existing
+The APIs proposed by this PEP intentionally have a layer of abstraction that is
+hidden from the user and offloads complexity onto CPython. This is done
+primarily to help ease the transition from ``PyGILState`` for existing
 codebases, and for ease-of-use to those who provide wrappers the C API, such
 as Cython or PyO3. See also :ref:`pep-788-activate-deactivate-instead`.
 
+Bikeshedding and the ``PyThreadState`` namespace
+------------------------------------------------
+
+To solve the issue with "GIL" terminology, the new functions described by this
+PEP intended as replacements for ``PyGILState`` will go under the existing
+``PyThreadState`` namespace. In Python 3.14, the documentation has been
+updated to switch over to terms like
+:term:`"attached thread state" <attached thread state>` instead of
+:term:`"global interpreter lock" <global interpreter lock>`, so this namespace
+seems to fit well for this PEP.
+
 Specification
 =============
 
@@ -297,12 +297,14 @@ prevent the interpreter from finalizing.
     This function is generally meant to be used in tandem with
     :c:func:`PyThreadState_Ensure`.
 
-    The caller must have an :term:`attached thread state`.
+    The caller must have an :term:`attached thread state`, and cannot return
+    ``NULL``. Failures are always a fatal error.
 
 
 .. c:function:: void PyInterpreterState_Release(PyInterpreterState *interp)
 
-    Decrement the reference count of the interpreter.
+    Decrement the reference count of the interpreter, as was incremented by
+    :c:func:`PyInterpreterState_Hold`.
 
     This function cannot fail, other than with a fatal error. The caller must
     have an :term:`attached thread state` for *interp*.
@@ -352,18 +354,20 @@ replace :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release`.
 
 .. c:function:: int PyThreadState_Ensure(PyInterpreterState *interp)
 
-    Ensure that the thread has an :term:`attached thread state` for *interp*, and
-    thus can safely invoke that interpreter. It is OK to call this function if
-    the thread already has an attached thread state, as long as there is a
-    subsequent call to :c:func:`PyThreadState_Release` that matches this one.
+    Ensure that the thread has an :term:`attached thread state` for *interp*,
+    and thus can safely invoke that interpreter. It is OK to call this
+    function if the thread already has an attached thread state, as long as
+    there is a subsequent call to :c:func:`PyThreadState_Release` that matches
+    this one.
 
-    The interpreter's *interp* reference count is decremented by one. As such, *interp*
-    should have been acquired by :c:func:`PyInterpreterState_Hold`.
+    The interpreter's *interp* reference count is decremented by one.
+    As such, *interp* should have been acquired by
+    :c:func:`PyInterpreterState_Hold`.
 
     Thread states created by this function are non-daemon by default. See
     :c:func:`PyThreadState_SetDaemon`. If the calling thread already has an
-    :term:`attached thread state` that matches *interp*, then this function will
-    simply mark the existing thread state as non-daemon and return. It will
+    :term:`attached thread state` that matches *interp*, then this function
+    will mark the existing thread state as non-daemon and return. It will
     be restored to its prior daemon status upon the next
     :c:func:`PyThreadState_Release` call.
 
@@ -594,24 +598,26 @@ This was ultimately rejected for two reasons:
    for code-generators like Cython to use, as there isn't any additional
    complexity with tracking :c:type:`PyThreadState` pointers around.
 
-Open Issues
-===========
+Using ``PyStatus`` for the return value of :c:func:`PyThreadState_Ensure`
+-------------------------------------------------------------------------
 
-Use ``PyStatus`` for the return value of :c:func:`PyThreadState_Ensure`?
-------------------------------------------------------------------------
+In prior iterations of this API, :c:func:`PyThreadState_Ensure` returned a
+:c:type:`PyStatus` instead of an integer to denote failures, which had the
+benefit of providing an error message.
 
-:c:func:`PyThreadState_Ensure` returns an integer to return failures, but some
-iterations have suggested the use of :c:type:`PyStatus` to denote failure,
-which has the benefit of providing an error message. The main hesitation for
-switching to ``PyStatus`` is that it's more difficult to use, as the
-``PyStatus`` has to be stored and checked, whereas a simple integer can simply
-be used inline with an ``if`` clause.
-
-Additionally, it's
-`not clear <https://discuss.python.org/t/83959/7>`_
+This was rejected because it's `not clear <https://discuss.python.org/t/83959/7>`_
 that an error message would be all that useful; all the conceived use-cases
-for this API wouldn't really care about a message indicating why Python can't
-be invoked.
+for this API wouldn't really care about a message indicating why Python
+can't be invoked. As such, the API would only be needlessly harder to use,
+which in turn would hurt the transition from :c:func:`PyGILState_Ensure`.
+
+In addition, :c:type:`PyStatus` isn't commonly used in the C API. A few
+functions related to interpreter initialization use it (simply because they
+can't raise exceptions), and :c:func:`PyThreadState_Ensure` does not fall
+under that category.
+
+Open Issues
+===========
 
 When should the legacy APIs be removed?
 ---------------------------------------