| :mod:`pprint` --- Data pretty printer |
| ===================================== |
| |
| .. module:: pprint |
| :synopsis: Data pretty printer. |
| |
| .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| |
| **Source code:** :source:`Lib/pprint.py` |
| |
| -------------- |
| |
| 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 |
| such as files, sockets or classes are included, as well as many other |
| objects which are not representable as Python literals. |
| |
| 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. |
| |
| Dictionaries are sorted by key before the display is computed. |
| |
| The :mod:`pprint` module defines one class: |
| |
| .. First the implementation class: |
| |
| |
| .. index:: single: ...; placeholder |
| |
| .. class:: PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, \ |
| compact=False, sort_dicts=True) |
| |
| 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 |
| ``sys.stdout``. The |
| 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 |
| 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. If |
| *sort_dicts* is true (the default), dictionaries will be formatted with their |
| keys sorted, otherwise they will display in insertion order. |
| |
| .. versionchanged:: 3.4 |
| Added the *compact* parameter. |
| |
| .. versionchanged:: 3.8 |
| Added the *sort_dicts* parameter. |
| |
| |
| >>> import pprint |
| >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] |
| >>> stuff.insert(0, stuff[:]) |
| >>> pp = pprint.PrettyPrinter(indent=4) |
| >>> pp.pprint(stuff) |
| [ ['spam', 'eggs', 'lumberjack', 'knights', 'ni'], |
| 'spam', |
| 'eggs', |
| 'lumberjack', |
| 'knights', |
| 'ni'] |
| >>> pp = pprint.PrettyPrinter(width=41, compact=True) |
| >>> pp.pprint(stuff) |
| [['spam', 'eggs', 'lumberjack', |
| 'knights', 'ni'], |
| 'spam', 'eggs', 'lumberjack', 'knights', |
| 'ni'] |
| >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', |
| ... ('parrot', ('fresh fruit',)))))))) |
| >>> pp = pprint.PrettyPrinter(depth=6) |
| >>> pp.pprint(tup) |
| ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...))))))) |
| |
| |
| The :mod:`pprint` module also provides several shortcut functions: |
| |
| .. function:: pformat(object, indent=1, width=80, depth=None, *, \ |
| compact=False, sort_dicts=True) |
| |
| Return the formatted representation of *object* as a string. *indent*, |
| *width*, *depth*, *compact* and *sort_dicts* will be passed to the |
| :class:`PrettyPrinter` constructor as formatting parameters. |
| |
| .. versionchanged:: 3.4 |
| Added the *compact* parameter. |
| |
| .. versionchanged:: 3.8 |
| Added the *sort_dicts* parameter. |
| |
| |
| .. function:: pp(object, *args, sort_dicts=False, **kwargs) |
| |
| Prints the formatted representation of *object* followed by a newline. |
| If *sort_dicts* is false (the default), dictionaries will be displayed with |
| their keys in insertion order, otherwise the dict keys will be sorted. |
| *args* and *kwargs* will be passed to :func:`pprint` as formatting |
| parameters. |
| |
| .. versionadded:: 3.8 |
| |
| |
| .. function:: pprint(object, stream=None, indent=1, width=80, depth=None, *, \ |
| compact=False, sort_dicts=True) |
| |
| Prints the formatted representation of *object* on *stream*, followed by a |
| newline. If *stream* is ``None``, ``sys.stdout`` is used. This may be used |
| in the interactive interpreter instead of the :func:`print` function for |
| inspecting values (you can even reassign ``print = pprint.pprint`` for use |
| within a scope). *indent*, *width*, *depth*, *compact* and *sort_dicts* will |
| be passed to the :class:`PrettyPrinter` constructor as formatting parameters. |
| |
| .. versionchanged:: 3.4 |
| Added the *compact* parameter. |
| |
| .. versionchanged:: 3.8 |
| Added the *sort_dicts* parameter. |
| |
| >>> import pprint |
| >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni'] |
| >>> stuff.insert(0, stuff) |
| >>> pprint.pprint(stuff) |
| [<Recursion on list with id=...>, |
| 'spam', |
| 'eggs', |
| 'lumberjack', |
| 'knights', |
| 'ni'] |
| |
| |
| .. 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`` |
| for recursive objects. |
| |
| >>> pprint.isreadable(stuff) |
| False |
| |
| |
| .. function:: isrecursive(object) |
| |
| Determine if *object* requires a recursive representation. |
| |
| |
| One more support function is also defined: |
| |
| .. 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) |
| "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']" |
| |
| |
| .. _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 |
| should be ``True``. Recursive calls to the :meth:`.format` method should add |
| 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. |
| |
| |
| .. _pprint-example: |
| |
| Example |
| ------- |
| |
| To demonstrate several uses of the :func:`pprint` function and its parameters, |
| let's fetch information about a project from `PyPI <https://pypi.org>`_:: |
| |
| >>> import json |
| >>> import pprint |
| >>> from urllib.request import urlopen |
| >>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp: |
| ... project_info = json.load(resp)['info'] |
| |
| In its basic form, :func:`pprint` shows the whole object:: |
| |
| >>> pprint.pprint(project_info) |
| {'author': 'The Python Packaging Authority', |
| 'author_email': 'pypa-dev@googlegroups.com', |
| 'bugtrack_url': None, |
| 'classifiers': ['Development Status :: 3 - Alpha', |
| 'Intended Audience :: Developers', |
| 'License :: OSI Approved :: MIT License', |
| 'Programming Language :: Python :: 2', |
| 'Programming Language :: Python :: 2.6', |
| 'Programming Language :: Python :: 2.7', |
| 'Programming Language :: Python :: 3', |
| 'Programming Language :: Python :: 3.2', |
| 'Programming Language :: Python :: 3.3', |
| 'Programming Language :: Python :: 3.4', |
| 'Topic :: Software Development :: Build Tools'], |
| 'description': 'A sample Python project\n' |
| '=======================\n' |
| '\n' |
| 'This is the description file for the project.\n' |
| '\n' |
| 'The file should use UTF-8 encoding and be written using ' |
| 'ReStructured Text. It\n' |
| 'will be used to generate the project webpage on PyPI, and ' |
| 'should be written for\n' |
| 'that purpose.\n' |
| '\n' |
| 'Typical contents for this file would include an overview of ' |
| 'the project, basic\n' |
| 'usage examples, etc. Generally, including the project ' |
| 'changelog in here is not\n' |
| 'a good idea, although a simple "What\'s New" section for the ' |
| 'most recent version\n' |
| 'may be appropriate.', |
| 'description_content_type': None, |
| 'docs_url': None, |
| 'download_url': 'UNKNOWN', |
| 'downloads': {'last_day': -1, 'last_month': -1, 'last_week': -1}, |
| 'home_page': 'https://github.com/pypa/sampleproject', |
| 'keywords': 'sample setuptools development', |
| 'license': 'MIT', |
| 'maintainer': None, |
| 'maintainer_email': None, |
| 'name': 'sampleproject', |
| 'package_url': 'https://pypi.org/project/sampleproject/', |
| 'platform': 'UNKNOWN', |
| 'project_url': 'https://pypi.org/project/sampleproject/', |
| 'project_urls': {'Download': 'UNKNOWN', |
| 'Homepage': 'https://github.com/pypa/sampleproject'}, |
| 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/', |
| 'requires_dist': None, |
| 'requires_python': None, |
| 'summary': 'A sample Python project', |
| 'version': '1.2.0'} |
| |
| The result can be limited to a certain *depth* (ellipsis is used for deeper |
| contents):: |
| |
| >>> pprint.pprint(project_info, depth=1) |
| {'author': 'The Python Packaging Authority', |
| 'author_email': 'pypa-dev@googlegroups.com', |
| 'bugtrack_url': None, |
| 'classifiers': [...], |
| 'description': 'A sample Python project\n' |
| '=======================\n' |
| '\n' |
| 'This is the description file for the project.\n' |
| '\n' |
| 'The file should use UTF-8 encoding and be written using ' |
| 'ReStructured Text. It\n' |
| 'will be used to generate the project webpage on PyPI, and ' |
| 'should be written for\n' |
| 'that purpose.\n' |
| '\n' |
| 'Typical contents for this file would include an overview of ' |
| 'the project, basic\n' |
| 'usage examples, etc. Generally, including the project ' |
| 'changelog in here is not\n' |
| 'a good idea, although a simple "What\'s New" section for the ' |
| 'most recent version\n' |
| 'may be appropriate.', |
| 'description_content_type': None, |
| 'docs_url': None, |
| 'download_url': 'UNKNOWN', |
| 'downloads': {...}, |
| 'home_page': 'https://github.com/pypa/sampleproject', |
| 'keywords': 'sample setuptools development', |
| 'license': 'MIT', |
| 'maintainer': None, |
| 'maintainer_email': None, |
| 'name': 'sampleproject', |
| 'package_url': 'https://pypi.org/project/sampleproject/', |
| 'platform': 'UNKNOWN', |
| 'project_url': 'https://pypi.org/project/sampleproject/', |
| 'project_urls': {...}, |
| 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/', |
| 'requires_dist': None, |
| 'requires_python': None, |
| 'summary': 'A sample Python project', |
| 'version': '1.2.0'} |
| |
| 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=1, width=60) |
| {'author': 'The Python Packaging Authority', |
| 'author_email': 'pypa-dev@googlegroups.com', |
| 'bugtrack_url': None, |
| 'classifiers': [...], |
| 'description': 'A sample Python project\n' |
| '=======================\n' |
| '\n' |
| 'This is the description file for the ' |
| 'project.\n' |
| '\n' |
| 'The file should use UTF-8 encoding and be ' |
| 'written using ReStructured Text. It\n' |
| 'will be used to generate the project ' |
| 'webpage on PyPI, and should be written ' |
| 'for\n' |
| 'that purpose.\n' |
| '\n' |
| 'Typical contents for this file would ' |
| 'include an overview of the project, ' |
| 'basic\n' |
| 'usage examples, etc. Generally, including ' |
| 'the project changelog in here is not\n' |
| 'a good idea, although a simple "What\'s ' |
| 'New" section for the most recent version\n' |
| 'may be appropriate.', |
| 'description_content_type': None, |
| 'docs_url': None, |
| 'download_url': 'UNKNOWN', |
| 'downloads': {...}, |
| 'home_page': 'https://github.com/pypa/sampleproject', |
| 'keywords': 'sample setuptools development', |
| 'license': 'MIT', |
| 'maintainer': None, |
| 'maintainer_email': None, |
| 'name': 'sampleproject', |
| 'package_url': 'https://pypi.org/project/sampleproject/', |
| 'platform': 'UNKNOWN', |
| 'project_url': 'https://pypi.org/project/sampleproject/', |
| 'project_urls': {...}, |
| 'release_url': 'https://pypi.org/project/sampleproject/1.2.0/', |
| 'requires_dist': None, |
| 'requires_python': None, |
| 'summary': 'A sample Python project', |
| 'version': '1.2.0'} |
