diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index eebd270a096ba5f..f85b46c6aeca451 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -70,18 +70,57 @@ Functions The configuration parameters *stream*, *indent*, *width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are passed to the :class:`PrettyPrinter` constructor and their meanings are as - described in its documentation below. + described in the documentation below. Note that *sort_dicts* is ``True`` by default and you might want to use :func:`~pprint.pp` instead where it is ``False`` by default. +.. _prettyprinter-parameters: + +.. list-table:: **Recognised parameters for PrettyPrinter** + :header-rows: 1 + :widths: 20 80 + + * - Parameter + - Description + * - ``indent``: ``int`` + - The amount of indentation added for each nesting level. + * - ``width``: ``int`` + - The desired maximum number of characters per line in the output. + If a structure cannot be formatted within the width constraint, + a best effort will be made. + * - ``depth``: ``int`` | ``None`` + - The number of nesting levels which may be printed. + If the data structure being printed is too deep, + the next contained level is replaced by ``...``. + If ``None`` (the default), there is no constraint + on the depth of the objects being formatted. + * - ``stream``: :term:`file-like object` | ``None`` + - A file-like object to which the output will be written + by calling its :meth:`!write` method. + If ``None`` (the default), :data:`sys.stdout` is used. + * - ``compact``: ``bool`` + - Control the way long :term:`sequences ` are formatted. + If ``False`` (the default), + each item of a sequence will be formatted on a separate line, + otherwise as many items as will fit within the *width* + will be formatted on each output line. + * - ``sort_dicts``: ``bool`` + - If ``True`` (the default), dictionaries will be formatted with + their keys sorted, otherwise they will display in insertion order. + * - ``underscore_numbers``: ``bool`` + - If ``True``, + integers will be formatted with the ``_`` character for a thousands separator, + otherwise underscores are not displayed (the default). + + .. function:: pformat(object, indent=1, width=80, depth=None, *, \ compact=False, sort_dicts=True, underscore_numbers=False) Return the formatted representation of *object* as a string. *indent*, *width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are passed to the :class:`PrettyPrinter` constructor as formatting parameters - and their meanings are as described in its documentation below. + and their meanings are as described in the documentation above. .. function:: isreadable(object) @@ -120,11 +159,6 @@ Functions PrettyPrinter Objects --------------------- -This module defines one class: - -.. First the implementation class: - - .. index:: single: ...; placeholder .. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \ @@ -132,39 +166,7 @@ This module defines one class: Construct a :class:`PrettyPrinter` instance. This constructor understands several keyword parameters. - - *stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to - which the output will be written by calling its :meth:`!write` method. - If both *stream* and :data:`!sys.stdout` are ``None``, then - :meth:`~PrettyPrinter.pprint` silently returns. - - Other values configure the manner in which nesting of complex data - structures is displayed. - - *indent* (default 1) specifies the amount of indentation added for - each nesting level. - - *depth* controls the number of nesting levels which may be printed; if - the data structure being printed is too deep, the next contained level - is replaced by ``...``. By default, there is no constraint on the - depth of the objects being formatted. - - *width* (default 80) specifies the desired maximum number of characters per - 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). + Parameters described at :ref:`parameters table `. .. versionchanged:: 3.4 Added the *compact* parameter.