python · kumaraditya303 · Jan 31, 2025 · Jan 5, 2025 · Jan 5, 2025 · Jan 5, 2025
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
@@ -658,6 +658,8 @@ Glossary
       and therefore it is never deallocated while the interpreter is running.
       For example, :const:`True` and :const:`None` are immortal in CPython.
 
+      Immortal objects can be identified via :func:`sys._is_immortal`.
+
    immutable
       An object with a fixed value.  Immutable objects include numbers, strings and
       tuples.  Such an object cannot be altered.  A new object has to

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -855,6 +855,11 @@ always available. Unless explicitly noted otherwise, all variables are read-only
    reflect the actual number of references.  Consequently, do not rely
    on the returned value to be accurate, other than a value of 0 or 1.
 
+   .. impl-detail::
+
+      :term:`Immortal <immortal>` objects with a large reference count can be identified
+      via :func:`_is_immortal`.
+
    .. versionchanged:: 3.12
       Immortal objects have very large refcounts that do not match
       the actual number of references to the object.
@@ -1264,6 +1269,23 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 
    .. versionadded:: 3.12
 
+.. function:: _is_immortal(op)
+
+   Return :const:`True` if the given object is :term:`immortal`, :const:`False`
+   otherwise.
+
+   .. note::
+
+      Objects that are immortal (and thus return ``True`` upon being passed to this function)
+      are not guaranteed to be immortal in future versions, and vice versa for mortal objects.
+
+   .. versionadded:: next
+
+   .. impl-detail::
+
+      This function should be used for specialized purposes only.
+      It is not guaranteed to exist in all implementations of Python.
+
 .. function:: _is_interned(string)
 
    Return :const:`True` if the given string is "interned", :const:`False`

diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
@@ -649,6 +649,9 @@ sys
   which only exists in specialized builds of Python, may now return objects
   from other interpreters than the one it's called in.
 
+* Add :func:`sys._is_immortal` for determining if an object is :term:`immortal`.
+  (Contributed by Peter Bierma in :gh:`128509`.)
+
 sys.monitoring
 --------------
 

diff --git a/Lib/test/test_capi/test_immortal.py b/Lib/test/test_capi/test_immortal.py
@@ -1,26 +1,32 @@
 import unittest
 from test.support import import_helper
+import sys
 
 _testcapi = import_helper.import_module('_testcapi')
 _testinternalcapi = import_helper.import_module('_testinternalcapi')
 
 
-class TestUnstableCAPI(unittest.TestCase):
-    def test_immortal(self):
+class TestImmortalAPI(unittest.TestCase):
+    def immortal_checking(self, func):
         # Not extensive
         known_immortals = (True, False, None, 0, ())
         for immortal in known_immortals:
             with self.subTest(immortal=immortal):
-                self.assertTrue(_testcapi.is_immortal(immortal))
+                self.assertTrue(func(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))
+                self.assertFalse(func(non_immortal))
 
+    def test_unstable_c_api(self):
+        self.immortal_checking(_testcapi.is_immortal)
         # CRASHES _testcapi.is_immortal(NULL)
 
+    def test_sys(self):
+        self.immortal_checking(sys._is_immortal)
+
 
 class TestInternalCAPI(unittest.TestCase):
 

diff --git a/Misc/NEWS.d/next/Library/2025-01-04-20-51-48.gh-issue-128509.3gr_-O.rst b/Misc/NEWS.d/next/Library/2025-01-04-20-51-48.gh-issue-128509.3gr_-O.rst
@@ -0,0 +1,2 @@
+Add :func:`sys._is_immortal` for identifying :term:`immortal` objects at
+runtime.
@@ -955,6 +955,21 @@ sys_intern_impl(PyObject *module, PyObject *s)
     }
 }
 
+/*[clinic input]
+sys._is_immortal -> bool
+
+  op: object
+  /
+
+Return True if the given object is "immortal" per PEP 683.
+[clinic start generated code]*/
+
+static int
+sys__is_immortal_impl(PyObject *module, PyObject *op)
+/*[clinic end generated code: output=c2f5d6a80efb8d1a input=83733fc356c78475]*/
+{
+    return _Py_IsImmortal(op);
+}
 
 /*[clinic input]
 sys._is_interned -> bool
@@ -2590,6 +2605,7 @@ static PyMethodDef sys_methods[] = {
     SYS__GETFRAMEMODULENAME_METHODDEF
     SYS_GETWINDOWSVERSION_METHODDEF
     SYS__ENABLELEGACYWINDOWSFSENCODING_METHODDEF
+    SYS__IS_IMMORTAL_METHODDEF
     SYS_INTERN_METHODDEF
     SYS__IS_INTERNED_METHODDEF
     SYS_IS_FINALIZING_METHODDEF
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Add :func:`sys._is_immortal` for identifying :term:`immortal` objects at
		runtime.