Skip to content

Commit 72fefb5

Browse files
Privat33r-devPrivat33r-dev
authored andcommitted
GH-115986 Doc: change 'pprint' module documentation's structure
Ensure `pp` and `pprint` are positioned prominently at the top of the page.
1 parent 686ec17 commit 72fefb5

File tree

1 file changed

+83
-79
lines changed

1 file changed

+83
-79
lines changed

Doc/library/pprint.rst

Lines changed: 83 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,89 @@ 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+
35+
This module defines the following functions:
36+
37+
.. function:: pp(object, *args, sort_dicts=False, **kwargs)
38+
39+
Prints the formatted representation of *object* followed by a newline.
40+
If *sort_dicts* is false (the default), dictionaries will be displayed with
41+
their keys in insertion order, otherwise the dict keys will be sorted.
42+
*args* and *kwargs* will be passed to :func:`pprint` as formatting
43+
parameters.
44+
45+
.. versionadded:: 3.8
46+
47+
48+
.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
49+
compact=False, sort_dicts=True, underscore_numbers=False)
50+
51+
Prints the formatted representation of *object* on *stream*, followed by a
52+
newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used
53+
in the interactive interpreter instead of the :func:`print` function for
54+
inspecting values (you can even reassign ``print = pprint.pprint`` for use
55+
within a scope).
56+
57+
The configuration parameters *stream*, *indent*, *width*, *depth*,
58+
*compact*, *sort_dicts* and *underscore_numbers* are passed to the
59+
:class:`PrettyPrinter` constructor and their meanings are as
60+
described in its documentation above.
61+
62+
>>> import pprint
63+
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
64+
>>> stuff.insert(0, stuff)
65+
>>> pprint.pprint(stuff)
66+
[<Recursion on list with id=...>,
67+
'spam',
68+
'eggs',
69+
'lumberjack',
70+
'knights',
71+
'ni']
72+
73+
.. function:: pformat(object, indent=1, width=80, depth=None, *, \
74+
compact=False, sort_dicts=True, underscore_numbers=False)
75+
76+
Return the formatted representation of *object* as a string. *indent*,
77+
*width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
78+
passed to the :class:`PrettyPrinter` constructor as formatting parameters
79+
and their meanings are as described in its documentation above.
80+
81+
82+
.. function:: isreadable(object)
83+
84+
.. index:: pair: built-in function; eval
85+
86+
Determine if the formatted representation of *object* is "readable", or can be
87+
used to reconstruct the value using :func:`eval`. This always returns ``False``
88+
for recursive objects.
89+
90+
>>> pprint.isreadable(stuff)
91+
False
92+
93+
94+
.. function:: isrecursive(object)
95+
96+
Determine if *object* requires a recursive representation. This function is
97+
subject to the same limitations as noted in :func:`saferepr` below and may raise an
98+
:exc:`RecursionError` if it fails to detect a recursive object.
99+
100+
101+
One more support function is also defined:
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+
116+
This module defines one class:
35117

36118
.. First the implementation class:
37119
@@ -112,84 +194,6 @@ The :mod:`pprint` module defines one class:
112194
>>> pp.pprint(tup)
113195
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
114196

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-
193197

194198
.. _prettyprinter-objects:
195199

0 commit comments

Comments
 (0)