Flesh out the pprint protocol documentation

* Update the docs on the `print()` function to describe the new `pretty` keyword
* Document the `__pprint__()` protocol.
* Add a test for the `__pprint__()` protocol method.

Author: warsaw

Doc/library/functions.rst

@@ -1587,17 +1587,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
+   :method:`PrettyPrinter.pprint()` API which takes an object and returns a
+   formatted representation of the object.  When *pretty* is ``True``, then it
+   actually does call ``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
@@ -1611,6 +1617,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

@@ -28,6 +28,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
@@ -253,6 +256,16 @@ 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 will use 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 with 4 arguments, exactly matching the API of :meth:`PrettyPrinter.format()`.  The
+``__pprint__()`` method is expected to return a string, which is used as the pretty printed representation of
+the object.
 
 .. _pprint-example:
 
@@ -418,3 +431,12 @@ cannot be split, the specified width will be exceeded::
     'requires_python': None,
     'summary': 'A sample Python project',
     'version': '1.2.0'}
+
+A custom ``__pprint__()`` method can be used to customize the representation of the object::
+
+    >>> class Custom:
+    ...     def __str__(self): return 'my str'
+    ...     def __repr__(self): return 'my repr'
+    ...     def __pprint__(self, context, maxlevels, level): return 'my pprint'
+    >>> pprint.pp(Custom())
+    my pprint

Lib/test/test_pprint.py

@@ -134,6 +134,18 @@ def __ne__(self, other):
     def __hash__(self):
         return self._hash
 
+
+class CustomPrintable:
+    def __str__(self):
+        return "my str"
+
+    def __repr__(self):
+        return "my str"
+
+    def __pprint__(self, context, maxlevels, level):
+        return "my pprint"
+
+
 class QueryTestCase(unittest.TestCase):
 
     def setUp(self):
@@ -1472,6 +1484,13 @@ def test_user_string(self):
     'jumped over a '
     'lazy dog'}""")
 
+    def test_custom_pprinter(self):
+        stream = io.StringIO()
+        pp = pprint.PrettyPrinter(stream=stream)
+        custom_obj = CustomPrintable()
+        pp.pprint(custom_obj)
+        self.assertEqual(stream.getvalue(), "my pprint\n")
+
 
 class DottedPrettyPrinter(pprint.PrettyPrinter):