gh-115754: Add Py_GetConstant() function (#116883)

Add Py_GetConstant() and Py_GetConstantBorrowed() functions.

In the limited C API version 3.13, getting Py_None, Py_False,
Py_True, Py_Ellipsis and Py_NotImplemented singletons is now
implemented as function calls at the stable ABI level to hide
implementation details. Getting these constants still return borrowed
references.

Add _testlimitedcapi/object.c and test_capi/test_object.py to test
Py_GetConstant() and Py_GetConstantBorrowed() functions.

2 files changed, 56 insertions, 0 deletions

diff --git a/Lib/test/test_capi/test_object.py b/Lib/test/test_capi/test_object.py
new file mode 100644
index 0000000..c80e9b6
--- /dev/null
+++ b/Lib/test/test_capi/test_object.py
@@ -0,0 +1,54 @@
+import enum
+import unittest
+from test.support import import_helper
+
+_testlimitedcapi = import_helper.import_module('_testlimitedcapi')
+
+
+class Constant(enum.IntEnum):
+    Py_CONSTANT_NONE = 0
+    Py_CONSTANT_FALSE = 1
+    Py_CONSTANT_TRUE = 2
+    Py_CONSTANT_ELLIPSIS = 3
+    Py_CONSTANT_NOT_IMPLEMENTED = 4
+    Py_CONSTANT_ZERO = 5
+    Py_CONSTANT_ONE = 6
+    Py_CONSTANT_EMPTY_STR = 7
+    Py_CONSTANT_EMPTY_BYTES = 8
+    Py_CONSTANT_EMPTY_TUPLE = 9
+
+    INVALID_CONSTANT = Py_CONSTANT_EMPTY_TUPLE + 1
+
+
+class CAPITest(unittest.TestCase):
+    def check_get_constant(self, get_constant):
+        self.assertIs(get_constant(Constant.Py_CONSTANT_NONE), None)
+        self.assertIs(get_constant(Constant.Py_CONSTANT_FALSE), False)
+        self.assertIs(get_constant(Constant.Py_CONSTANT_TRUE), True)
+        self.assertIs(get_constant(Constant.Py_CONSTANT_ELLIPSIS), Ellipsis)
+        self.assertIs(get_constant(Constant.Py_CONSTANT_NOT_IMPLEMENTED), NotImplemented)
+
+        for constant_id, constant_type, value in (
+            (Constant.Py_CONSTANT_ZERO, int, 0),
+            (Constant.Py_CONSTANT_ONE, int, 1),
+            (Constant.Py_CONSTANT_EMPTY_STR, str, ""),
+            (Constant.Py_CONSTANT_EMPTY_BYTES, bytes, b""),
+            (Constant.Py_CONSTANT_EMPTY_TUPLE, tuple, ()),
+        ):
+            with self.subTest(constant_id=constant_id):
+                obj = get_constant(constant_id)
+                self.assertEqual(type(obj), constant_type, obj)
+                self.assertEqual(obj, value)
+
+        with self.assertRaises(SystemError):
+            get_constant(Constant.INVALID_CONSTANT)
+
+    def test_get_constant(self):
+        self.check_get_constant(_testlimitedcapi.get_constant)
+
+    def test_get_constant_borrowed(self):
+        self.check_get_constant(_testlimitedcapi.get_constant_borrowed)
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/Lib/test/test_stable_abi_ctypes.py b/Lib/test/test_stable_abi_ctypes.py
index 117c27d..0e30485 100644
--- a/Lib/test/test_stable_abi_ctypes.py
+++ b/Lib/test/test_stable_abi_ctypes.py
@@ -856,6 +856,8 @@ SYMBOL_NAMES = (
     "Py_GetArgcArgv",
     "Py_GetBuildInfo",
     "Py_GetCompiler",
+    "Py_GetConstant",
+    "Py_GetConstantBorrowed",
     "Py_GetCopyright",
     "Py_GetExecPrefix",
     "Py_GetPath",