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 394dc93

Browse filesBrowse files
miss-islingtonPrivat33r-devhugovk
authored
[3.13] gh-115986 Improve pprint docs formatting (GH-117401) (GH-121098)
* Move pprinter parameter descriptions to a table * Make pprint doc with params markup * Remove duplication of the parameters' description --------- (cherry picked from commit 0890ad7) Co-authored-by: Kerim Kabirov <the.privat33r+gh@pm.me> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
1 parent 4970476 commit 394dc93
Copy full SHA for 394dc93

File tree

Expand file treeCollapse file tree

1 file changed

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

1 file changed

+89
-91
lines changed

‎Doc/library/pprint.rst

Copy file name to clipboardExpand all lines: Doc/library/pprint.rst
+89-91Lines changed: 89 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -35,52 +35,85 @@ Dictionaries are sorted by key before the display is computed.
3535
Functions
3636
---------
3737

38-
.. function:: pp(object, *args, sort_dicts=False, **kwargs)
39-
40-
Prints the formatted representation of *object* followed by a newline.
41-
If *sort_dicts* is false (the default), dictionaries will be displayed with
42-
their keys in insertion order, otherwise the dict keys will be sorted.
43-
*args* and *kwargs* will be passed to :func:`~pprint.pprint` as formatting
44-
parameters.
45-
46-
>>> import pprint
47-
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
48-
>>> stuff.insert(0, stuff)
49-
>>> pprint.pp(stuff)
50-
[<Recursion on list with id=...>,
51-
'spam',
52-
'eggs',
53-
'lumberjack',
54-
'knights',
55-
'ni']
38+
.. function:: pp(object, stream=None, indent=1, width=80, depth=None, *, \
39+
compact=False, sort_dicts=False, underscore_numbers=False)
40+
41+
Prints the formatted representation of *object*, followed by a newline.
42+
This function may be used in the interactive interpreter
43+
instead of the :func:`print` function for inspecting values.
44+
Tip: you can reassign ``print = pprint.pp`` for use within a scope.
45+
46+
:param object:
47+
The object to be printed.
48+
49+
:param stream:
50+
A file-like object to which the output will be written
51+
by calling its :meth:`!write` method.
52+
If ``None`` (the default), :data:`sys.stdout` is used.
53+
:type stream: :term:`file-like object` | None
54+
55+
:param int indent:
56+
The amount of indentation added for each nesting level.
57+
58+
:param int width:
59+
The desired maximum number of characters per line in the output.
60+
If a structure cannot be formatted within the width constraint,
61+
a best effort will be made.
62+
63+
:param depth:
64+
The number of nesting levels which may be printed.
65+
If the data structure being printed is too deep,
66+
the next contained level is replaced by ``...``.
67+
If ``None`` (the default), there is no constraint
68+
on the depth of the objects being formatted.
69+
:type depth: int | None
70+
71+
:param bool compact:
72+
Control the way long :term:`sequences <sequence>` are formatted.
73+
If ``False`` (the default),
74+
each item of a sequence will be formatted on a separate line,
75+
otherwise as many items as will fit within the *width*
76+
will be formatted on each output line.
77+
78+
:param bool sort_dicts:
79+
If ``True``, dictionaries will be formatted with
80+
their keys sorted, otherwise
81+
they will be displayed in insertion order (the default).
82+
83+
:param bool underscore_numbers:
84+
If ``True``,
85+
integers will be formatted with the ``_`` character for a thousands separator,
86+
otherwise underscores are not displayed (the default).
87+
88+
>>> import pprint
89+
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
90+
>>> stuff.insert(0, stuff)
91+
>>> pprint.pp(stuff)
92+
[<Recursion on list with id=...>,
93+
'spam',
94+
'eggs',
95+
'lumberjack',
96+
'knights',
97+
'ni']
5698

5799
.. versionadded:: 3.8
58100

59101

60102
.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
61103
compact=False, sort_dicts=True, underscore_numbers=False)
62104

63-
Prints the formatted representation of *object* on *stream*, followed by a
64-
newline. If *stream* is ``None``, :data:`sys.stdout` is used. This may be used
65-
in the interactive interpreter instead of the :func:`print` function for
66-
inspecting values (you can even reassign ``print = pprint.pprint`` for use
67-
within a scope).
68-
69-
The configuration parameters *stream*, *indent*, *width*, *depth*,
70-
*compact*, *sort_dicts* and *underscore_numbers* are passed to the
71-
:class:`PrettyPrinter` constructor and their meanings are as
72-
described in its documentation below.
105+
Alias for :func:`~pprint.pp` with *sort_dicts* set to ``True`` by default,
106+
which would automatically sort the dictionaries' keys,
107+
you might want to use :func:`~pprint.pp` instead where it is ``False`` by default.
73108

74-
Note that *sort_dicts* is ``True`` by default and you might want to use
75-
:func:`~pprint.pp` instead where it is ``False`` by default.
76109

77110
.. function:: pformat(object, indent=1, width=80, depth=None, *, \
78111
compact=False, sort_dicts=True, underscore_numbers=False)
79112

80113
Return the formatted representation of *object* as a string. *indent*,
81114
*width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
82115
passed to the :class:`PrettyPrinter` constructor as formatting parameters
83-
and their meanings are as described in its documentation below.
116+
and their meanings are as described in the documentation above.
84117

85118

86119
.. function:: isreadable(object)
@@ -119,51 +152,39 @@ Functions
119152
PrettyPrinter Objects
120153
---------------------
121154

122-
This module defines one class:
123-
124-
.. First the implementation class:
125-
126-
127155
.. index:: single: ...; placeholder
128156

129157
.. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \
130158
compact=False, sort_dicts=True, underscore_numbers=False)
131159

132-
Construct a :class:`PrettyPrinter` instance. This constructor understands
133-
several keyword parameters.
134-
135-
*stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to
136-
which the output will be written by calling its :meth:`!write` method.
137-
If both *stream* and :data:`!sys.stdout` are ``None``, then
138-
:meth:`~PrettyPrinter.pprint` silently returns.
160+
Construct a :class:`PrettyPrinter` instance.
139161

140-
Other values configure the manner in which nesting of complex data
141-
structures is displayed.
162+
Arguments have the same meaning as for :func:`~pprint.pp`.
163+
Note that they are in a different order, and that *sort_dicts* defaults to ``True``.
142164

143-
*indent* (default 1) specifies the amount of indentation added for
144-
each nesting level.
145-
146-
*depth* controls the number of nesting levels which may be printed; if
147-
the data structure being printed is too deep, the next contained level
148-
is replaced by ``...``. By default, there is no constraint on the
149-
depth of the objects being formatted.
150-
151-
*width* (default 80) specifies the desired maximum number of characters per
152-
line in the output. If a structure cannot be formatted within the width
153-
constraint, a best effort will be made.
154-
155-
*compact* impacts the way that long sequences (lists, tuples, sets, etc)
156-
are formatted. If *compact* is false (the default) then each item of a
157-
sequence will be formatted on a separate line. If *compact* is true, as
158-
many items as will fit within the *width* will be formatted on each output
159-
line.
160-
161-
If *sort_dicts* is true (the default), dictionaries will be formatted with
162-
their keys sorted, otherwise they will display in insertion order.
165+
>>> import pprint
166+
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
167+
>>> stuff.insert(0, stuff[:])
168+
>>> pp = pprint.PrettyPrinter(indent=4)
169+
>>> pp.pprint(stuff)
170+
[ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
171+
'spam',
172+
'eggs',
173+
'lumberjack',
174+
'knights',
175+
'ni']
176+
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
177+
>>> pp.pprint(stuff)
178+
[['spam', 'eggs', 'lumberjack',
179+
'knights', 'ni'],
180+
'spam', 'eggs', 'lumberjack', 'knights',
181+
'ni']
182+
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
183+
... ('parrot', ('fresh fruit',))))))))
184+
>>> pp = pprint.PrettyPrinter(depth=6)
185+
>>> pp.pprint(tup)
186+
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
163187

164-
If *underscore_numbers* is true, integers will be formatted with the
165-
``_`` character for a thousands separator, otherwise underscores are not
166-
displayed (the default).
167188

168189
.. versionchanged:: 3.4
169190
Added the *compact* parameter.
@@ -177,29 +198,6 @@ This module defines one class:
177198
.. versionchanged:: 3.11
178199
No longer attempts to write to :data:`!sys.stdout` if it is ``None``.
179200

180-
>>> import pprint
181-
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
182-
>>> stuff.insert(0, stuff[:])
183-
>>> pp = pprint.PrettyPrinter(indent=4)
184-
>>> pp.pprint(stuff)
185-
[ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
186-
'spam',
187-
'eggs',
188-
'lumberjack',
189-
'knights',
190-
'ni']
191-
>>> pp = pprint.PrettyPrinter(width=41, compact=True)
192-
>>> pp.pprint(stuff)
193-
[['spam', 'eggs', 'lumberjack',
194-
'knights', 'ni'],
195-
'spam', 'eggs', 'lumberjack', 'knights',
196-
'ni']
197-
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
198-
... ('parrot', ('fresh fruit',))))))))
199-
>>> pp = pprint.PrettyPrinter(depth=6)
200-
>>> pp.pprint(tup)
201-
('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
202-
203201

204202
:class:`PrettyPrinter` instances have the following methods:
205203

0 commit comments

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