PageRenderTime 345ms CodeModel.GetById 151ms app.highlight 8ms RepoModel.GetById 183ms app.codeStats 0ms

/Doc/library/pprint.rst

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