pprint.rst 14 KB
Newer Older
1 2 3 4 5
:mod:`pprint` --- Data pretty printer
=====================================

.. module:: pprint
   :synopsis: Data pretty printer.
6

7 8 9
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

10
**Source code:** :source:`Lib/pprint.py`
11

12 13
--------------

14 15 16 17
The :mod:`pprint` module provides a capability to "pretty-print" arbitrary
Python data structures in a form which can be used as input to the interpreter.
If the formatted structures include objects which are not fundamental Python
types, the representation may not be loadable.  This may be the case if objects
18 19
such as files, sockets or classes are included, as well as many other
objects which are not representable as Python literals.
20 21 22 23 24 25

The formatted representation keeps objects on a single line if it can, and
breaks them onto multiple lines if they don't fit within the allowed width.
Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the
width constraint.

26
Dictionaries are sorted by key before the display is computed.
27 28 29

The :mod:`pprint` module defines one class:

30
.. First the implementation class:
31 32


33 34
.. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \
                         compact=False)
35 36 37 38 39

   Construct a :class:`PrettyPrinter` instance.  This constructor understands
   several keyword parameters.  An output stream may be set using the *stream*
   keyword; the only method used on the stream object is the file protocol's
   :meth:`write` method.  If not specified, the :class:`PrettyPrinter` adopts
40
   ``sys.stdout``.  The
41 42 43 44 45 46 47 48
   amount of indentation added for each recursive level is specified by *indent*;
   the default is one.  Other values can cause output to look a little odd, but can
   make nesting easier to spot.  The number of levels which may be printed is
   controlled by *depth*; if the data structure being printed is too deep, the next
   contained level is replaced by ``...``.  By default, there is no constraint on
   the depth of the objects being formatted.  The desired output width is
   constrained using the *width* parameter; the default is 80 characters.  If a
   structure cannot be formatted within the constrained width, a best effort will
49 50 51
   be made.  If *compact* is false (the default) each item of a long sequence
   will be formatted on a separate line.  If *compact* is true, as many items
   as will fit within the *width* will be formatted on each output line.
52

53 54 55
   .. versionchanged:: 3.4
      Added the *compact* parameter.

56 57
      >>> import pprint
      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
58 59 60
      >>> stuff.insert(0, stuff[:])
      >>> pp = pprint.PrettyPrinter(indent=4)
      >>> pp.pprint(stuff)
61
      [   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
62 63 64 65 66
          'spam',
          'eggs',
          'lumberjack',
          'knights',
          'ni']
67 68 69 70 71 72
      >>> pp = pprint.PrettyPrinter(width=41, compact=True)
      >>> pp.pprint(stuff)
      [['spam', 'eggs', 'lumberjack',
        'knights', 'ni'],
       'spam', 'eggs', 'lumberjack', 'knights',
       'ni']
73 74
      >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
      ... ('parrot', ('fresh fruit',))))))))
75 76
      >>> pp = pprint.PrettyPrinter(depth=6)
      >>> pp.pprint(tup)
77
      ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))
78 79


80
The :mod:`pprint` module also provides several shortcut functions:
81

82
.. function:: pformat(object, indent=1, width=80, depth=None, *, compact=False)
83

84 85 86
   Return the formatted representation of *object* as a string.  *indent*,
   *width*, *depth* and *compact* will be passed to the :class:`PrettyPrinter`
   constructor as formatting parameters.
87

88 89 90
   .. versionchanged:: 3.4
      Added the *compact* parameter.

91

92 93
.. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \
                     compact=False)
94 95

   Prints the formatted representation of *object* on *stream*, followed by a
96
   newline.  If *stream* is ``None``, ``sys.stdout`` is used.  This may be used
97 98
   in the interactive interpreter instead of the :func:`print` function for
   inspecting values (you can even reassign ``print = pprint.pprint`` for use
99 100
   within a scope).  *indent*, *width*, *depth* and *compact* will be passed
   to the :class:`PrettyPrinter` constructor as formatting parameters.
101

102 103 104
   .. versionchanged:: 3.4
      Added the *compact* parameter.

105 106
      >>> import pprint
      >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
107 108
      >>> stuff.insert(0, stuff)
      >>> pprint.pprint(stuff)
Christian Heimes's avatar
Christian Heimes committed
109 110 111 112 113 114
      [<Recursion on list with id=...>,
       'spam',
       'eggs',
       'lumberjack',
       'knights',
       'ni']
115 116 117 118 119 120 121 122


.. function:: isreadable(object)

   .. index:: builtin: eval

   Determine if the formatted representation of *object* is "readable," or can be
   used to reconstruct the value using :func:`eval`.  This always returns ``False``
Christian Heimes's avatar
Christian Heimes committed
123
   for recursive objects.
124 125 126 127 128 129 130 131 132 133

      >>> pprint.isreadable(stuff)
      False


.. function:: isrecursive(object)

   Determine if *object* requires a recursive representation.


Christian Heimes's avatar
Christian Heimes committed
134
One more support function is also defined:
135 136 137 138 139 140 141 142 143

.. function:: saferepr(object)

   Return a string representation of *object*, protected against recursive data
   structures.  If the representation of *object* exposes a recursive entry, the
   recursive reference will be represented as ``<Recursion on typename with
   id=number>``.  The representation is not otherwise formatted.

   >>> pprint.saferepr(stuff)
Christian Heimes's avatar
Christian Heimes committed
144
   "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200


.. _prettyprinter-objects:

PrettyPrinter Objects
---------------------

:class:`PrettyPrinter` instances have the following methods:


.. method:: PrettyPrinter.pformat(object)

   Return the formatted representation of *object*.  This takes into account the
   options passed to the :class:`PrettyPrinter` constructor.


.. method:: PrettyPrinter.pprint(object)

   Print the formatted representation of *object* on the configured stream,
   followed by a newline.

The following methods provide the implementations for the corresponding
functions of the same names.  Using these methods on an instance is slightly
more efficient since new :class:`PrettyPrinter` objects don't need to be
created.


.. method:: PrettyPrinter.isreadable(object)

   .. index:: builtin: eval

   Determine if the formatted representation of the object is "readable," or can be
   used to reconstruct the value using :func:`eval`.  Note that this returns
   ``False`` for recursive objects.  If the *depth* parameter of the
   :class:`PrettyPrinter` is set and the object is deeper than allowed, this
   returns ``False``.


.. method:: PrettyPrinter.isrecursive(object)

   Determine if the object requires a recursive representation.

This method is provided as a hook to allow subclasses to modify the way objects
are converted to strings.  The default implementation uses the internals of the
:func:`saferepr` implementation.


.. method:: PrettyPrinter.format(object, context, maxlevels, level)

   Returns three values: the formatted version of *object* as a string, a flag
   indicating whether the result is readable, and a flag indicating whether
   recursion was detected.  The first argument is the object to be presented.  The
   second is a dictionary which contains the :func:`id` of objects that are part of
   the current presentation context (direct and indirect containers for *object*
   that are affecting the presentation) as the keys; if an object needs to be
   presented which is already represented in *context*, the third return value
201
   should be ``True``.  Recursive calls to the :meth:`.format` method should add
202 203 204 205 206
   additional entries for containers to this dictionary.  The third argument,
   *maxlevels*, gives the requested limit to recursion; this will be ``0`` if there
   is no requested limit.  This argument should be passed unmodified to recursive
   calls. The fourth argument, *level*, gives the current level; recursive calls
   should be passed a value less than that of the current call.
207 208 209 210


.. _pprint-example:

211 212
Example
-------
213

214
To demonstrate several uses of the :func:`pprint` function and its parameters,
215
let's fetch information about a project from `PyPI <https://pypi.python.org/pypi>`_::
216

217
   >>> import json
218
   >>> import pprint
219
   >>> from urllib.request import urlopen
220
   >>> with urlopen('http://pypi.python.org/pypi/Twisted/json') as url:
221 222
   ...     http_info = url.info()
   ...     raw_data = url.read().decode(http_info.get_content_charset())
223
   >>> project_info = json.loads(raw_data)
224 225 226

In its basic form, :func:`pprint` shows the whole object::

227 228 229 230 231 232 233 234 235 236 237 238
   >>> pprint.pprint(project_info)
   {'info': {'_pypi_hidden': False,
             '_pypi_ordering': 125,
             'author': 'Glyph Lefkowitz',
             'author_email': 'glyph@twistedmatrix.com',
             'bugtrack_url': '',
             'cheesecake_code_kwalitee_id': None,
             'cheesecake_documentation_id': None,
             'cheesecake_installability_id': None,
             'classifiers': ['Programming Language :: Python :: 2.6',
                             'Programming Language :: Python :: 2.7',
                             'Programming Language :: Python :: 2 :: Only'],
239 240 241 242
             'description': 'An extensible framework for Python programming, with '
                            'special focus\r\n'
                            'on event-based network programming and multiprotocol '
                            'integration.',
243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277
             'docs_url': '',
             'download_url': 'UNKNOWN',
             'home_page': 'http://twistedmatrix.com/',
             'keywords': '',
             'license': 'MIT',
             'maintainer': '',
             'maintainer_email': '',
             'name': 'Twisted',
             'package_url': 'http://pypi.python.org/pypi/Twisted',
             'platform': 'UNKNOWN',
             'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0',
             'requires_python': None,
             'stable_version': None,
             'summary': 'An asynchronous networking framework written in Python',
             'version': '12.3.0'},
    'urls': [{'comment_text': '',
              'downloads': 71844,
              'filename': 'Twisted-12.3.0.tar.bz2',
              'has_sig': False,
              'md5_digest': '6e289825f3bf5591cfd670874cc0862d',
              'packagetype': 'sdist',
              'python_version': 'source',
              'size': 2615733,
              'upload_time': '2012-12-26T12:47:03',
              'url': 'https://pypi.python.org/packages/source/T/Twisted/Twisted-12.3.0.tar.bz2'},
             {'comment_text': '',
              'downloads': 5224,
              'filename': 'Twisted-12.3.0.win32-py2.7.msi',
              'has_sig': False,
              'md5_digest': '6b778f5201b622a5519a2aca1a2fe512',
              'packagetype': 'bdist_msi',
              'python_version': '2.7',
              'size': 2916352,
              'upload_time': '2012-12-26T12:48:15',
              'url': 'https://pypi.python.org/packages/2.7/T/Twisted/Twisted-12.3.0.win32-py2.7.msi'}]}
278 279 280 281

The result can be limited to a certain *depth* (ellipsis is used for deeper
contents)::

282 283 284 285 286 287 288 289 290 291
   >>> pprint.pprint(project_info, depth=2)
   {'info': {'_pypi_hidden': False,
             '_pypi_ordering': 125,
             'author': 'Glyph Lefkowitz',
             'author_email': 'glyph@twistedmatrix.com',
             'bugtrack_url': '',
             'cheesecake_code_kwalitee_id': None,
             'cheesecake_documentation_id': None,
             'cheesecake_installability_id': None,
             'classifiers': [...],
292 293 294 295
             'description': 'An extensible framework for Python programming, with '
                            'special focus\r\n'
                            'on event-based network programming and multiprotocol '
                            'integration.',
296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
             'docs_url': '',
             'download_url': 'UNKNOWN',
             'home_page': 'http://twistedmatrix.com/',
             'keywords': '',
             'license': 'MIT',
             'maintainer': '',
             'maintainer_email': '',
             'name': 'Twisted',
             'package_url': 'http://pypi.python.org/pypi/Twisted',
             'platform': 'UNKNOWN',
             'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0',
             'requires_python': None,
             'stable_version': None,
             'summary': 'An asynchronous networking framework written in Python',
             'version': '12.3.0'},
    'urls': [{...}, {...}]}

Additionally, maximum character *width* can be suggested. If a long object
cannot be split, the specified width will be exceeded::

   >>> pprint.pprint(project_info, depth=2, width=50)
   {'info': {'_pypi_hidden': False,
             '_pypi_ordering': 125,
             'author': 'Glyph Lefkowitz',
             'author_email': 'glyph@twistedmatrix.com',
             'bugtrack_url': '',
             'cheesecake_code_kwalitee_id': None,
             'cheesecake_documentation_id': None,
             'cheesecake_installability_id': None,
             'classifiers': [...],
             'description': 'An extensible '
327 328 329 330 331 332
                            'framework for Python '
                            'programming, with '
                            'special focus\r\n'
                            'on event-based network '
                            'programming and '
                            'multiprotocol '
333 334 335 336 337 338 339 340 341 342 343 344 345 346
                            'integration.',
             'docs_url': '',
             'download_url': 'UNKNOWN',
             'home_page': 'http://twistedmatrix.com/',
             'keywords': '',
             'license': 'MIT',
             'maintainer': '',
             'maintainer_email': '',
             'name': 'Twisted',
             'package_url': 'http://pypi.python.org/pypi/Twisted',
             'platform': 'UNKNOWN',
             'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0',
             'requires_python': None,
             'stable_version': None,
347 348 349
             'summary': 'An asynchronous networking '
                        'framework written in '
                        'Python',
350 351
             'version': '12.3.0'},
    'urls': [{...}, {...}]}