https://github.com/python/cpython/commit/02bb367748121b4c271ac07392820b5136db3571
commit: 02bb367748121b4c271ac07392820b5136db3571
branch: 3.11
author: Erlend E. Aasland <erl...@python.org>
committer: erlend-aasland <erlend.aasl...@protonmail.com>
date: 2024-02-28T20:11:12Z
summary:
[3.11] GH-115986 Reorder pprint docs and amend some references (#116019)
(#116064)
(cherry picked from commit 6c1c94dc517b77afcebb25436a4b7b0d13b6eb4d)
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.
Co-authored-by: Kerim Kabirov <39376984+privat33r-...@users.noreply.github.com>
files:
M Doc/library/pprint.rst
diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
index fa5153284a2aab..e7f0bddc9606f7 100644
--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
@@ -31,7 +31,90 @@ 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.
+
+
+.. function:: saferepr(object)
+
+ Return a string representation of *object*, protected against recursive data
+ structures. 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 +127,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 +170,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,85 +195,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.
-
-
-One more support function is also defined:
-
-.. function:: saferepr(object)
-
- Return a string representation of *object*, protected against recursive data
- structures. 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:
@@ -254,7 +258,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
@@ -263,7 +267,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',
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
