Skip to content

Commit

Permalink
pythonGH-115986 Reorder pprint docs and amend some references (python…
Browse files Browse the repository at this point in the history 
…#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.
  • Loading branch information
@Privat33r-dev @adorilson
Privat33r-dev authored and adorilson committed Mar 25, 2024
1 parent 74817ee commit 1c688fe
Showing 1 changed file with 92 additions and 89 deletions.
181 changes: 92 additions & 89 deletions Doc/library/pprint.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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']
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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',
Expand Down

0 comments on commit 1c688fe

Please sign in to comment.