Update the pretty print protocol documentation

Author: warsaw

Doc/library/functions.rst

@@ -1610,9 +1610,9 @@ are always available.  They are listed here in alphabetical order.
 
    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
+   :meth:`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.
+   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

Doc/library/pprint.rst

@@ -261,11 +261,29 @@ are converted to strings.  The default implementation uses the internals of the
 The "__pprint__" protocol
 -------------------------
 
-Pretty printing will use an object's ``__repr__`` by default.  For custom pretty printing, objects can
+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 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.
+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:
 
@@ -432,11 +450,37 @@ cannot be split, the specified width will be exceeded::
     'summary': 'A sample Python project',
     'version': '1.2.0'}
 
-A custom ``__pprint__()`` method can be used to customize the representation of the object::
+.. _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)
 
-    >>> 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
+Note that you'd get exactly the same output if you used ``print(..., pretty=True)``.