Skip to content

Commit

Permalink
[3.13] gh-115986 Improve pprint docs formatting (GH-117401) (GH-121098)
Browse files Browse the repository at this point in the history 
* Move pprinter parameter descriptions to a table

* Make pprint doc with params markup

* Remove duplication of the parameters' description

---------

(cherry picked from commit 0890ad7)

Co-authored-by: Kerim Kabirov <the.privat33r+gh@pm.me>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
  • Loading branch information
@miss-islington @Privat33r-dev @hugovk
3 people authored Jun 28, 2024
1 parent 4970476 commit 394dc93
Showing 1 changed file with 89 additions and 91 deletions.
180 changes: 89 additions & 91 deletions Doc/library/pprint.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,52 +35,85 @@ Dictionaries are sorted by key before the display is computed.
Functions
---------

.. 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* and *kwargs* will be passed to :func:`~pprint.pprint` as formatting
parameters.

>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pp(stuff)
[<Recursion on list with id=...>,
'spam',
'eggs',
'lumberjack',
'knights',
'ni']
.. function:: pp(object, stream=None, indent=1, width=80, depth=None, *, \
compact=False, sort_dicts=False, underscore_numbers=False)

Prints the formatted representation of *object*, followed by a newline.
This function may be used in the interactive interpreter
instead of the :func:`print` function for inspecting values.
Tip: you can reassign ``print = pprint.pp`` for use within a scope.

:param object:
The object to be printed.

:param stream:
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.
:type stream: :term:`file-like object` | None

:param int indent:
The amount of indentation added for each nesting level.

:param int width:
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.

:param depth:
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.
:type depth: int | None

:param bool compact:
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.

:param bool sort_dicts:
If ``True``, dictionaries will be formatted with
their keys sorted, otherwise
they will be displayed in insertion order (the default).

:param bool underscore_numbers:
If ``True``,
integers will be formatted with the ``_`` character for a thousands separator,
otherwise underscores are not displayed (the default).

>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pp(stuff)
[<Recursion on list with id=...>,
'spam',
'eggs',
'lumberjack',
'knights',
'ni']

.. versionadded:: 3.8


.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
compact=False, sort_dicts=True, underscore_numbers=False)

Prints the formatted representation of *object* on *stream*, followed by a
newline. If *stream* is ``None``, :data:`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).

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.
Alias for :func:`~pprint.pp` with *sort_dicts* set to ``True`` by default,
which would automatically sort the dictionaries' keys,
you might want to use :func:`~pprint.pp` instead where it is ``False`` by default.

Note that *sort_dicts* is ``True`` by default and you might want to use
:func:`~pprint.pp` instead where it is ``False`` by 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 @@ -119,51 +152,39 @@ 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.
Construct a :class:`PrettyPrinter` instance.

Other values configure the manner in which nesting of complex data
structures is displayed.
Arguments have the same meaning as for :func:`~pprint.pp`.
Note that they are in a different order, and that *sort_dicts* defaults to ``True``.

*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.
>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
'spam',
'eggs',
'lumberjack',
'knights',
'ni']
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
>>> pp.pprint(stuff)
[['spam', 'eggs', 'lumberjack',
'knights', 'ni'],
'spam', 'eggs', 'lumberjack', 'knights',
'ni']
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))

If *underscore_numbers* is true, integers will be formatted with the
``_`` character for a thousands separator, otherwise underscores are not
displayed (the default).

.. versionchanged:: 3.4
Added the *compact* parameter.
Expand All @@ -177,29 +198,6 @@ This module defines one class:
.. versionchanged:: 3.11
No longer attempts to write to :data:`!sys.stdout` if it is ``None``.

>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff[:])
>>> pp = pprint.PrettyPrinter(indent=4)
>>> pp.pprint(stuff)
[ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
'spam',
'eggs',
'lumberjack',
'knights',
'ni']
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
>>> pp.pprint(stuff)
[['spam', 'eggs', 'lumberjack',
'knights', 'ni'],
'spam', 'eggs', 'lumberjack', 'knights',
'ni']
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> pp = pprint.PrettyPrinter(depth=6)
>>> pp.pprint(tup)
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))


:class:`PrettyPrinter` instances have the following methods:

Expand Down

0 comments on commit 394dc93

Please sign in to comment.