Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :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 | |
Raymond Hettinger | 1048094 | 2011-01-10 03:26:08 +0000 | [diff] [blame] | 9 | **Source code:** :source:`Lib/pprint.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
Raymond Hettinger | 4f707fd | 2011-01-10 19:54:11 +0000 | [diff] [blame] | 11 | -------------- |
| 12 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | The :mod:`pprint` module provides a capability to "pretty-print" arbitrary |
| 14 | Python data structures in a form which can be used as input to the interpreter. |
| 15 | If the formatted structures include objects which are not fundamental Python |
| 16 | types, the representation may not be loadable. This may be the case if objects |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 17 | such as files, sockets or classes are included, as well as many other |
| 18 | objects which are not representable as Python literals. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 19 | |
| 20 | The formatted representation keeps objects on a single line if it can, and |
| 21 | breaks them onto multiple lines if they don't fit within the allowed width. |
| 22 | Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the |
| 23 | width constraint. |
| 24 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 25 | Dictionaries are sorted by key before the display is computed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
| 27 | The :mod:`pprint` module defines one class: |
| 28 | |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 29 | .. First the implementation class: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 30 | |
| 31 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 32 | .. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | |
| 34 | Construct a :class:`PrettyPrinter` instance. This constructor understands |
| 35 | several keyword parameters. An output stream may be set using the *stream* |
| 36 | keyword; the only method used on the stream object is the file protocol's |
| 37 | :meth:`write` method. If not specified, the :class:`PrettyPrinter` adopts |
| 38 | ``sys.stdout``. Three additional parameters may be used to control the |
| 39 | formatted representation. The keywords are *indent*, *depth*, and *width*. The |
| 40 | amount of indentation added for each recursive level is specified by *indent*; |
| 41 | the default is one. Other values can cause output to look a little odd, but can |
| 42 | make nesting easier to spot. The number of levels which may be printed is |
| 43 | controlled by *depth*; if the data structure being printed is too deep, the next |
| 44 | contained level is replaced by ``...``. By default, there is no constraint on |
| 45 | the depth of the objects being formatted. The desired output width is |
| 46 | constrained using the *width* parameter; the default is 80 characters. If a |
| 47 | structure cannot be formatted within the constrained width, a best effort will |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 48 | be made. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 49 | |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 50 | >>> import pprint |
| 51 | >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 52 | >>> stuff.insert(0, stuff[:]) |
| 53 | >>> pp = pprint.PrettyPrinter(indent=4) |
| 54 | >>> pp.pprint(stuff) |
Georg Brandl | 3ccb787 | 2008-07-16 03:00:45 +0000 | [diff] [blame] | 55 | [ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'], |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 56 | 'spam', |
| 57 | 'eggs', |
| 58 | 'lumberjack', |
| 59 | 'knights', |
| 60 | 'ni'] |
| 61 | >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', |
| 62 | ... ('parrot', ('fresh fruit',)))))))) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | >>> pp = pprint.PrettyPrinter(depth=6) |
| 64 | >>> pp.pprint(tup) |
Alexandre Vassalotti | eca20b6 | 2008-05-16 02:54:33 +0000 | [diff] [blame] | 65 | ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...))))))) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 66 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 67 | |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 68 | The :mod:`pprint` module also provides several shortcut functions: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 70 | .. function:: pformat(object, indent=1, width=80, depth=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
| 72 | Return the formatted representation of *object* as a string. *indent*, *width* |
| 73 | and *depth* will be passed to the :class:`PrettyPrinter` constructor as |
| 74 | formatting parameters. |
| 75 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 76 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 77 | .. function:: pprint(object, stream=None, indent=1, width=80, depth=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 78 | |
| 79 | Prints the formatted representation of *object* on *stream*, followed by a |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 80 | newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 81 | in the interactive interpreter instead of the :func:`print` function for |
| 82 | inspecting values (you can even reassign ``print = pprint.pprint`` for use |
| 83 | within a scope). *indent*, *width* and *depth* will be passed to the |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 84 | :class:`PrettyPrinter` constructor as formatting parameters. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 86 | >>> import pprint |
| 87 | >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | >>> stuff.insert(0, stuff) |
| 89 | >>> pprint.pprint(stuff) |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 90 | [<Recursion on list with id=...>, |
| 91 | 'spam', |
| 92 | 'eggs', |
| 93 | 'lumberjack', |
| 94 | 'knights', |
| 95 | 'ni'] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 97 | |
| 98 | .. function:: isreadable(object) |
| 99 | |
| 100 | .. index:: builtin: eval |
| 101 | |
| 102 | Determine if the formatted representation of *object* is "readable," or can be |
| 103 | used to reconstruct the value using :func:`eval`. This always returns ``False`` |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 104 | for recursive objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
| 106 | >>> pprint.isreadable(stuff) |
| 107 | False |
| 108 | |
| 109 | |
| 110 | .. function:: isrecursive(object) |
| 111 | |
| 112 | Determine if *object* requires a recursive representation. |
| 113 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 115 | One more support function is also defined: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | |
| 117 | .. function:: saferepr(object) |
| 118 | |
| 119 | Return a string representation of *object*, protected against recursive data |
| 120 | structures. If the representation of *object* exposes a recursive entry, the |
| 121 | recursive reference will be represented as ``<Recursion on typename with |
| 122 | id=number>``. The representation is not otherwise formatted. |
| 123 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | >>> pprint.saferepr(stuff) |
Christian Heimes | fe337bf | 2008-03-23 21:54:12 +0000 | [diff] [blame] | 125 | "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 126 | |
| 127 | |
| 128 | .. _prettyprinter-objects: |
| 129 | |
| 130 | PrettyPrinter Objects |
| 131 | --------------------- |
| 132 | |
| 133 | :class:`PrettyPrinter` instances have the following methods: |
| 134 | |
| 135 | |
| 136 | .. method:: PrettyPrinter.pformat(object) |
| 137 | |
| 138 | Return the formatted representation of *object*. This takes into account the |
| 139 | options passed to the :class:`PrettyPrinter` constructor. |
| 140 | |
| 141 | |
| 142 | .. method:: PrettyPrinter.pprint(object) |
| 143 | |
| 144 | Print the formatted representation of *object* on the configured stream, |
| 145 | followed by a newline. |
| 146 | |
| 147 | The following methods provide the implementations for the corresponding |
| 148 | functions of the same names. Using these methods on an instance is slightly |
| 149 | more efficient since new :class:`PrettyPrinter` objects don't need to be |
| 150 | created. |
| 151 | |
| 152 | |
| 153 | .. method:: PrettyPrinter.isreadable(object) |
| 154 | |
| 155 | .. index:: builtin: eval |
| 156 | |
| 157 | Determine if the formatted representation of the object is "readable," or can be |
| 158 | used to reconstruct the value using :func:`eval`. Note that this returns |
| 159 | ``False`` for recursive objects. If the *depth* parameter of the |
| 160 | :class:`PrettyPrinter` is set and the object is deeper than allowed, this |
| 161 | returns ``False``. |
| 162 | |
| 163 | |
| 164 | .. method:: PrettyPrinter.isrecursive(object) |
| 165 | |
| 166 | Determine if the object requires a recursive representation. |
| 167 | |
| 168 | This method is provided as a hook to allow subclasses to modify the way objects |
| 169 | are converted to strings. The default implementation uses the internals of the |
| 170 | :func:`saferepr` implementation. |
| 171 | |
| 172 | |
| 173 | .. method:: PrettyPrinter.format(object, context, maxlevels, level) |
| 174 | |
| 175 | Returns three values: the formatted version of *object* as a string, a flag |
| 176 | indicating whether the result is readable, and a flag indicating whether |
| 177 | recursion was detected. The first argument is the object to be presented. The |
| 178 | second is a dictionary which contains the :func:`id` of objects that are part of |
| 179 | the current presentation context (direct and indirect containers for *object* |
| 180 | that are affecting the presentation) as the keys; if an object needs to be |
| 181 | presented which is already represented in *context*, the third return value |
| 182 | should be ``True``. Recursive calls to the :meth:`format` method should add |
| 183 | additional entries for containers to this dictionary. The third argument, |
| 184 | *maxlevels*, gives the requested limit to recursion; this will be ``0`` if there |
| 185 | is no requested limit. This argument should be passed unmodified to recursive |
| 186 | calls. The fourth argument, *level*, gives the current level; recursive calls |
| 187 | should be passed a value less than that of the current call. |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 188 | |
| 189 | |
| 190 | .. _pprint-example: |
| 191 | |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 192 | Example |
| 193 | ------- |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 194 | |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 195 | To demonstrate several uses of the :func:`pprint` function and its parameters, |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 196 | let's fetch information about a project from `PyPI <https://pypi.python.org>`_:: |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 197 | |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 198 | >>> import json |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 199 | >>> import pprint |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 200 | >>> from urllib.request import urlopen |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 201 | >>> with urlopen('http://pypi.python.org/pypi/Twisted/json') as url: |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 202 | ... http_info = url.info() |
| 203 | ... raw_data = url.read().decode(http_info.get_content_charset()) |
Éric Araujo | 6a21f55 | 2011-05-29 03:46:31 +0200 | [diff] [blame] | 204 | >>> project_info = json.loads(raw_data) |
Christian Heimes | b9eccbf | 2007-12-05 20:18:38 +0000 | [diff] [blame] | 205 | |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 206 | In its basic form, :func:`pprint` shows the whole object:: |
| 207 | |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 208 | >>> pprint.pprint(project_info) |
| 209 | {'info': {'_pypi_hidden': False, |
| 210 | '_pypi_ordering': 125, |
| 211 | 'author': 'Glyph Lefkowitz', |
| 212 | 'author_email': 'glyph@twistedmatrix.com', |
| 213 | 'bugtrack_url': '', |
| 214 | 'cheesecake_code_kwalitee_id': None, |
| 215 | 'cheesecake_documentation_id': None, |
| 216 | 'cheesecake_installability_id': None, |
| 217 | 'classifiers': ['Programming Language :: Python :: 2.6', |
| 218 | 'Programming Language :: Python :: 2.7', |
| 219 | 'Programming Language :: Python :: 2 :: Only'], |
| 220 | 'description': 'An extensible framework for Python programming, ' |
| 221 | 'with special focus\r\n' |
| 222 | 'on event-based network programming and ' |
| 223 | 'multiprotocol integration.', |
| 224 | 'docs_url': '', |
| 225 | 'download_url': 'UNKNOWN', |
| 226 | 'home_page': 'http://twistedmatrix.com/', |
| 227 | 'keywords': '', |
| 228 | 'license': 'MIT', |
| 229 | 'maintainer': '', |
| 230 | 'maintainer_email': '', |
| 231 | 'name': 'Twisted', |
| 232 | 'package_url': 'http://pypi.python.org/pypi/Twisted', |
| 233 | 'platform': 'UNKNOWN', |
| 234 | 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', |
| 235 | 'requires_python': None, |
| 236 | 'stable_version': None, |
| 237 | 'summary': 'An asynchronous networking framework written in Python', |
| 238 | 'version': '12.3.0'}, |
| 239 | 'urls': [{'comment_text': '', |
| 240 | 'downloads': 71844, |
| 241 | 'filename': 'Twisted-12.3.0.tar.bz2', |
| 242 | 'has_sig': False, |
| 243 | 'md5_digest': '6e289825f3bf5591cfd670874cc0862d', |
| 244 | 'packagetype': 'sdist', |
| 245 | 'python_version': 'source', |
| 246 | 'size': 2615733, |
| 247 | 'upload_time': '2012-12-26T12:47:03', |
| 248 | 'url': 'https://pypi.python.org/packages/source/T/Twisted/Twisted-12.3.0.tar.bz2'}, |
| 249 | {'comment_text': '', |
| 250 | 'downloads': 5224, |
| 251 | 'filename': 'Twisted-12.3.0.win32-py2.7.msi', |
| 252 | 'has_sig': False, |
| 253 | 'md5_digest': '6b778f5201b622a5519a2aca1a2fe512', |
| 254 | 'packagetype': 'bdist_msi', |
| 255 | 'python_version': '2.7', |
| 256 | 'size': 2916352, |
| 257 | 'upload_time': '2012-12-26T12:48:15', |
| 258 | 'url': 'https://pypi.python.org/packages/2.7/T/Twisted/Twisted-12.3.0.win32-py2.7.msi'}]} |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 259 | |
| 260 | The result can be limited to a certain *depth* (ellipsis is used for deeper |
| 261 | contents):: |
| 262 | |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 263 | >>> pprint.pprint(project_info, depth=2) |
| 264 | {'info': {'_pypi_hidden': False, |
| 265 | '_pypi_ordering': 125, |
| 266 | 'author': 'Glyph Lefkowitz', |
| 267 | 'author_email': 'glyph@twistedmatrix.com', |
| 268 | 'bugtrack_url': '', |
| 269 | 'cheesecake_code_kwalitee_id': None, |
| 270 | 'cheesecake_documentation_id': None, |
| 271 | 'cheesecake_installability_id': None, |
| 272 | 'classifiers': [...], |
| 273 | 'description': 'An extensible framework for Python programming, ' |
| 274 | 'with special focus\r\n' |
| 275 | 'on event-based network programming and ' |
| 276 | 'multiprotocol integration.', |
| 277 | 'docs_url': '', |
| 278 | 'download_url': 'UNKNOWN', |
| 279 | 'home_page': 'http://twistedmatrix.com/', |
| 280 | 'keywords': '', |
| 281 | 'license': 'MIT', |
| 282 | 'maintainer': '', |
| 283 | 'maintainer_email': '', |
| 284 | 'name': 'Twisted', |
| 285 | 'package_url': 'http://pypi.python.org/pypi/Twisted', |
| 286 | 'platform': 'UNKNOWN', |
| 287 | 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', |
| 288 | 'requires_python': None, |
| 289 | 'stable_version': None, |
| 290 | 'summary': 'An asynchronous networking framework written in Python', |
| 291 | 'version': '12.3.0'}, |
| 292 | 'urls': [{...}, {...}]} |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 293 | |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 294 | Additionally, maximum character *width* can be suggested. If a long object |
| 295 | cannot be split, the specified width will be exceeded:: |
Łukasz Langa | 4ad78ab | 2011-05-14 22:43:44 +0200 | [diff] [blame] | 296 | |
Antoine Pitrou | 64c16c3 | 2013-03-23 20:30:39 +0100 | [diff] [blame] | 297 | >>> pprint.pprint(project_info, depth=2, width=50) |
| 298 | {'info': {'_pypi_hidden': False, |
| 299 | '_pypi_ordering': 125, |
| 300 | 'author': 'Glyph Lefkowitz', |
| 301 | 'author_email': 'glyph@twistedmatrix.com', |
| 302 | 'bugtrack_url': '', |
| 303 | 'cheesecake_code_kwalitee_id': None, |
| 304 | 'cheesecake_documentation_id': None, |
| 305 | 'cheesecake_installability_id': None, |
| 306 | 'classifiers': [...], |
| 307 | 'description': 'An extensible ' |
| 308 | 'framework for ' |
| 309 | 'Python programming, ' |
| 310 | 'with special ' |
| 311 | 'focus\r\n' |
| 312 | 'on event-based ' |
| 313 | 'network programming ' |
| 314 | 'and multiprotocol ' |
| 315 | 'integration.', |
| 316 | 'docs_url': '', |
| 317 | 'download_url': 'UNKNOWN', |
| 318 | 'home_page': 'http://twistedmatrix.com/', |
| 319 | 'keywords': '', |
| 320 | 'license': 'MIT', |
| 321 | 'maintainer': '', |
| 322 | 'maintainer_email': '', |
| 323 | 'name': 'Twisted', |
| 324 | 'package_url': 'http://pypi.python.org/pypi/Twisted', |
| 325 | 'platform': 'UNKNOWN', |
| 326 | 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', |
| 327 | 'requires_python': None, |
| 328 | 'stable_version': None, |
| 329 | 'summary': 'An asynchronous ' |
| 330 | 'networking framework ' |
| 331 | 'written in Python', |
| 332 | 'version': '12.3.0'}, |
| 333 | 'urls': [{...}, {...}]} |