blob: 8e7baf88d8e6358ead45fdd05089a91f057176b2 [file] [log] [blame]
Georg Brandl8ec7f652007-08-15 14:28:01 +00001:mod:`pprint` --- Data pretty printer
2=====================================
3
4.. module:: pprint
5 :synopsis: Data pretty printer.
6.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
8
Éric Araujo29a0b572011-08-19 02:14:03 +02009**Source code:** :source:`Lib/pprint.py`
10
11--------------
Georg Brandl8ec7f652007-08-15 14:28:01 +000012
13The :mod:`pprint` module provides a capability to "pretty-print" arbitrary
14Python data structures in a form which can be used as input to the interpreter.
15If the formatted structures include objects which are not fundamental Python
16types, the representation may not be loadable. This may be the case if objects
17such as files, sockets, classes, or instances are included, as well as many
Georg Brandld7d4fd72009-07-26 14:37:28 +000018other built-in objects which are not representable as Python constants.
Georg Brandl8ec7f652007-08-15 14:28:01 +000019
20The formatted representation keeps objects on a single line if it can, and
21breaks them onto multiple lines if they don't fit within the allowed width.
22Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the
23width constraint.
24
25.. versionchanged:: 2.5
26 Dictionaries are sorted by key before the display is computed; before 2.5, a
27 dictionary was sorted only if its display required more than one line, although
28 that wasn't documented.
29
Raymond Hettingerc226c312008-01-23 00:04:40 +000030.. versionchanged:: 2.6
31 Added support for :class:`set` and :class:`frozenset`.
32
Raymond Hettingere0e08222010-11-06 07:10:31 +000033
Georg Brandl8ec7f652007-08-15 14:28:01 +000034The :mod:`pprint` module defines one class:
35
Georg Brandlb19be572007-12-29 10:57:00 +000036.. First the implementation class:
Georg Brandl8ec7f652007-08-15 14:28:01 +000037
38
Ezio Melotti63b04482012-12-01 19:36:00 +020039.. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None)
Georg Brandl8ec7f652007-08-15 14:28:01 +000040
41 Construct a :class:`PrettyPrinter` instance. This constructor understands
42 several keyword parameters. An output stream may be set using the *stream*
43 keyword; the only method used on the stream object is the file protocol's
44 :meth:`write` method. If not specified, the :class:`PrettyPrinter` adopts
45 ``sys.stdout``. Three additional parameters may be used to control the
46 formatted representation. The keywords are *indent*, *depth*, and *width*. The
47 amount of indentation added for each recursive level is specified by *indent*;
48 the default is one. Other values can cause output to look a little odd, but can
49 make nesting easier to spot. The number of levels which may be printed is
50 controlled by *depth*; if the data structure being printed is too deep, the next
51 contained level is replaced by ``...``. By default, there is no constraint on
52 the depth of the objects being formatted. The desired output width is
53 constrained using the *width* parameter; the default is 80 characters. If a
54 structure cannot be formatted within the constrained width, a best effort will
Georg Brandl473f1642008-03-22 12:59:37 +000055 be made.
Georg Brandl8ec7f652007-08-15 14:28:01 +000056
Georg Brandl722e1012007-12-05 17:56:50 +000057 >>> import pprint
58 >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
Georg Brandl8ec7f652007-08-15 14:28:01 +000059 >>> stuff.insert(0, stuff[:])
60 >>> pp = pprint.PrettyPrinter(indent=4)
61 >>> pp.pprint(stuff)
Facundo Batista2da91c32008-06-21 17:43:56 +000062 [ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
Georg Brandl722e1012007-12-05 17:56:50 +000063 'spam',
64 'eggs',
65 'lumberjack',
66 'knights',
67 'ni']
68 >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
69 ... ('parrot', ('fresh fruit',))))))))
Georg Brandl8ec7f652007-08-15 14:28:01 +000070 >>> pp = pprint.PrettyPrinter(depth=6)
71 >>> pp.pprint(tup)
Georg Brandl23da6e62008-05-12 16:26:52 +000072 ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
Georg Brandl8ec7f652007-08-15 14:28:01 +000073
74The :class:`PrettyPrinter` class supports several derivative functions:
75
Ezio Melotti63b04482012-12-01 19:36:00 +020076.. function:: pformat(object, indent=1, width=80, depth=None)
Georg Brandl8ec7f652007-08-15 14:28:01 +000077
78 Return the formatted representation of *object* as a string. *indent*, *width*
79 and *depth* will be passed to the :class:`PrettyPrinter` constructor as
80 formatting parameters.
81
82 .. versionchanged:: 2.4
83 The parameters *indent*, *width* and *depth* were added.
84
85
Ezio Melotti63b04482012-12-01 19:36:00 +020086.. function:: pprint(object, stream=None, indent=1, width=80, depth=None)
Georg Brandl8ec7f652007-08-15 14:28:01 +000087
88 Prints the formatted representation of *object* on *stream*, followed by a
Ezio Melotti63b04482012-12-01 19:36:00 +020089 newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used in
Georg Brandl8ec7f652007-08-15 14:28:01 +000090 the interactive interpreter instead of a :keyword:`print` statement for
91 inspecting values. *indent*, *width* and *depth* will be passed to the
Georg Brandl473f1642008-03-22 12:59:37 +000092 :class:`PrettyPrinter` constructor as formatting parameters.
Georg Brandl8ec7f652007-08-15 14:28:01 +000093
Georg Brandl722e1012007-12-05 17:56:50 +000094 >>> import pprint
95 >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
Georg Brandl8ec7f652007-08-15 14:28:01 +000096 >>> stuff.insert(0, stuff)
97 >>> pprint.pprint(stuff)
Georg Brandl473f1642008-03-22 12:59:37 +000098 [<Recursion on list with id=...>,
99 'spam',
100 'eggs',
101 'lumberjack',
102 'knights',
103 'ni']
Georg Brandl8ec7f652007-08-15 14:28:01 +0000104
105 .. versionchanged:: 2.4
106 The parameters *indent*, *width* and *depth* were added.
107
108
109.. function:: isreadable(object)
110
111 .. index:: builtin: eval
112
113 Determine if the formatted representation of *object* is "readable," or can be
114 used to reconstruct the value using :func:`eval`. This always returns ``False``
Georg Brandl473f1642008-03-22 12:59:37 +0000115 for recursive objects.
Georg Brandl8ec7f652007-08-15 14:28:01 +0000116
117 >>> pprint.isreadable(stuff)
118 False
119
120
121.. function:: isrecursive(object)
122
123 Determine if *object* requires a recursive representation.
124
Georg Brandl8ec7f652007-08-15 14:28:01 +0000125
Georg Brandl473f1642008-03-22 12:59:37 +0000126One more support function is also defined:
Georg Brandl8ec7f652007-08-15 14:28:01 +0000127
128.. function:: saferepr(object)
129
130 Return a string representation of *object*, protected against recursive data
131 structures. If the representation of *object* exposes a recursive entry, the
132 recursive reference will be represented as ``<Recursion on typename with
133 id=number>``. The representation is not otherwise formatted.
134
Georg Brandl8ec7f652007-08-15 14:28:01 +0000135 >>> pprint.saferepr(stuff)
Georg Brandl473f1642008-03-22 12:59:37 +0000136 "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
Georg Brandl8ec7f652007-08-15 14:28:01 +0000137
138
139.. _prettyprinter-objects:
140
141PrettyPrinter Objects
142---------------------
143
144:class:`PrettyPrinter` instances have the following methods:
145
146
147.. method:: PrettyPrinter.pformat(object)
148
149 Return the formatted representation of *object*. This takes into account the
150 options passed to the :class:`PrettyPrinter` constructor.
151
152
153.. method:: PrettyPrinter.pprint(object)
154
155 Print the formatted representation of *object* on the configured stream,
156 followed by a newline.
157
158The following methods provide the implementations for the corresponding
159functions of the same names. Using these methods on an instance is slightly
160more efficient since new :class:`PrettyPrinter` objects don't need to be
161created.
162
163
164.. method:: PrettyPrinter.isreadable(object)
165
166 .. index:: builtin: eval
167
168 Determine if the formatted representation of the object is "readable," or can be
169 used to reconstruct the value using :func:`eval`. Note that this returns
170 ``False`` for recursive objects. If the *depth* parameter of the
171 :class:`PrettyPrinter` is set and the object is deeper than allowed, this
172 returns ``False``.
173
174
175.. method:: PrettyPrinter.isrecursive(object)
176
177 Determine if the object requires a recursive representation.
178
179This method is provided as a hook to allow subclasses to modify the way objects
180are converted to strings. The default implementation uses the internals of the
181:func:`saferepr` implementation.
182
183
184.. method:: PrettyPrinter.format(object, context, maxlevels, level)
185
186 Returns three values: the formatted version of *object* as a string, a flag
187 indicating whether the result is readable, and a flag indicating whether
188 recursion was detected. The first argument is the object to be presented. The
189 second is a dictionary which contains the :func:`id` of objects that are part of
190 the current presentation context (direct and indirect containers for *object*
191 that are affecting the presentation) as the keys; if an object needs to be
192 presented which is already represented in *context*, the third return value
193 should be ``True``. Recursive calls to the :meth:`format` method should add
194 additional entries for containers to this dictionary. The third argument,
195 *maxlevels*, gives the requested limit to recursion; this will be ``0`` if there
196 is no requested limit. This argument should be passed unmodified to recursive
197 calls. The fourth argument, *level*, gives the current level; recursive calls
198 should be passed a value less than that of the current call.
199
200 .. versionadded:: 2.3
201
Georg Brandl722e1012007-12-05 17:56:50 +0000202.. _pprint-example:
203
204pprint Example
205--------------
206
Ezio Melotti63b04482012-12-01 19:36:00 +0200207This example demonstrates several uses of the :func:`pprint` function and its
208parameters.
Georg Brandl722e1012007-12-05 17:56:50 +0000209
210 >>> import pprint
211 >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
212 ... ('parrot', ('fresh fruit',))))))))
213 >>> stuff = ['a' * 10, tup, ['a' * 30, 'b' * 30], ['c' * 20, 'd' * 20]]
214 >>> pprint.pprint(stuff)
215 ['aaaaaaaaaa',
216 ('spam',
217 ('eggs',
218 ('lumberjack',
219 ('knights', ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
220 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
221 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
222 >>> pprint.pprint(stuff, depth=3)
223 ['aaaaaaaaaa',
Georg Brandl23da6e62008-05-12 16:26:52 +0000224 ('spam', ('eggs', (...))),
Georg Brandl722e1012007-12-05 17:56:50 +0000225 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
226 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
227 >>> pprint.pprint(stuff, width=60)
228 ['aaaaaaaaaa',
229 ('spam',
230 ('eggs',
231 ('lumberjack',
232 ('knights',
233 ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
234 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
235 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
236 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
237