gh-146063: Add PyObject_CallFinalizer() to the limited C API

Add PyObject_CallFinalizer() and PyObject_CallFinalizerFromDealloc()
to the limited C API.

Add a test on PyObject_CallFinalizer().

Author: vstinner

Doc/data/stable_abi.dat

@@ -1662,6 +1662,10 @@ New features
 
   (Contributed by Victor Stinner in :gh:`141510`.)
 
+* Add :c:func:`PyObject_CallFinalizer` and
+  :c:func:`PyObject_CallFinalizerFromDealloc` functions to the limited C API.
+  (Contributed by Victor Stinner in :gh:`146063`.)
+
 * Add :c:func:`PySys_GetAttr`, :c:func:`PySys_GetAttrString`,
   :c:func:`PySys_GetOptionalAttr`, and :c:func:`PySys_GetOptionalAttrString`
   functions as replacements for :c:func:`PySys_GetObject`.

Doc/whatsnew/3.15.rst

@@ -303,8 +303,6 @@ PyAPI_FUNC(void) PyObject_Dump(PyObject *);
 Py_DEPRECATED(3.15) PyAPI_FUNC(PyObject*) _PyObject_GetAttrId(PyObject *, _Py_Identifier *);
 
 PyAPI_FUNC(PyObject **) _PyObject_GetDictPtr(PyObject *);
-PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *);
-PyAPI_FUNC(int) PyObject_CallFinalizerFromDealloc(PyObject *);
 
 PyAPI_FUNC(void) PyUnstable_Object_ClearWeakRefsNoCallbacks(PyObject *);
 

Include/cpython/object.h

@@ -856,6 +856,9 @@ PyAPI_FUNC(int) PyType_Freeze(PyTypeObject *type);
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= _Py_PACK_VERSION(3, 15)
 PyAPI_FUNC(PyObject *) PyType_GetModuleByToken(PyTypeObject *type,
                                                const void *token);
+
+PyAPI_FUNC(void) PyObject_CallFinalizer(PyObject *);
+PyAPI_FUNC(int) PyObject_CallFinalizerFromDealloc(PyObject *);
 #endif
 
 #ifdef __cplusplus

Include/object.h

@@ -305,6 +305,21 @@ def test_pyobject_dump(self):
         output = self.pyobject_dump(NULL)
         self.assertRegex(output, r'<object at .* is freed>')
 
+    def test_pyobject_callfinalizer(self):
+        # Test PyObject_CallFinalizer()
+        pyobject_callfinalizer = _testlimitedcapi.pyobject_callfinalizer
+
+        class Finalizer:
+            def __init__(self):
+                self.finalized = False
+            def __del__(self):
+                self.finalized = True
+
+        obj = Finalizer()
+        self.assertFalse(obj.finalized)
+        pyobject_callfinalizer(obj)
+        self.assertTrue(obj.finalized)
+
 
 if __name__ == "__main__":
     unittest.main()

Lib/test/test_capi/test_object.py

@@ -0,0 +1,3 @@
+Add :c:func:`PyObject_CallFinalizer` and
+:c:func:`PyObject_CallFinalizerFromDealloc` functions to the limited C API.
+Patch by Victor Stinner.

Lib/test/test_stable_abi_ctypes.py

@@ -2668,7 +2668,6 @@
     added = '3.15'
 
 # PEP 757 import/export API.
-
 [function.PyLong_GetNativeLayout]
     added = '3.15'
 [function.PyLong_Export]
@@ -2692,3 +2691,8 @@
     # Note: The `_reserved` member of this struct is for interal use only.
     # (The definition of 'full-abi' was clarified when this entry was added.)
     struct_abi_kind = 'full-abi'
+
+[function.PyObject_CallFinalizer]
+    added = '3.15'
+[function.PyObject_CallFinalizerFromDealloc]
+    added = '3.15'

Misc/NEWS.d/next/C_API/2026-03-19-15-28-14.gh-issue-146063.Sc-1RU.rst

@@ -1,7 +1,7 @@
-// Need limited C API version 3.13 for Py_GetConstant()
+// Need limited C API version 3.15 for PyObject_CallFinalizer()
 #include "pyconfig.h"   // Py_GIL_DISABLED
 #if !defined(Py_GIL_DISABLED) && !defined(Py_LIMITED_API)
-#  define Py_LIMITED_API 0x030d0000
+#  define Py_LIMITED_API 0x030f0000
 #endif
 
 #include "parts.h"
@@ -62,19 +62,25 @@ test_constants(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
     Py_RETURN_NONE;
 }
 
+
+static PyObject *
+pyobject_callfinalizer(PyObject *Py_UNUSED(module), PyObject *obj)
+{
+    PyObject_CallFinalizer(obj);
+    Py_RETURN_NONE;
+}
+
+
 static PyMethodDef test_methods[] = {
     {"get_constant", get_constant, METH_VARARGS},
     {"get_constant_borrowed", get_constant_borrowed, METH_VARARGS},
     {"test_constants", test_constants, METH_NOARGS},
+    {"pyobject_callfinalizer", pyobject_callfinalizer, METH_O},
     {NULL},
 };
 
 int
 _PyTestLimitedCAPI_Init_Object(PyObject *m)
 {
-    if (PyModule_AddFunctions(m, test_methods) < 0) {
-        return -1;
-    }
-
-    return 0;
+    return PyModule_AddFunctions(m, test_methods);
 }