mirror of
https://github.com/python/cpython.git
synced 2024-11-27 11:55:13 +08:00
GH-115986 Reorder pprint docs and amend some references (#116019)
Introduce a new subsubsection, 'Functions', for module level functions,
and place it before the PrettyPrinter class reference.
Also:
- Fix pprint.pprint() references so they properly link to the module
level function.
- Add links to sys.stdout.
This commit is contained in:
Kerim Kabirov
GitHub
parent
e2a3e4b748
commit
6c1c94dc51
@ -31,7 +31,93 @@ Dictionaries are sorted by key before the display is computed.
|
||||
.. versionchanged:: 3.10
|
||||
Added support for pretty-printing :class:`dataclasses.dataclass`.
|
||||
|
||||
The :mod:`pprint` module defines one class:
|
||||
.. _pprint-functions:
|
||||
|
||||
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.
|
||||
|
||||
.. 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 above.
|
||||
|
||||
>>> import pprint
|
||||
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
|
||||
>>> stuff.insert(0, stuff)
|
||||
>>> pprint.pprint(stuff)
|
||||
[<Recursion on list with id=...>,
|
||||
'spam',
|
||||
'eggs',
|
||||
'lumberjack',
|
||||
'knights',
|
||||
'ni']
|
||||
|
||||
.. 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 above.
|
||||
|
||||
|
||||
.. function:: isreadable(object)
|
||||
|
||||
.. index:: pair: built-in function; eval
|
||||
|
||||
Determine if the formatted representation of *object* is "readable", or can be
|
||||
used to reconstruct the value using :func:`eval`. This always returns ``False``
|
||||
for recursive objects.
|
||||
|
||||
>>> pprint.isreadable(stuff)
|
||||
False
|
||||
|
||||
|
||||
.. function:: isrecursive(object)
|
||||
|
||||
Determine if *object* requires a recursive representation. This function is
|
||||
subject to the same limitations as noted in :func:`saferepr` below and may raise an
|
||||
:exc:`RecursionError` if it fails to detect a recursive object.
|
||||
|
||||
|
||||
.. function:: saferepr(object)
|
||||
|
||||
Return a string representation of *object*, protected against recursion in
|
||||
some common data structures, namely instances of :class:`dict`, :class:`list`
|
||||
and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden. If the
|
||||
representation of object exposes a recursive entry, the recursive reference
|
||||
will be represented as ``<Recursion on typename with id=number>``. The
|
||||
representation is not otherwise formatted.
|
||||
|
||||
>>> pprint.saferepr(stuff)
|
||||
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
|
||||
|
||||
.. _prettyprinter-objects:
|
||||
|
||||
PrettyPrinter Objects
|
||||
---------------------
|
||||
|
||||
This module defines one class:
|
||||
|
||||
.. First the implementation class:
|
||||
|
||||
@ -44,9 +130,9 @@ The :mod:`pprint` module defines one class:
|
||||
Construct a :class:`PrettyPrinter` instance. This constructor understands
|
||||
several keyword parameters.
|
||||
|
||||
*stream* (default ``sys.stdout``) is a :term:`file-like object` to
|
||||
*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 ``sys.stdout`` are ``None``, then
|
||||
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
|
||||
@ -87,7 +173,7 @@ The :mod:`pprint` module defines one class:
|
||||
Added the *underscore_numbers* parameter.
|
||||
|
||||
.. versionchanged:: 3.11
|
||||
No longer attempts to write to ``sys.stdout`` if it is ``None``.
|
||||
No longer attempts to write to :data:`!sys.stdout` if it is ``None``.
|
||||
|
||||
>>> import pprint
|
||||
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
|
||||
@ -112,89 +198,6 @@ The :mod:`pprint` module defines one class:
|
||||
>>> pp.pprint(tup)
|
||||
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
|
||||
|
||||
.. 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 above.
|
||||
|
||||
|
||||
.. 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` as formatting
|
||||
parameters.
|
||||
|
||||
.. 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``, ``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 above.
|
||||
|
||||
>>> import pprint
|
||||
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
|
||||
>>> stuff.insert(0, stuff)
|
||||
>>> pprint.pprint(stuff)
|
||||
[<Recursion on list with id=...>,
|
||||
'spam',
|
||||
'eggs',
|
||||
'lumberjack',
|
||||
'knights',
|
||||
'ni']
|
||||
|
||||
.. function:: isreadable(object)
|
||||
|
||||
.. index:: pair: built-in function; eval
|
||||
|
||||
Determine if the formatted representation of *object* is "readable", or can be
|
||||
used to reconstruct the value using :func:`eval`. This always returns ``False``
|
||||
for recursive objects.
|
||||
|
||||
>>> pprint.isreadable(stuff)
|
||||
False
|
||||
|
||||
|
||||
.. function:: isrecursive(object)
|
||||
|
||||
Determine if *object* requires a recursive representation. This function is
|
||||
subject to the same limitations as noted in :func:`saferepr` below and may raise an
|
||||
:exc:`RecursionError` if it fails to detect a recursive object.
|
||||
|
||||
|
||||
One more support function is also defined:
|
||||
|
||||
.. function:: saferepr(object)
|
||||
|
||||
Return a string representation of *object*, protected against recursion in
|
||||
some common data structures, namely instances of :class:`dict`, :class:`list`
|
||||
and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden. If the
|
||||
representation of object exposes a recursive entry, the recursive reference
|
||||
will be represented as ``<Recursion on typename with id=number>``. The
|
||||
representation is not otherwise formatted.
|
||||
|
||||
>>> pprint.saferepr(stuff)
|
||||
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
|
||||
|
||||
|
||||
.. _prettyprinter-objects:
|
||||
|
||||
PrettyPrinter Objects
|
||||
---------------------
|
||||
|
||||
:class:`PrettyPrinter` instances have the following methods:
|
||||
|
||||
@ -258,7 +261,7 @@ are converted to strings. The default implementation uses the internals of the
|
||||
Example
|
||||
-------
|
||||
|
||||
To demonstrate several uses of the :func:`pprint` function and its parameters,
|
||||
To demonstrate several uses of the :func:`~pprint.pprint` function and its parameters,
|
||||
let's fetch information about a project from `PyPI <https://pypi.org>`_::
|
||||
|
||||
>>> import json
|
||||
@ -267,7 +270,7 @@ let's fetch information about a project from `PyPI <https://pypi.org>`_::
|
||||
>>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp:
|
||||
... project_info = json.load(resp)['info']
|
||||
|
||||
In its basic form, :func:`pprint` shows the whole object::
|
||||
In its basic form, :func:`~pprint.pprint` shows the whole object::
|
||||
|
||||
>>> pprint.pprint(project_info)
|
||||
{'author': 'The Python Packaging Authority',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user