bpo-34798: [doc] clearer presentation of pprint.PrettyPrinter constru… (GH-26967)

Doc/library/pprint.rst

@@ -42,24 +42,36 @@ The :mod:`pprint` module defines one class:
                          compact=False, sort_dicts=True, underscore_numbers=False)
 
    Construct a :class:`PrettyPrinter` instance.  This constructor understands
-   several keyword parameters.  An output stream may be set using the *stream*
+   several keyword parameters.
-   keyword; the only method used on the stream object is the file protocol's
+
-   :meth:`write` method.  If not specified, the :class:`PrettyPrinter` adopts
+   *stream* (default ``sys.stdout``) is a :term:`file-like object` to
-   ``sys.stdout``.  The
+   which the output will be written by calling its :meth:`write` method.
-   amount of indentation added for each recursive level is specified by *indent*;
+
-   the default is one.  Other values can cause output to look a little odd, but can
+   Other values configure the manner in which nesting of complex data
-   make nesting easier to spot.  The number of levels which may be printed is
+   structures is displayed.
-   controlled by *depth*; if the data structure being printed is too deep, the next
+
-   contained level is replaced by ``...``.  By default, there is no constraint on
+   *indent* (default 1) specifies the amount of indentation added for
-   the depth of the objects being formatted.  The desired output width is
+   each nesting level.
-   constrained using the *width* parameter; the default is 80 characters.  If a
+
-   structure cannot be formatted within the constrained width, a best effort will
+   *depth* controls the number of nesting levels which may be printed; if
-   be made.  If *compact* is false (the default) each item of a long sequence
+   the data structure being printed is too deep, the next contained level
-   will be formatted on a separate line.  If *compact* is true, as many items
+   is replaced by ``...``.  By default, there is no constraint on the
-   as will fit within the *width* will be formatted on each output line. If
+   depth of the objects being formatted.
-   *sort_dicts* is true (the default), dictionaries will be formatted with their
+
-   keys sorted, otherwise they will display in insertion order.  If
+   *width* (default 80) specifies the desired maximum number of characters per
-   *underscore_numbers* is true, integers will be formatted with the
+   line in the output. If a structure cannot be formatted within the width
+   constraint, a best effort will be made.
+
+   *compact* impacts the way that long sequences (lists, tuples, sets, etc)
+   are formatted. If *compact* is false (the default) then each item of a
+   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.
+
+   If *sort_dicts* is true (the default), dictionaries will be formatted with
+   their keys sorted, otherwise they will display in insertion order.
+
+   If *underscore_numbers* is true, integers will be formatted with the
    ``_`` character for a thousands separator, otherwise underscores are not
    displayed (the default).
 

Misc/NEWS.d/next/Library/2021-06-30-13-29-49.bpo-34798.t7FCa0.rst

@@ -0,0 +1 @@
+Break up paragraph about :class:`pprint.PrettyPrinter` construction parameters to make it easier to read.