gh-145153: The PEP 813 (pretty print protocol) reference implementation

.pre-commit-config.yaml

@@ -14,6 +14,8 @@ repos:
         name: Run Ruff (lint) on Lib/test/
         args: [--exit-non-zero-on-fix]
         files: ^Lib/test/
+        # TODO: remove this exclude once !p f-string support is merged to main
+        exclude: ^Lib/test/test_print\.py$
       - id: ruff-check
         name: Run Ruff (lint) on Tools/build/
         args: [--exit-non-zero-on-fix, --config=Tools/build/.ruff.toml]

Doc/library/functions.rst

@@ -1598,17 +1598,23 @@ are always available.  They are listed here in alphabetical order.
       supported.
 
 
-.. function:: print(*objects, sep=' ', end='\n', file=None, flush=False)
+.. function:: print(*objects, sep=' ', end='\n', file=None, flush=False, pretty=None)
 
-   Print *objects* to the text stream *file*, separated by *sep* and followed
-   by *end*.  *sep*, *end*, *file*, and *flush*, if present, must be given as keyword
-   arguments.
+   Print *objects* to the text stream *file*, separated by *sep* and followed by
+   *end*.  *sep*, *end*, *file*, *flush*, and *pretty*, if present, must be
+   given as keyword arguments.
+
+   When *pretty* is ``None``, all non-keyword arguments are converted to
+   strings like :func:`str` does and written to the stream, separated by *sep*
+   and followed by *end*.  Both *sep* and *end* must be strings; they can also
+   be ``None``, which means to use the default values.  If no *objects* are
+   given, :func:`print` will just write *end*.
 
-   All non-keyword arguments are converted to strings like :func:`str` does and
-   written to the stream, separated by *sep* and followed by *end*.  Both *sep*
-   and *end* must be strings; they can also be ``None``, which means to use the
-   default values.  If no *objects* are given, :func:`print` will just write
-   *end*.
+   When *pretty* is given, it signals that the objects should be "pretty
+   printed".  *pretty* can be ``True`` or an object implementing the
+   :meth:`pprint.PrettyPrinter.pformat` API which takes an object and returns a
+   formatted representation of the object.  When *pretty* is ``True``, then it
+   calls ``PrettyPrinter.pformat()`` explicitly.
 
    The *file* argument must be an object with a ``write(string)`` method; if it
    is not present or ``None``, :data:`sys.stdout` will be used.  Since printed
@@ -1622,6 +1628,9 @@ are always available.  They are listed here in alphabetical order.
    .. versionchanged:: 3.3
       Added the *flush* keyword argument.
 
+   .. versionchanged:: 3.15
+      Added the *pretty* keyword argument.
+
 
 .. class:: property(fget=None, fset=None, fdel=None, doc=None)
 

Doc/library/pprint.rst

@@ -25,6 +25,9 @@ adjustable by the *width* parameter defaulting to 80 characters.
 .. versionchanged:: 3.10
    Added support for pretty-printing :class:`dataclasses.dataclass`.
 
+.. versionchanged:: 3.15
+   Added support for the :ref:`__pprint__ <dunder-pprint>` protocol.
+
 .. _pprint-functions:
 
 Functions
@@ -250,6 +253,34 @@ are converted to strings.  The default implementation uses the internals of the
    calls. The fourth argument, *level*, gives the current level; recursive calls
    should be passed a value less than that of the current call.
 
+.. _dunder-pprint:
+
+The "__pprint__" protocol
+-------------------------
+
+Pretty printing uses an object's ``__repr__`` by default.  For custom pretty printing, objects can
+implement a ``__pprint__()`` function to customize how their representations will be printed.  If this method
+exists, it is called instead of ``__repr__``.  The method is called with a single argument, the object to be
+pretty printed.
+
+The method is expected to return or yield a sequence of values, which are used to construct a pretty
+representation of the object.  These values are wrapped in standard class "chrome", such as the class name.
+The printed representation will usually look like a class constructor, with positional, keyword, and default
+arguments.  The values can be any of the following formats:
+
+* A single value, representing a positional argument.  The value itself is used.
+* A 2-tuple of ``(name, value)`` representing a keyword argument.  A representation of
+  ``name=value`` is used.
+* A 3-tuple of ``(name, value, default_value)`` representing a keyword argument with a default
+  value.  If ``value`` equals ``default_value``, then this tuple is skipped, otherwise
+  ``name=value`` is used.
+
+.. note::
+
+   This protocol is compatible with the `Rich library's pretty printing protocol
+   <https://rich.readthedocs.io/en/latest/pretty.html#rich-repr-protocol>`_.
+
+See the :ref:`pprint-protocol-example` for how this can be used in practice.
 
 .. _pprint-example:
 
@@ -415,3 +446,38 @@ cannot be split, the specified width will be exceeded::
     'requires_python': None,
     'summary': 'A sample Python project',
     'version': '1.2.0'}
+
+.. _pprint-protocol-example:
+
+Pretty Print Protocol Example
+-----------------------------
+
+Let's start with a simple class that defines a ``__pprint__()`` method:
+
+.. code-block:: python
+
+    class Bass:
+        def __init__(self, strings: int, pickups: str, active: bool=False):
+            self._strings = strings
+            self._pickups = pickups
+            self._active = active
+
+        def __pprint__(self):
+            yield self._strings
+            yield 'pickups', self._pickups
+            yield 'active', self._active, False
+
+    precision = Bass(4, 'split coil P', active=False)
+    stingray = Bass(5, 'humbucker', active=True)
+
+The ``__pprint__()`` method yields three values, which correspond to the ``__init__()`` arguments,
+showing by example each of the three different allowed formats.  Here is what the output looks like:
+
+.. code-block:: pycon
+
+    >>> pprint.pprint(precision)
+    Bass(4, pickups='split coil P')
+    >>> pprint.pprint(stingray)
+    Bass(5, pickups='humbucker', active=True)
+
+Note that you'd get exactly the same output if you used ``print(..., pretty=True)``.

Include/ceval.h

@@ -125,13 +125,14 @@ PyAPI_FUNC(void) PyEval_ReleaseThread(PyThreadState *tstate);
                  }
 
 /* Masks and values used by FORMAT_VALUE opcode. */
-#define FVC_MASK      0x3
+#define FVC_MASK      0x7
 #define FVC_NONE      0x0
 #define FVC_STR       0x1
 #define FVC_REPR      0x2
 #define FVC_ASCII     0x3
-#define FVS_MASK      0x4
-#define FVS_HAVE_SPEC 0x4
+#define FVC_PRETTY    0x4
+#define FVS_MASK      0x8
+#define FVS_HAVE_SPEC 0x8
 
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_CEVAL_H

Include/internal/pycore_global_strings.h

@@ -716,6 +716,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(posix)
         STRUCT_FOR_ID(prec)
         STRUCT_FOR_ID(preserve_exc)
+        STRUCT_FOR_ID(pretty)
         STRUCT_FOR_ID(print_file_and_line)
         STRUCT_FOR_ID(priority)
         STRUCT_FOR_ID(progress)

Include/object.h

@@ -466,6 +466,7 @@ PyAPI_FUNC(void) PyType_Modified(PyTypeObject *);
 PyAPI_FUNC(PyObject *) PyObject_Repr(PyObject *);
 PyAPI_FUNC(PyObject *) PyObject_Str(PyObject *);
 PyAPI_FUNC(PyObject *) PyObject_ASCII(PyObject *);
+PyAPI_FUNC(PyObject *) PyObject_Pretty(PyObject *);
 PyAPI_FUNC(PyObject *) PyObject_Bytes(PyObject *);
 PyAPI_FUNC(PyObject *) PyObject_RichCompare(PyObject *, PyObject *, int);
 PyAPI_FUNC(int) PyObject_RichCompareBool(PyObject *, PyObject *, int);

Lib/pprint.py

@@ -623,12 +623,60 @@ def _pprint_user_string(self, object, stream, indent, allowance, context, level)
 
     _dispatch[_collections.UserString.__repr__] = _pprint_user_string
 
+    def _format_pprint(self, object, method, context, maxlevels, level):
+        """Format an object using its __pprint__ method.
+
+        The __pprint__ method should be a generator yielding values:
+           - yield value                  -> positional arg
+           - yield (name, value)          -> keyword arg, always shown
+           - yield (name, value, default) -> keyword arg, shown if value != default
+        """
+        cls_name = type(object).__name__
+        parts = []
+        readable = True
+
+        for item in method(object):
+            match item:
+                case (name, value, default):
+                    # Keyword argument w/default.  Show only if value != default.
+                    if value != default:
+                        formatted, is_readable, _ = self.format(value, context, maxlevels, level + 1)
+                        parts.append(f"{name}={formatted}")
+                        readable = readable and is_readable
+                case (str() as name, value) if name:
+                    # Keyword argument.  Always show.
+                    formatted, is_readable, _ = self.format(value, context, maxlevels, level + 1)
+                    parts.append(f"{name}={formatted}")
+                    readable = readable and is_readable
+                case (name, value) if not name:
+                    # 2-tuple with a false-y name: treat as positional.
+                    formatted, is_readable, _ = self.format(value, context, maxlevels, level + 1)
+                    parts.append(formatted)
+                    readable = readable and is_readable
+                case (name, value):
+                    # Truthy non-string name is an error.
+                    raise ValueError(
+                        f"__pprint__ yielded a 2-tuple with "
+                        f"non-string name: {name!r}"
+                    )
+                case _:
+                    # Positional argument.
+                    formatted, is_readable, _ = self.format(item, context, maxlevels, level + 1)
+                    parts.append(formatted)
+                    readable = readable and is_readable
+
+        rep = f"{cls_name}({', '.join(parts)})"
+        return rep, readable, False
+
     def _safe_repr(self, object, context, maxlevels, level):
         # Return triple (repr_string, isreadable, isrecursive).
         typ = type(object)
         if typ in _builtin_scalars:
             return repr(object), True, False
 
+        if (p := getattr(typ, "__pprint__", None)):
+            return self._format_pprint(object, p, context, maxlevels, level)
+
         r = getattr(typ, "__repr__", None)
 
         if issubclass(typ, int) and r is int.__repr__:

Lib/test/test_fstring.py

@@ -1369,7 +1369,7 @@ def test_conversions(self):
         for conv_identifier in 'g', 'A', 'G', 'ä', 'ɐ':
             self.assertAllRaise(SyntaxError,
                                 "f-string: invalid conversion character %r: "
-                                "expected 's', 'r', or 'a'" % conv_identifier,
+                                "expected 's', 'r', 'a', or 'p'" % conv_identifier,
                                 ["f'{3!" + conv_identifier + "}'"])
 
         for conv_non_identifier in '3', '!':
@@ -1385,7 +1385,7 @@ def test_conversions(self):
 
         self.assertAllRaise(SyntaxError,
                             "f-string: invalid conversion character 'ss': "
-                            "expected 's', 'r', or 'a'",
+                            "expected 's', 'r', 'a', or 'p'",
                             ["f'{3!ss}'",
                              "f'{3!ss:}'",
                              "f'{3!ss:s}'",