Flesh out PyObject_Pretty()

* Document it in the C-API docs.
* Express the refcounting semantics in refcounts.dat.
* Describe PyObject_Pretty in the stable_abi.dat and stable_abi.toml files.
* Add tests to test_capi/test_abstract.py

Author: warsaw

Doc/c-api/object.rst

@@ -380,6 +380,15 @@ Object Protocol
    .. index:: string; PyObject_Str (C function)
 
 
+.. c:function:: PyObject* PyObject_Pretty(PyObject *o)
+
+   Return the "pretty" representation of an object *o*, which must not be
+   ``NULL``. This is used by the ``!p`` specifier for both f-strings and
+   :func:`str.format`.  This function is not directly exposed in Python.
+
+   .. versionadded:: 3.15
+
+
 .. c:function:: PyObject* PyObject_Str(PyObject *o)
 
    Compute a string representation of object *o*.  Returns the string

Doc/data/refcounts.dat

@@ -1690,6 +1690,9 @@ PyOS_FSPath:PyObject*:path:0:
 PyObject_ASCII:PyObject*::+1:
 PyObject_ASCII:PyObject*:o:0:
 
+PyObject_Pretty:PyObject*::+1:
+PyObject_Pretty:PyObject*:o:0:
+
 PyObject_Bytes:PyObject*::+1:
 PyObject_Bytes:PyObject*:o:0:
 

Doc/data/stable_abi.dat

@@ -112,6 +112,35 @@ def test_object_ascii(self):
         self.assertTypedEqual(object_ascii(WithRepr(StrSubclass('<\U0001f40d>'))), r'<\U0001f40d>')
         self.assertTypedEqual(object_ascii(NULL), '<NULL>')
 
+    def test_object_pretty(self):
+        # Test PyObject_Pretty()
+        import pprint
+        object_pretty = _testlimitedcapi.object_pretty
+
+        # Simple objects: pretty == repr for short values
+        self.assertTypedEqual(object_pretty('abc'), "'abc'")
+        self.assertTypedEqual(object_pretty(42), '42')
+        self.assertTypedEqual(object_pretty([1, 2, 3]), '[1, 2, 3]')
+        self.assertTypedEqual(object_pretty({'a': 1}), "{'a': 1}")
+        self.assertTypedEqual(object_pretty(()), '()')
+        self.assertTypedEqual(object_pretty(True), 'True')
+        self.assertTypedEqual(object_pretty(None), 'None')
+
+        # Nested/long structures that pformat formats differently from repr
+        long_list = list(range(20))
+        self.assertEqual(object_pretty(long_list), pprint.pformat(long_list))
+
+        nested = {'key1': list(range(10)), 'key2': {'inner': list(range(10))}}
+        self.assertEqual(object_pretty(nested), pprint.pformat(nested))
+
+        # OrderedDict
+        od = OrderedDict([('b', 2), ('a', 1), ('c', 3)])
+        self.assertEqual(object_pretty(od), pprint.pformat(od))
+
+        # Return type is always str
+        self.assertIsInstance(object_pretty([1, 2, 3]), str)
+        self.assertIsInstance(object_pretty(nested), str)
+
     def test_object_bytes(self):
         # Test PyObject_Bytes()
         object_bytes = _testlimitedcapi.object_bytes

Lib/test/test_capi/test_abstract.py

@@ -1138,6 +1138,8 @@
     added = '3.2'
 [function.PyObject_ASCII]
     added = '3.2'
+[function.PyObject_Pretty]
+    added = '3.15'
 [function.PyObject_AsFileDescriptor]
     added = '3.2'
 [function.PyObject_Bytes]

Lib/test/test_stable_abi_ctypes.py

@@ -23,6 +23,12 @@ object_str(PyObject *self, PyObject *arg)
     return PyObject_Str(arg);
 }
 
+static PyObject *
+object_pretty(PyObject *self, PyObject *arg)
+{
+    return PyObject_Pretty(arg);
+}
+
 static PyObject *
 object_bytes(PyObject *self, PyObject *arg)
 {
@@ -533,6 +539,7 @@ static PyMethodDef test_methods[] = {
     {"object_repr", object_repr, METH_O},
     {"object_ascii", object_ascii, METH_O},
     {"object_str", object_str, METH_O},
+    {"object_pretty", object_pretty, METH_O},
     {"object_bytes", object_bytes, METH_O},
 
     {"object_getattr", object_getattr, METH_VARARGS},