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

2 files changed, 41 insertions, 17 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)
diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index 68a278c..3672955 100644
--- a/Doc/tools/susp-ignored.csv
+++ b/Doc/tools/susp-ignored.csv
@@ -180,15 +180,15 @@ library/pickle,,:memory,"conn = sqlite3.connect("":memory:"")"
 library/posix,,`,"CFLAGS=""`getconf LFS_CFLAGS`"" OPT=""-g -O2 $CFLAGS"""
 library/pprint,,::,"'Programming Language :: Python :: 2.6',"
 library/pprint,,::,"'Programming Language :: Python :: 2.7',"
-library/pprint,225,::,"'classifiers': ['Development Status :: 3 - Alpha',"
-library/pprint,225,::,"'Intended Audience :: Developers',"
-library/pprint,225,::,"'License :: OSI Approved :: MIT License',"
-library/pprint,225,::,"'Programming Language :: Python :: 2',"
-library/pprint,225,::,"'Programming Language :: Python :: 3',"
-library/pprint,225,::,"'Programming Language :: Python :: 3.2',"
-library/pprint,225,::,"'Programming Language :: Python :: 3.3',"
-library/pprint,225,::,"'Programming Language :: Python :: 3.4',"
-library/pprint,225,::,"'Topic :: Software Development :: Build Tools'],"
+library/pprint,,::,"'classifiers': ['Development Status :: 3 - Alpha',"
+library/pprint,,::,"'Intended Audience :: Developers',"
+library/pprint,,::,"'License :: OSI Approved :: MIT License',"
+library/pprint,,::,"'Programming Language :: Python :: 2',"
+library/pprint,,::,"'Programming Language :: Python :: 3',"
+library/pprint,,::,"'Programming Language :: Python :: 3.2',"
+library/pprint,,::,"'Programming Language :: Python :: 3.3',"
+library/pprint,,::,"'Programming Language :: Python :: 3.4',"
+library/pprint,,::,"'Topic :: Software Development :: Build Tools'],"
 library/profile,,:lineno,filename:lineno(function)
 library/pyexpat,,:elem1,<py:elem1 />
 library/pyexpat,,:py,"xmlns:py = ""http://www.python.org/ns/"">"