Add a test.

Author: ZeroIntensity

Doc/c-api/object.rst

@@ -615,7 +615,7 @@ Object Protocol
 
 .. c:function:: int PyUnstable_IsImmortal(PyObject *obj)
 
-   This function returns ``1`` if *obj* is :term:`immortal`, and ``0`` otherwise.
+   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

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()

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 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 */
 };