Skip to content

Commit

Permalink
Move pprinter parameters description to the table
Browse files Browse the repository at this point in the history
The change improves readability.
Suggested in the GH#116085 PR discussion.
  • Loading branch information
Privat33r-dev committed Mar 31, 2024
1 parent bfc57d4 commit 33e0842
Showing 1 changed file with 42 additions and 40 deletions.
82 changes: 42 additions & 40 deletions Doc/library/pprint.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <sequence>` 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)
Expand Down Expand Up @@ -120,51 +159,14 @@ 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, *, \
compact=False, sort_dicts=True, underscore_numbers=False)

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 <prettyprinter-parameters>`.

.. versionchanged:: 3.4
Added the *compact* parameter.
Expand Down

0 comments on commit 33e0842

Please sign in to comment.