Skip to content

gh-115986 Improve pprint docs formatting #117401

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Jun 27, 2024
Merged

gh-115986 Improve pprint docs formatting #117401

Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
cc92c08
Move pprinter parameters description to the table
Privat33r-dev Mar 31, 2024
5797858
Make pprint doc with params markup
Privat33r-dev Apr 30, 2024
e614722
Fix formatting
Privat33r-dev May 2, 2024
ebcafbf
Fix formatting for tests
Privat33r-dev May 2, 2024
a79de4a
fix code indentation for autotests
Privat33r-dev May 2, 2024
5461f94
Fix identation for autotests
Privat33r-dev May 2, 2024
aeb9488
Remove duplication of the parameters' description
Privat33r-dev Jun 26, 2024
4283ad1
Rearrange parameters description in a correct order
Privat33r-dev Jun 26, 2024
3918538
Merge branch 'main' into add-params-table-115986
hugovk Jun 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 89 additions & 91 deletions Doc/library/pprint.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,52 +36,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 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 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 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation for PrettyPrinter is still below. Maybe this should be:

The arguments have the same meaning as for :func:`~pprint.pprint`.
Note that *sort_dicts* defaults to ``True``.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's why "its" was changed to "the", as arguments description is above (in the pp.pprint description).



.. function:: isreadable(object)
Expand Down Expand Up @@ -120,51 +153,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 @@ -178,29 +199,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
Loading