Skip to content

Commit cc92c08

Browse files
committed
Move pprinter parameters description to the table
The change improves readability. Suggested in the GH#116085 PR discussion.
1 parent bfc57d4 commit cc92c08

File tree

1 file changed

+42
-40
lines changed

1 file changed

+42
-40
lines changed

Doc/library/pprint.rst

Lines changed: 42 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -70,18 +70,57 @@ Functions
7070
The configuration parameters *stream*, *indent*, *width*, *depth*,
7171
*compact*, *sort_dicts* and *underscore_numbers* are passed to the
7272
:class:`PrettyPrinter` constructor and their meanings are as
73-
described in its documentation below.
73+
described in the documentation below.
7474

7575
Note that *sort_dicts* is ``True`` by default and you might want to use
7676
:func:`~pprint.pp` instead where it is ``False`` by default.
7777

78+
.. _prettyprinter-parameters:
79+
80+
.. list-table:: **Recognised parameters for PrettyPrinter**
81+
:header-rows: 1
82+
:widths: 20 80
83+
84+
* - Parameter
85+
- Description
86+
* - ``indent``: ``int``
87+
- The amount of indentation added for each nesting level.
88+
* - ``width``: ``int``
89+
- The desired maximum number of characters per line in the output.
90+
If a structure cannot be formatted within the width constraint,
91+
a best effort will be made.
92+
* - ``depth``: ``int`` | ``None``
93+
- The number of nesting levels which may be printed.
94+
If the data structure being printed is too deep,
95+
the next contained level is replaced by ``...``.
96+
If ``None`` (the default), there is no constraint
97+
on the depth of the objects being formatted.
98+
* - ``stream``: :term:`file-like object` | ``None``
99+
- A file-like object to which the output will be written
100+
by calling its :meth:`!write` method.
101+
If ``None`` (the default), :data:`sys.stdout` is used.
102+
* - ``compact``: ``bool``
103+
- Control the way long :term:`sequences <sequence>` are formatted.
104+
If ``False`` (the default),
105+
each item of a sequence will be formatted on a separate line,
106+
otherwise as many items as will fit within the *width*
107+
will be formatted on each output line.
108+
* - ``sort_dicts``: ``bool``
109+
- If ``True`` (the default), dictionaries will be formatted with
110+
their keys sorted, otherwise they will display in insertion order.
111+
* - ``underscore_numbers``: ``bool``
112+
- If ``True``,
113+
integers will be formatted with the ``_`` character for a thousands separator,
114+
otherwise underscores are not displayed (the default).
115+
116+
78117
.. function:: pformat(object, indent=1, width=80, depth=None, *, \
79118
compact=False, sort_dicts=True, underscore_numbers=False)
80119

81120
Return the formatted representation of *object* as a string. *indent*,
82121
*width*, *depth*, *compact*, *sort_dicts* and *underscore_numbers* are
83122
passed to the :class:`PrettyPrinter` constructor as formatting parameters
84-
and their meanings are as described in its documentation below.
123+
and their meanings are as described in the documentation above.
85124

86125

87126
.. function:: isreadable(object)
@@ -120,51 +159,14 @@ Functions
120159
PrettyPrinter Objects
121160
---------------------
122161

123-
This module defines one class:
124-
125-
.. First the implementation class:
126-
127-
128162
.. index:: single: ...; placeholder
129163

130164
.. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \
131165
compact=False, sort_dicts=True, underscore_numbers=False)
132166

133167
Construct a :class:`PrettyPrinter` instance. This constructor understands
134168
several keyword parameters.
135-
136-
*stream* (default :data:`!sys.stdout`) is a :term:`file-like object` to
137-
which the output will be written by calling its :meth:`!write` method.
138-
If both *stream* and :data:`!sys.stdout` are ``None``, then
139-
:meth:`~PrettyPrinter.pprint` silently returns.
140-
141-
Other values configure the manner in which nesting of complex data
142-
structures is displayed.
143-
144-
*indent* (default 1) specifies the amount of indentation added for
145-
each nesting level.
146-
147-
*depth* controls the number of nesting levels which may be printed; if
148-
the data structure being printed is too deep, the next contained level
149-
is replaced by ``...``. By default, there is no constraint on the
150-
depth of the objects being formatted.
151-
152-
*width* (default 80) specifies the desired maximum number of characters per
153-
line in the output. If a structure cannot be formatted within the width
154-
constraint, a best effort will be made.
155-
156-
*compact* impacts the way that long sequences (lists, tuples, sets, etc)
157-
are formatted. If *compact* is false (the default) then each item of a
158-
sequence will be formatted on a separate line. If *compact* is true, as
159-
many items as will fit within the *width* will be formatted on each output
160-
line.
161-
162-
If *sort_dicts* is true (the default), dictionaries will be formatted with
163-
their keys sorted, otherwise they will display in insertion order.
164-
165-
If *underscore_numbers* is true, integers will be formatted with the
166-
``_`` character for a thousands separator, otherwise underscores are not
167-
displayed (the default).
169+
Parameters described at :ref:`parameters table <prettyprinter-parameters>`.
168170

169171
.. versionchanged:: 3.4
170172
Added the *compact* parameter.

0 commit comments

Comments
 (0)