Mercurial > cpython-lru_cache-weakref

annotate Doc/library/pprint.rst @ 79675:c0a2294de787 2.7

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