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 02bb367

Browse filesBrowse files
erlend-aaslandPrivat33r-dev
erlend-aasland
and
Privat33r-dev
authored
[3.11] GH-115986 Reorder pprint docs and amend some references (#116019) (#116064)
(cherry picked from commit 6c1c94d) 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-dev@users.noreply.github.com>
1 parent 99ab0d4 commit 02bb367
Copy full SHA for 02bb367

File tree

Expand file treeCollapse file tree

1 file changed

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

1 file changed

+89
-85
lines changed

‎Doc/library/pprint.rst

Copy file name to clipboardExpand all lines: Doc/library/pprint.rst
+89-85Lines changed: 89 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,90 @@ 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.
99+
100+
101+
.. function:: saferepr(object)
102+
103+
Return a string representation of *object*, protected against recursive data
104+
structures. If the representation of *object* exposes a recursive entry, the
105+
recursive reference will be represented as ``<Recursion on typename with
106+
id=number>``. The representation is not otherwise formatted.
107+
108+
>>> pprint.saferepr(stuff)
109+
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
110+
111+
112+
.. _prettyprinter-objects:
113+
114+
PrettyPrinter Objects
115+
---------------------
116+
117+
This module defines one class:
35118

36119
.. First the implementation class:
37120
@@ -44,9 +127,9 @@ The :mod:`pprint` module defines one class:
44127
Construct a :class:`PrettyPrinter` instance. This constructor understands
45128
several keyword parameters.
46129

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

52135
Other values configure the manner in which nesting of complex data
@@ -87,7 +170,7 @@ The :mod:`pprint` module defines one class:
87170
Added the *underscore_numbers* parameter.
88171

89172
.. versionchanged:: 3.11
90-
No longer attempts to write to ``sys.stdout`` if it is ``None``.
173+
No longer attempts to write to :data:`!sys.stdout` if it is ``None``.
91174

92175
>>> import pprint
93176
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
@@ -112,85 +195,6 @@ The :mod:`pprint` module defines one class:
112195
>>> pp.pprint(tup)
113196
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
114197

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.
175-
176-
177-
One more support function is also defined:
178-
179-
.. function:: saferepr(object)
180-
181-
Return a string representation of *object*, protected against recursive data
182-
structures. If the representation of *object* exposes a recursive entry, the
183-
recursive reference will be represented as ``<Recursion on typename with
184-
id=number>``. The representation is not otherwise formatted.
185-
186-
>>> pprint.saferepr(stuff)
187-
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
188-
189-
190-
.. _prettyprinter-objects:
191-
192-
PrettyPrinter Objects
193-
---------------------
194198

195199
:class:`PrettyPrinter` instances have the following methods:
196200

@@ -254,7 +258,7 @@ are converted to strings. The default implementation uses the internals of the
254258
Example
255259
-------
256260

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

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

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

268272
>>> pprint.pprint(project_info)
269273
{'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.