gh-128509: Add PyUnstable_IsImmortal for finding immortal objects

Doc/c-api/object.rst

@@ -613,3 +613,14 @@ Object Protocol
 
    .. versionadded:: 3.14
 
+.. c:function:: int PyUnstable_IsImmortal(PyObject *obj)
+
+   This function returns non-zero if *obj* is :term:`immortal`, and zero
+   otherwise. This function cannot fail.
+
+   .. note::
+
+      Objects that are immortal in one CPython version are not guaranteed to
+      be immortal in another.
+
+   .. versionadded:: next

Doc/whatsnew/3.14.rst

@@ -1321,6 +1321,9 @@ New features
   bit-packing Python version numbers.
   (Contributed by Petr Viktorin in :gh:`128629`.)
 
+* Add :c:func:`PyUnstable_IsImmortal` for determining whether an object is :term:`immortal`,
+  for debugging purposes.
+
 
 Porting to Python 3.14
 ----------------------

Include/cpython/object.h

@@ -541,3 +541,6 @@ PyAPI_FUNC(PyRefTracer) PyRefTracer_GetTracer(void**);
  * 0 if the runtime ignored it. This function cannot fail.
  */
 PyAPI_FUNC(int) PyUnstable_Object_EnableDeferredRefcount(PyObject *);
+
+/* Check whether the object is immortal. This cannot fail. */
+PyAPI_FUNC(int) PyUnstable_IsImmortal(PyObject *);

Lib/test/test_capi/test_immortal.py

@@ -27,6 +27,21 @@ def test_immortal_builtins(self):
         for obj in ([], {}, set()):
             self.assertFalse(_testinternalcapi.is_static_immortal(obj))
 
+    def test_immortal(self):
+        # Not extensive
+        known_immortals = (True, False, None, 0, ())
+        for immortal in known_immortals:
+            with self.subTest(immortal=immortal):
+                self.assertTrue(_testcapi.is_immortal(immortal))
+
+        # Some arbitrary mutable objects
+        non_immortals = (object(), self, [object()])
+        for non_immortal in non_immortals:
+            with self.subTest(non_immortal=non_immortal):
+                self.assertFalse(_testcapi.is_immortal(non_immortal))
+
+        # CRASHES _testcapi.is_immortal(NULL)
+
 
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C_API/2025-01-22-09-28-04.gh-issue-128509.gqQ36L.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyUnstable_IsImmortal` for determining whether an object is
+:term:`immortal`.

Modules/_testcapi/object.c

@@ -131,13 +131,22 @@ pyobject_enable_deferred_refcount(PyObject *self, PyObject *obj)
     return PyLong_FromLong(result);
 }
 
+
+static PyObject *
+is_immortal(PyObject *self, PyObject *op)
+{
+    return PyBool_FromLong(PyUnstable_IsImmortal(op));
+}
+
+
 static PyMethodDef test_methods[] = {
     {"call_pyobject_print", call_pyobject_print, METH_VARARGS},
     {"pyobject_print_null", pyobject_print_null, METH_VARARGS},
     {"pyobject_print_noref_object", pyobject_print_noref_object, METH_VARARGS},
     {"pyobject_print_os_error", pyobject_print_os_error, METH_VARARGS},
     {"pyobject_clear_weakrefs_no_callbacks", pyobject_clear_weakrefs_no_callbacks, METH_O},
     {"pyobject_enable_deferred_refcount", pyobject_enable_deferred_refcount, METH_O},
+    {"is_immortal", is_immortal, METH_O},
     {NULL},
 };
 

Objects/object.c

@@ -3155,3 +3155,12 @@ Py_REFCNT(PyObject *ob)
 {
     return _Py_REFCNT(ob);
 }
+
+int
+PyUnstable_IsImmortal(PyObject *op)
+{
+    /* Checking a reference count requires a thread state */
+    _Py_AssertHoldsTstate();
+    assert(op != NULL);
+    return _Py_IsImmortal(op);
+}