mirror of https://github.com/python/cpython
[3.13] gh-115986 Improve pprint docs formatting (GH-117401) (GH-121098)
* Move pprinter parameter descriptions to a table
* Make pprint doc with params markup
* Remove duplication of the parameters' description
---------
(cherry picked from commit 0890ad7c02)
Co-authored-by: Kerim Kabirov <the.privat33r+gh@pm.me>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot)
GitHub
parent
497047606d
commit
394dc93bf9
|
|
@ -35,24 +35,66 @@ Dictionaries are sorted by key before the display is computed.
|
|||
Functions
|
||||
---------
|
||||
|
||||
.. function:: pp(object, *args, sort_dicts=False, **kwargs)
|
||||
.. 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.
|
||||
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.
|
||||
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.
|
||||
|
||||
>>> 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']
|
||||
: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
|
||||
|
||||
|
|
@ -60,19 +102,10 @@ Functions
|
|||
.. 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).
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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)
|
||||
|
|
@ -80,7 +113,7 @@ Functions
|
|||
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)
|
||||
|
|
@ -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.
|
||||
Construct a :class:`PrettyPrinter` instance.
|
||||
|
||||
*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.
|
||||
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``.
|
||||
|
||||
Other values configure the manner in which nesting of complex data
|
||||
structures is displayed.
|
||||
>>> 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', (...)))))))
|
||||
|
||||
*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).
|
||||
|
||||
.. versionchanged:: 3.4
|
||||
Added the *compact* parameter.
|
||||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue