rest25/library/pprint.rst => rest262/library/pprint.rst
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
n28+.. versionchanged:: 2.6
29+   Added support for :class:`set` and :class:`frozenset`.
30+ 
28The :mod:`pprint` module defines one class:
29
n30-.. % First the implementation class:
n33+.. First the implementation class:
31
32
33.. class:: PrettyPrinter(...)
34
35   Construct a :class:`PrettyPrinter` instance.  This constructor understands
36   several keyword parameters.  An output stream may be set using the *stream*
37   keyword; the only method used on the stream object is the file protocol's
38   :meth:`write` method.  If not specified, the :class:`PrettyPrinter` adopts
39   ``sys.stdout``.  Three additional parameters may be used to control the
40   formatted representation.  The keywords are *indent*, *depth*, and *width*.  The
41   amount of indentation added for each recursive level is specified by *indent*;
42   the default is one.  Other values can cause output to look a little odd, but can
43   make nesting easier to spot.  The number of levels which may be printed is
44   controlled by *depth*; if the data structure being printed is too deep, the next
45   contained level is replaced by ``...``.  By default, there is no constraint on
46   the depth of the objects being formatted.  The desired output width is
n47-   constrained using the *width* parameter; the default is eighty characters.  If a
n50+   constrained using the *width* parameter; the default is 80 characters.  If a
48   structure cannot be formatted within the constrained width, a best effort will
n49-   be made. ::
n52+   be made.
50
n51-      >>> import pprint, sys
n54+      >>> import pprint
52-      >>> stuff = sys.path[:]
55+      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
53      >>> stuff.insert(0, stuff[:])
54      >>> pp = pprint.PrettyPrinter(indent=4)
55      >>> pp.pprint(stuff)
n56-      [   [   '',
n59+      [   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
57-              '/usr/local/lib/python1.5',
58-              '/usr/local/lib/python1.5/test',
59-              '/usr/local/lib/python1.5/sunos5',
60-              '/usr/local/lib/python1.5/sharedmodules',
61-              '/usr/local/lib/python1.5/tkinter'],
62-          '',
60+          'spam',
63-          '/usr/local/lib/python1.5',
61+          'eggs',
64-          '/usr/local/lib/python1.5/test',
62+          'lumberjack',
65-          '/usr/local/lib/python1.5/sunos5',
63+          'knights',
66-          '/usr/local/lib/python1.5/sharedmodules',
64+          'ni']
67-          '/usr/local/lib/python1.5/tkinter']
65+      >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
68-      >>>
66+      ... ('parrot', ('fresh fruit',))))))))
69-      >>> import parser
70-      >>> tup = parser.ast2tuple(
71-      ...     parser.suite(open('pprint.py').read()))[1][1][1]
72      >>> pp = pprint.PrettyPrinter(depth=6)
73      >>> pp.pprint(tup)
n74-      (266, (267, (307, (287, (288, (...))))))
n69+      ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
75
76The :class:`PrettyPrinter` class supports several derivative functions:
77
n78-.. % Now the derivative functions:
n73+.. Now the derivative functions:
79- 
80
81.. function:: pformat(object[, indent[, width[, depth]]])
82
83   Return the formatted representation of *object* as a string.  *indent*, *width*
84   and *depth* will be passed to the :class:`PrettyPrinter` constructor as
85   formatting parameters.
86
87   .. versionchanged:: 2.4
89
90
91.. function:: pprint(object[, stream[, indent[, width[, depth]]]])
92
93   Prints the formatted representation of *object* on *stream*, followed by a
94   newline.  If *stream* is omitted, ``sys.stdout`` is used.  This may be used in
95   the interactive interpreter instead of a :keyword:`print` statement for
96   inspecting values.    *indent*, *width* and *depth* will be passed to the
n97-   :class:`PrettyPrinter` constructor as formatting parameters. ::
n91+   :class:`PrettyPrinter` constructor as formatting parameters.
98
n99-      >>> stuff = sys.path[:]
n93+      >>> import pprint
94+      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
100      >>> stuff.insert(0, stuff)
101      >>> pprint.pprint(stuff)
n102-      [<Recursion on list with id=869440>,
n97+      [<Recursion on list with id=...>,
103-       '',
98+       'spam',
104-       '/usr/local/lib/python1.5',
99+       'eggs',
105-       '/usr/local/lib/python1.5/test',
100+       'lumberjack',
106-       '/usr/local/lib/python1.5/sunos5',
101+       'knights',
107-       '/usr/local/lib/python1.5/sharedmodules',
102+       'ni']
108-       '/usr/local/lib/python1.5/tkinter']
109
110   .. versionchanged:: 2.4
111      The parameters *indent*, *width* and *depth* were added.
112
113
114.. function:: isreadable(object)
115
116   .. index:: builtin: eval
117
118   Determine if the formatted representation of *object* is "readable," or can be
n119-   used to reconstruct the value using :func:`eval`.  This always returns false for
n113+   used to reconstruct the value using :func:`eval`.  This always returns ``False``
120-   recursive objects. ::
114+   for recursive objects.
121
122      >>> pprint.isreadable(stuff)
123      False
124
125
126.. function:: isrecursive(object)
127
128   Determine if *object* requires a recursive representation.
129
n124+ 
130One more support function is also defined:
n131- 
132
133.. function:: saferepr(object)
134
135   Return a string representation of *object*, protected against recursive data
136   structures.  If the representation of *object* exposes a recursive entry, the
137   recursive reference will be represented as ``<Recursion on typename with
138   id=number>``.  The representation is not otherwise formatted.
139
n140-.. % This example is outside the {funcdesc} to keep it from running over
141-.. % the right margin.
142- 
143-::
144- 
145   >>> pprint.saferepr(stuff)
n146-   "[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
n135+   "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
147-   l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
148-   1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
149
150
n151-.. _prettyprinter objects:
n138+.. _prettyprinter-objects:
152
153PrettyPrinter Objects
154---------------------
155
156:class:`PrettyPrinter` instances have the following methods:
157
158
n159-.. method:: XXX Class.pformat(object)
n146+.. method:: PrettyPrinter.pformat(object)
160
161   Return the formatted representation of *object*.  This takes into account the
162   options passed to the :class:`PrettyPrinter` constructor.
163
164
n165-.. method:: XXX Class.pprint(object)
n152+.. method:: PrettyPrinter.pprint(object)
166
167   Print the formatted representation of *object* on the configured stream,
168   followed by a newline.
169
170The following methods provide the implementations for the corresponding
171functions of the same names.  Using these methods on an instance is slightly
172more efficient since new :class:`PrettyPrinter` objects don't need to be
173created.
174
175
n176-.. method:: XXX Class.isreadable(object)
n163+.. method:: PrettyPrinter.isreadable(object)
177
178   .. index:: builtin: eval
179
180   Determine if the formatted representation of the object is "readable," or can be
n181-   used to reconstruct the value using :func:`eval`.  Note that this returns false
n168+   used to reconstruct the value using :func:`eval`.  Note that this returns
182-   for recursive objects.  If the *depth* parameter of the :class:`PrettyPrinter`
169+   ``False`` for recursive objects.  If the *depth* parameter of the
183-   is set and the object is deeper than allowed, this returns false.
170+   :class:`PrettyPrinter` is set and the object is deeper than allowed, this
171+   returns ``False``.
184
185
n186-.. method:: XXX Class.isrecursive(object)
n174+.. method:: PrettyPrinter.isrecursive(object)
187
188   Determine if the object requires a recursive representation.
189
190This method is provided as a hook to allow subclasses to modify the way objects
191are converted to strings.  The default implementation uses the internals of the
192:func:`saferepr` implementation.
193
194
n195-.. method:: XXX Class.format(object, context, maxlevels, level)
n183+.. method:: PrettyPrinter.format(object, context, maxlevels, level)
196
197   Returns three values: the formatted version of *object* as a string, a flag
198   indicating whether the result is readable, and a flag indicating whether
199   recursion was detected.  The first argument is the object to be presented.  The
200   second is a dictionary which contains the :func:`id` of objects that are part of
201   the current presentation context (direct and indirect containers for *object*
202   that are affecting the presentation) as the keys; if an object needs to be
203   presented which is already represented in *context*, the third return value
n204-   should be true.  Recursive calls to the :meth:`format` method should add
n192+   should be ``True``.  Recursive calls to the :meth:`format` method should add
205   additional entries for containers to this dictionary.  The third argument,
206   *maxlevels*, gives the requested limit to recursion; this will be ``0`` if there
207   is no requested limit.  This argument should be passed unmodified to recursive
208   calls. The fourth argument, *level*, gives the current level; recursive calls
209   should be passed a value less than that of the current call.
210
211   .. versionadded:: 2.3
212
t201+.. _pprint-example:
202+ 
203+pprint Example
204+--------------
205+ 
206+This 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+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op