gh-128509: Add PyUnstable_IsImmortal for finding immortal objects

Doc/c-api/object.rst

@@ -613,3 +613,19 @@ Object Protocol
 
    .. versionadded:: 3.14
 
+.. c:function:: int PyUnstable_IsImmortal(PyObject *obj)
+
+   This function returns ``1`` if *obj* is :term:`immortal`, and ``0`` otherwise. This function cannot fail.
+
+   Immortal objects don't care about reference counting, thus they no-op calls to :c:func:`Py_INCREF`
+   and :c:func:`Py_DECREF`. Some immutable objects such as literal strings, small integers, or special tuples
+   might be made immortal as an optimization by the interpreter.
+
+   On the :term:`free-threaded <free threading>` build, some objects that support deferred reference counting
+   (see :c:func:`PyUnstable_Object_EnableDeferredRefcount`) might also be immortalized.
+
+   .. note::
+
+      Objects that are immortal in one version are not guarunteed 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,20 @@ 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))
+
+
 
 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/_testcapimodule.c

@@ -3487,6 +3487,12 @@ tracemalloc_track_race(PyObject *self, PyObject *args)
 #undef NTHREAD
 }
 
+static PyObject *
+is_immortal(PyObject *self, PyObject *op)
+{
+    return PyBool_FromLong(PyUnstable_IsImmortal(op));
+}
+
 static PyMethodDef TestMethods[] = {
     {"set_errno",               set_errno,                       METH_VARARGS},
     {"test_config",             test_config,                     METH_NOARGS},
@@ -3630,6 +3636,7 @@ static PyMethodDef TestMethods[] = {
     {"test_atexit", test_atexit, METH_NOARGS},
     {"code_offset_to_line", _PyCFunction_CAST(code_offset_to_line), METH_FASTCALL},
     {"tracemalloc_track_race", tracemalloc_track_race, METH_NOARGS},
+    {"is_immortal", is_immortal, METH_O},
     {NULL, NULL} /* sentinel */
 };
 

Objects/object.c

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