Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 91e680b

Browse filesBrowse files
miss-islingtonPrivat33r-dev
miss-islington
and
Privat33r-dev
authored
[3.12] GH-115986 Reorder pprint docs and amend some references (GH-116019) (#116061)
GH-115986 Reorder pprint docs and amend some references (GH-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. (cherry picked from commit 6c1c94d) Co-authored-by: Kerim Kabirov <39376984+Privat33r-dev@users.noreply.github.com>
1 parent 9df6d1e commit 91e680b
Copy full SHA for 91e680b

File tree

Expand file treeCollapse file tree

1 file changed

+92
-89
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+92
-89
lines changed

‎Doc/library/pprint.rst

Copy file name to clipboardExpand all lines: Doc/library/pprint.rst
+92-89Lines changed: 92 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,93 @@ Dictionaries are sorted by key before the display is computed.
3131
.. versionchanged:: 3.10
3232
Added support for pretty-printing :class:`dataclasses.dataclass`.
3333

34-
The :mod:`pprint` module defines one class:
34+
.. _pprint-functions:
35+
36+
Functions
37+
---------
38+
39+
.. function:: pp(object, *args, sort_dicts=False, **kwargs)
40+
41+
Prints the formatted representation of *object* followed by a newline.
42+
If *sort_dicts* is false (the default), dictionaries will be displayed with
43+
their keys in insertion order, otherwise the dict keys will be sorted.
44+
*args* and *kwargs* will be passed to :func:`~pprint.pprint` as formatting
45+
parameters.
46+
47+
.. versionadded:: 3.8
48+
49+
50+
.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
51+
compact=False, sort_dicts=True, underscore_numbers=False)
52+
53+
Prints the formatted representation of *object* on *stream*, followed by a
54+
newline. If *stream* is ``None``, :data:`sys.stdout` is used. This may be used
55+
in the interactive interpreter instead of the :func:`print` function for
56+
inspecting values (you can even reassign ``print = pprint.pprint`` for use
57+
within a scope).
58+
59+
The configuration parameters *stream*, *indent*, *width*, *depth*,
60+
*compact*, *sort_dicts* and *underscore_numbers* are passed to the
61+
:class:`PrettyPrinter` constructor and their meanings are as
62+
described in its documentation above.
63+
64+
>>> import pprint
65+
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
66+
>>> stuff.insert(0, stuff)
67+
>>> pprint.pprint(stuff)
68+
[<Recursion on list with id=...>,
69+
'spam',
70+
'eggs',
71+
'lumberjack',
72+
'knights',
73+
'ni']
74+
75+
.. function:: pformat(object, indent=1, width=80, depth=None, *, \
76+
compact=False, sort_dicts=True, underscore_numbers=False)
77+
78+
Return the formatted representation of *object* as a string. *indent*,
79+
*width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
80+
passed to the :class:`PrettyPrinter` constructor as formatting parameters
81+
and their meanings are as described in its documentation above.
82+
83+
84+
.. function:: isreadable(object)
85+
86+
.. index:: pair: built-in function; eval
87+
88+
Determine if the formatted representation of *object* is "readable", or can be
89+
used to reconstruct the value using :func:`eval`. This always returns ``False``
90+
for recursive objects.
91+
92+
>>> pprint.isreadable(stuff)
93+
False
94+
95+
96+
.. function:: isrecursive(object)
97+
98+
Determine if *object* requires a recursive representation. This function is
99+
subject to the same limitations as noted in :func:`saferepr` below and may raise an
100+
:exc:`RecursionError` if it fails to detect a recursive object.
101+
102+
103+
.. function:: saferepr(object)
104+
105+
Return a string representation of *object*, protected against recursion in
106+
some common data structures, namely instances of :class:`dict`, :class:`list`
107+
and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden. If the
108+
representation of object exposes a recursive entry, the recursive reference
109+
will be represented as ``<Recursion on typename with id=number>``. The
110+
representation is not otherwise formatted.
111+
112+
>>> pprint.saferepr(stuff)
113+
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
114+
115+
.. _prettyprinter-objects:
116+
117+
PrettyPrinter Objects
118+
---------------------
119+
120+
This module defines one class:
35121

36122
.. First the implementation class:
37123
@@ -44,9 +130,9 @@ The :mod:`pprint` module defines one class:
44130
Construct a :class:`PrettyPrinter` instance. This constructor understands
45131
several keyword parameters.
46132

47-
*stream* (default ``sys.stdout``) is a :term:`file-like object` to
133+
*stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to
48134
which the output will be written by calling its :meth:`!write` method.
49-
If both *stream* and ``sys.stdout`` are ``None``, then
135+
If both *stream* and :data:`!sys.stdout` are ``None``, then
50136
:meth:`~PrettyPrinter.pprint` silently returns.
51137

52138
Other values configure the manner in which nesting of complex data
@@ -87,7 +173,7 @@ The :mod:`pprint` module defines one class:
87173
Added the *underscore_numbers* parameter.
88174

89175
.. versionchanged:: 3.11
90-
No longer attempts to write to ``sys.stdout`` if it is ``None``.
176+
No longer attempts to write to :data:`!sys.stdout` if it is ``None``.
91177

92178
>>> import pprint
93179
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
@@ -112,89 +198,6 @@ The :mod:`pprint` module defines one class:
112198
>>> pp.pprint(tup)
113199
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
114200

115-
.. function:: pformat(object, indent=1, width=80, depth=None, *, \
116-
compact=False, sort_dicts=True, underscore_numbers=False)
117-
118-
Return the formatted representation of *object* as a string. *indent*,
119-
*width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
120-
passed to the :class:`PrettyPrinter` constructor as formatting parameters
121-
and their meanings are as described in its documentation above.
122-
123-
124-
.. function:: pp(object, *args, sort_dicts=False, **kwargs)
125-
126-
Prints the formatted representation of *object* followed by a newline.
127-
If *sort_dicts* is false (the default), dictionaries will be displayed with
128-
their keys in insertion order, otherwise the dict keys will be sorted.
129-
*args* and *kwargs* will be passed to :func:`pprint` as formatting
130-
parameters.
131-
132-
.. versionadded:: 3.8
133-
134-
135-
.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
136-
compact=False, sort_dicts=True, underscore_numbers=False)
137-
138-
Prints the formatted representation of *object* on *stream*, followed by a
139-
newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used
140-
in the interactive interpreter instead of the :func:`print` function for
141-
inspecting values (you can even reassign ``print = pprint.pprint`` for use
142-
within a scope).
143-
144-
The configuration parameters *stream*, *indent*, *width*, *depth*,
145-
*compact*, *sort_dicts* and *underscore_numbers* are passed to the
146-
:class:`PrettyPrinter` constructor and their meanings are as
147-
described in its documentation above.
148-
149-
>>> import pprint
150-
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
151-
>>> stuff.insert(0, stuff)
152-
>>> pprint.pprint(stuff)
153-
[<Recursion on list with id=...>,
154-
'spam',
155-
'eggs',
156-
'lumberjack',
157-
'knights',
158-
'ni']
159-
160-
.. function:: isreadable(object)
161-
162-
.. index:: pair: built-in function; eval
163-
164-
Determine if the formatted representation of *object* is "readable", or can be
165-
used to reconstruct the value using :func:`eval`. This always returns ``False``
166-
for recursive objects.
167-
168-
>>> pprint.isreadable(stuff)
169-
False
170-
171-
172-
.. function:: isrecursive(object)
173-
174-
Determine if *object* requires a recursive representation. This function is
175-
subject to the same limitations as noted in :func:`saferepr` below and may raise an
176-
:exc:`RecursionError` if it fails to detect a recursive object.
177-
178-
179-
One more support function is also defined:
180-
181-
.. function:: saferepr(object)
182-
183-
Return a string representation of *object*, protected against recursion in
184-
some common data structures, namely instances of :class:`dict`, :class:`list`
185-
and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden. If the
186-
representation of object exposes a recursive entry, the recursive reference
187-
will be represented as ``<Recursion on typename with id=number>``. The
188-
representation is not otherwise formatted.
189-
190-
>>> pprint.saferepr(stuff)
191-
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
192-
193-
194-
.. _prettyprinter-objects:
195-
196-
PrettyPrinter Objects
197-
---------------------
198201

199202
:class:`PrettyPrinter` instances have the following methods:
200203

@@ -258,7 +261,7 @@ are converted to strings. The default implementation uses the internals of the
258261
Example
259262
-------
260263

261-
To demonstrate several uses of the :func:`pprint` function and its parameters,
264+
To demonstrate several uses of the :func:`~pprint.pprint` function and its parameters,
262265
let's fetch information about a project from `PyPI <https://pypi.org>`_::
263266

264267
>>> import json
@@ -267,7 +270,7 @@ let's fetch information about a project from `PyPI <https://pypi.org>`_::
267270
>>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp:
268271
... project_info = json.load(resp)['info']
269272

270-
In its basic form, :func:`pprint` shows the whole object::
273+
In its basic form, :func:`~pprint.pprint` shows the whole object::
271274

272275
>>> pprint.pprint(project_info)
273276
{'author': 'The Python Packaging Authority',

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.