pythongh-141070: Add PyObject_Dump() function

Promote _PyObject_Dump() as a public function.

Keep _PyObject_Dump() alias to PyObject_Dump() for backward
compatibility.

Author: vstinner

Doc/c-api/object.rst

@@ -85,6 +85,26 @@ Object Protocol
    instead of the :func:`repr`.
 
 
+.. c:function:: void PyObject_Dump(PyObject* op)
+
+   Dump an object *op* to ``stderr``. Function used for debugging.
+
+   It can be called without an :term:`attached thread state`, even if it's not
+   recommended.
+
+   Implement an heuristic to detect if the object memory has been freed.
+
+   Example of output::
+
+       object address  : 0x7f80124702c0
+       object refcount : 2
+       object type     : 0x9902e0
+       object type name: str
+       object repr     : 'abcdef'
+
+   .. versionadded:: next
+
+
 .. c:function:: int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)
 
    Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.

Doc/whatsnew/3.15.rst

@@ -947,6 +947,10 @@ New features
 
   (Contributed by Victor Stinner in :gh:`129813`.)
 
+* Add :c:func:`PyObject_Dump` to dump an object to ``stderr``. Function used
+  for debugging.
+  (Contributed by Victor Stinner in :gh:`141070`.)
+
 * Add :c:func:`PyTuple_FromArray` to create a :class:`tuple` from an array.
   (Contributed by Victor Stinner in :gh:`111489`.)
 

Include/cpython/object.h

@@ -295,7 +295,10 @@ PyAPI_FUNC(PyObject *) PyType_GetDict(PyTypeObject *);
 
 PyAPI_FUNC(int) PyObject_Print(PyObject *, FILE *, int);
 PyAPI_FUNC(void) _Py_BreakPoint(void);
-PyAPI_FUNC(void) _PyObject_Dump(PyObject *);
+PyAPI_FUNC(void) PyObject_Dump(PyObject *);
+
+// Alias for backward compatibility
+#define _PyObject_Dump PyObject_Dump
 
 PyAPI_FUNC(PyObject*) _PyObject_GetAttrId(PyObject *, _Py_Identifier *);
 

Lib/test/test_capi/test_object.py

@@ -1,4 +1,5 @@
 import enum
+import os
 import sys
 import textwrap
 import unittest
@@ -13,6 +14,8 @@
 _testcapi = import_helper.import_module('_testcapi')
 _testinternalcapi = import_helper.import_module('_testinternalcapi')
 
+STDERR_FD = 2
+
 
 class Constant(enum.IntEnum):
     Py_CONSTANT_NONE = 0
@@ -247,5 +250,40 @@ def func(x):
 
         func(object())
 
+    def test_pyobject_dump(self):
+        pyobject_dump = _testcapi.pyobject_dump
+        obj = 'test string'
+
+        filename = os_helper.TESTFN
+        self.addCleanup(os_helper.unlink, filename)
+
+        try:
+            old_stderr = os.dup(STDERR_FD)
+        except OSError as exc:
+            # os.dup(STDERR_FD) is not supported on WASI
+            self.skipTest(f"os.dup() failed with {exc!r}")
+
+        try:
+            with open(filename, "wb") as fp:
+                fd = fp.fileno()
+                os.dup2(fd, STDERR_FD)
+                pyobject_dump(obj)
+        finally:
+            os.dup2(old_stderr, STDERR_FD)
+            os.close(old_stderr)
+
+        with open(filename) as fp:
+            output = fp.read()
+
+        hex_regex = r'0x[0-9a-fA-F]+'
+        self.assertRegex(output.rstrip(),
+            fr"object address  : {hex_regex}\n"
+             r"object refcount : [0-9]+\n"
+            fr"object type     : {hex_regex}\n"
+             r"object type name: str\n"
+             r"object repr     : 'test string'"
+        )
+
+
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C_API/2025-11-05-21-48-31.gh-issue-141070.mkrhjQ.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyObject_Dump` to dump an object to ``stderr``. Function used
+for debugging. Patch by Victor Stinner.

Modules/_testcapi/object.c

@@ -485,6 +485,14 @@ is_uniquely_referenced(PyObject *self, PyObject *op)
 }
 
 
+static PyObject *
+pyobject_dump(PyObject *self, PyObject *op)
+{
+    PyObject_Dump(op);
+    Py_RETURN_NONE;
+}
+
+
 static PyMethodDef test_methods[] = {
     {"call_pyobject_print", call_pyobject_print, METH_VARARGS},
     {"pyobject_print_null", pyobject_print_null, METH_VARARGS},
@@ -511,6 +519,7 @@ static PyMethodDef test_methods[] = {
     {"test_py_is_funcs", test_py_is_funcs, METH_NOARGS},
     {"clear_managed_dict", clear_managed_dict, METH_O, NULL},
     {"is_uniquely_referenced", is_uniquely_referenced, METH_O},
+    {"pyobject_dump", pyobject_dump, METH_O},
     {NULL},
 };
 

Objects/object.c

@@ -713,7 +713,7 @@ _PyObject_IsFreed(PyObject *op)
 
 /* For debugging convenience.  See Misc/gdbinit for some useful gdb hooks */
 void
-_PyObject_Dump(PyObject* op)
+PyObject_Dump(PyObject* op)
 {
     if (_PyObject_IsFreed(op)) {
         /* It seems like the object memory has been freed: