gh-160466: Add colors to the pprint module

Doc/library/pprint.rst

@@ -32,7 +32,7 @@ Functions
 
 .. function:: pp(object, stream=None, indent=1, width=80, depth=None, *, \
                  compact=False, expand=False, sort_dicts=False, \
-                 underscore_numbers=False)
+                 underscore_numbers=False, color=None)
 
    Prints the formatted representation of *object*, followed by a newline.
    This function may be used in the interactive interpreter
@@ -88,6 +88,15 @@ Functions
       integers will be formatted with the ``_`` character for a thousands separator,
       otherwise underscores are not displayed (the default).
 
+   :param color:
+      Whether to syntax highlight the output using ANSI escape sequences.
+      If ``None`` (the default), color is enabled when the *stream* and
+      :ref:`environment variables <using-on-controlling-color>` permit.
+      If ``True``, color is always enabled.
+      If ``False``, color is always disabled.
+      Added escape sequences do not count towards *width*.
+   :type color: bool | None
+
    >>> import pprint
    >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
    >>> stuff.insert(0, stuff)
@@ -101,25 +110,38 @@ Functions
 
    .. versionadded:: 3.8
 
+   .. versionchanged:: 3.16
+      Added the *color* parameter.
+
 
 .. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
                      compact=False, expand=False, sort_dicts=True, \
-                     underscore_numbers=False)
+                     underscore_numbers=False, color=None)
 
    Alias for :func:`~pprint.pp` with *sort_dicts* set to ``True`` by default,
    which would automatically sort the dictionaries' keys,
    you might want to use :func:`~pprint.pp` instead where it is ``False`` by default.
 
+   .. versionchanged:: 3.16
+      Added the *color* parameter.
+
 
 .. function:: pformat(object, indent=1, width=80, depth=None, *, \
                       compact=False, expand=False, sort_dicts=True, \
-                      underscore_numbers=False)
+                      underscore_numbers=False, color=False)
 
    Return the formatted representation of *object* as a string.  *indent*,
    *width*, *depth*, *compact*, *expand*, *sort_dicts* and *underscore_numbers* are
    passed to the :class:`PrettyPrinter` constructor as formatting parameters
    and their meanings are as described in the documentation above.
 
+   If *color* is ``True``, the returned string is syntax highlighted using ANSI
+   escape sequences. If ``False`` (the default) or ``None``, the returned string
+   contains no added color escape sequences.
+
+   .. versionchanged:: 3.16
+      Added the *color* parameter.
+
 
 .. function:: isreadable(object)
 
@@ -161,7 +183,7 @@ PrettyPrinter Objects
 
 .. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \
                          compact=False, expand=False, sort_dicts=True, \
-                         underscore_numbers=False)
+                         underscore_numbers=False, color=None)
 
    Construct a :class:`PrettyPrinter` instance.
 
@@ -223,6 +245,9 @@ PrettyPrinter Objects
    .. versionchanged:: 3.15
       Added the *expand* parameter.
 
+   .. versionchanged:: 3.16
+      Added the *color* parameter.
+
 
 :class:`PrettyPrinter` instances have the following methods:
 
@@ -231,6 +256,8 @@ PrettyPrinter Objects
 
    Return the formatted representation of *object*.  This takes into account the
    options passed to the :class:`PrettyPrinter` constructor.
+   Color is enabled only when the constructor's *color* argument is ``True``;
+   ``None`` (the default) and ``False`` disable color in the returned string.
 
 
 .. method:: PrettyPrinter.pprint(object)

Doc/whatsnew/3.16.rst

@@ -618,6 +618,20 @@ pickle
   :class:`!WeakMethod` and :class:`!WeakSet` can now also be copied.
   (Contributed by Serhiy Storchaka in :gh:`74876`.)
 
+
+pprint
+------
+
+* Add the *color* parameter to :func:`pprint.pp`, :func:`pprint.pprint`,
+  :func:`pprint.pformat`, and :class:`pprint.PrettyPrinter`.
+  Output written to a stream is syntax highlighted by default when the stream
+  and :ref:`environment variables <using-on-controlling-color>` permit.
+  Set *color* to ``True`` to force color, or ``False`` to disable it.
+  Strings returned by :func:`~pprint.pformat` or
+  :meth:`.PrettyPrinter.pformat` are highlighted only when *color* is ``True``.
+  (Contributed by Hugo van Kemenade and Peter Bierma in :gh:`145217`.)
+
+
 quopri
 ------