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