bpo-30670: Add pp function to the pprint module (GH-11769)

1 files changed, 32 insertions, 8 deletions

diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
index deadf18..988f85b 100644
--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
@@ -33,7 +33,7 @@ The :mod:`pprint` module defines one class:
 .. index:: single: ...; placeholder
 
 .. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \
-                         compact=False)
+                         compact=False, sort_dicts=True)
 
    Construct a :class:`PrettyPrinter` instance.  This constructor understands
    several keyword parameters.  An output stream may be set using the *stream*
@@ -50,11 +50,17 @@ The :mod:`pprint` module defines one class:
    structure cannot be formatted within the constrained width, a best effort will
    be made.  If *compact* is false (the default) each item of a long sequence
    will be formatted on a separate line.  If *compact* is true, as many items
-   as will fit within the *width* will be formatted on each output line.
+   as will fit within the *width* will be formatted on each output line. If
+   *sort_dicts* is true (the default), dictionaries will be formatted with their
+   keys sorted, otherwise they will display in insertion order.
 
    .. versionchanged:: 3.4
       Added the *compact* parameter.
 
+   .. versionchanged:: 3.8
+      Added the *sort_dicts* parameter.
+
+
       >>> import pprint
       >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
       >>> stuff.insert(0, stuff[:])
@@ -81,29 +87,47 @@ The :mod:`pprint` module defines one class:
 
 The :mod:`pprint` module also provides several shortcut functions:
 
-.. function:: pformat(object, indent=1, width=80, depth=None, *, compact=False)
+.. function:: pformat(object, indent=1, width=80, depth=None, *, \
+                      compact=False, sort_dicts=True)
 
    Return the formatted representation of *object* as a string.  *indent*,
-   *width*, *depth* and *compact* will be passed to the :class:`PrettyPrinter`
-   constructor as formatting parameters.
+   *width*, *depth*, *compact* and *sort_dicts* will be passed to the
+   :class:`PrettyPrinter` constructor as formatting parameters.
 
    .. versionchanged:: 3.4
       Added the *compact* parameter.
 
+   .. versionchanged:: 3.8
+      Added the *sort_dicts* parameter.
+
+
+.. function:: pp(object, *args, sort_dicts=False, **kwargs)
+
+   Prints the formatted representation of *object* followed by a newline.
+   If *sort_dicts* is false (the default), dictionaries will be displayed with
+   their keys in insertion order, otherwise the dict keys will be sorted.
+   *args* an *kwargs* will be passed to :func:`pprint` as formatting
+   parameters.
+
+   .. versionadded:: 3.8
+
 
 .. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
-                     compact=False)
+                     compact=False, sort_dicts=True)
 
    Prints the formatted representation of *object* on *stream*, followed by a
    newline.  If *stream* is ``None``, ``sys.stdout`` is used.  This may be used
    in the interactive interpreter instead of the :func:`print` function for
    inspecting values (you can even reassign ``print = pprint.pprint`` for use
-   within a scope).  *indent*, *width*, *depth* and *compact* will be passed
-   to the :class:`PrettyPrinter` constructor as formatting parameters.
+   within a scope).  *indent*, *width*, *depth*, *compact* and *sort_dicts* will
+   be passed to the :class:`PrettyPrinter` constructor as formatting parameters.
 
    .. versionchanged:: 3.4
       Added the *compact* parameter.
 
+   .. versionchanged:: 3.8
+      Added the *sort_dicts* parameter.
+
       >>> import pprint
       >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
       >>> stuff.insert(0, stuff)