pprint —- 数据美化输出

源代码：Lib/pprint.py

pprint 模块提供了“美化打印”任意 Python 数据结构的功能，这种美化形式可用作对解释器的输入。 如果经格式化的结构包含非基本 Python 类型的对象，则其美化形式可能无法被加载。 包含文件、套接字或类对象，以及许多其他不能用 Python 字面值来表示的对象都有可能导致这样的结果。

格式化后的形式会在可能的情况下以单行来表示对象，并在无法在允许宽度内容纳对象的情况下将其分为多行。 如果你需要调整宽度限制则应显式地构造 PrettyPrinter 对象。

Dictionaries are sorted by key before the display is computed.字典在被计算前通过键值来排序。

pprint 模块定义了一个类：

  • class pprint.PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, compact=False)
  • 构造一个 PrettyPrinter 实例。 此构造器接受几个关键字形参。 使用 stream 关键字可设置输出流；在流对象上使用的唯一方法是文件协议的 write() 方法。 如果未指定此关键字，则 PrettyPrinter 会选择 sys.stdout。 每个递归层级的缩进量由 indent 指定；默认值为一。 其他值可导致输出看起来有些怪异，但可使得嵌套结构更易区分。 可被打印的层级数量由 depth 控制；如果数据结构的层级被打印得过深，其所包含的下一层级会被替换为 …。 在默认情况下，对被格式化对象的层级深度没有限制。 希望的输出宽度可使用 width 形参来限制；默认值为 80 个字符。 如果一个结构无法在限定宽度内被格式化，则将做到尽可能接近。 如果 compact 为假值（默认）则长序列的每一项将被格式化为单独的行。 如果 compact 为真值，则格式化将在 width 可容纳的情况下把尽可能多的项放入每个输出行。

在 3.4 版更改: 加入compact 参数。

  1. >>> import pprint
  2. >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
  3. >>> stuff.insert(0, stuff[:])
  4. >>> pp = pprint.PrettyPrinter(indent=4)
  5. >>> pp.pprint(stuff)
  6. [   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],
  7.     'spam',
  8.     'eggs',
  9.     'lumberjack',
  10.     'knights',
  11.     'ni']
  12. >>> pp = pprint.PrettyPrinter(width=41, compact=True)
  13. >>> pp.pprint(stuff)
  14. [['spam', 'eggs', 'lumberjack',
  15.   'knights', 'ni'],
  16.  'spam', 'eggs', 'lumberjack', 'knights',
  17.  'ni']
  18. >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
  19. ... ('parrot', ('fresh fruit',))))))))
  20. >>> pp = pprint.PrettyPrinter(depth=6)
  21. >>> pp.pprint(tup)
  22. ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))

pprint 模块还提供了一些快捷函数：

  • pprint.pformat(object, indent=1, width=80, depth=None, *, compact=False)
  • 将 object 格式化表示作为字符串返回。 indent, width, depth 和 compact 将作为格式化形参被传入 PrettyPrinter 构造器。

在 3.4 版更改: 加入compact 参数。

  • pprint.pprint(object, stream=None, indent=1, width=80, depth=None, *, compact=False)
  • 在 stream 上打印 object 的格式化表示，并附带一个换行符。 如果 stream 为 None，则使用 sys.stdout。 这可以替换 print() 函数在交互式解释器中使用以查看值（你甚至可以执行重新赋值 print = pprint.pprint 以在特定作用域中使用）。 indent, width, depth 和 compact 将作为格式化形参被传给 PrettyPrinter 构造器。

在 3.4 版更改: 加入compact 参数。

  1. >>> import pprint
  2. >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
  3. >>> stuff.insert(0, stuff)
  4. >>> pprint.pprint(stuff)
  5. [<Recursion on list with id=...>,
  6.  'spam',
  7.  'eggs',
  8.  'lumberjack',
  9.  'knights',
  10.  'ni']
  • pprint.isreadable(object)
  • 确定 object 的格式化表示是否“可读”，或是否可被用来通过 eval() 重新构建对象的值。 此函数对于递归对象总是返回 False。
  1. >>> pprint.isreadable(stuff)
  2. False
  • pprint.isrecursive(object)
  • 确定 object 是否需要递归表示。

此外还定义了一个支持函数：

  • pprint.saferepr(object)
  • 返回 object 的字符串表示，并为递归数据结构提供保护。 如果 object 的表示形式公开了一个递归条目，该递归引用会被表示为 <Recursion on typename with id=number>。 该表示因而不会进行其它格式化。
  1. >>> pprint.saferepr(stuff)
  2. "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"

PrettyPrinter 对象

PrettyPrinter 的实例具有下列方法：

  • PrettyPrinter.pformat(object)
  • 返回 object 格式化表示。 这会将传给 PrettyPrinter 构造器的选项纳入考虑。
  • PrettyPrinter.pprint(object)
  • 在所配置的流上打印 object 的格式化表示，并附加一个换行符。

下列方法提供了与同名函数相对应的实现。 在实例上使用这些方法效率会更高一些，因为不需要创建新的 PrettyPrinter 对象。

  • PrettyPrinter.isreadable(object)
  • 确定对象的格式化表示是否“可读”，或者是否可使用 eval() 重建对象值。 请注意此方法对于递归对象将返回 False。 如果设置了 PrettyPrinter 的 depth 形参并且对象深度超出允许范围，此方法将返回 False。
  • PrettyPrinter.isrecursive(object)
  • 确定对象是否需要递归表示。

此方法作为一个钩子提供，允许子类修改将对象转换为字符串的方式。 默认实现使用 saferepr() 实现的内部方式。

  • PrettyPrinter.format(object, context, maxlevels, level)
  • 返回三个值：字符串形式的 object 已格式化版本，指明结果是否可读的旗标，以及指明是否检测到递归的旗标。 第一个参数是要表示的对象。 第二个是以对象 id() 为键的字典，这些对象是当前表示上下文的一部分（影响 object 表示的直接和间接容器）；如果需要呈现一个已经在 context 中表示的对象，则第三个返回值应当为 True。 对 format() 方法的递归调用应当将容器的附加条目添加到此字典中。 第三个参数 maxlevels 给出了对递归的请求限制；如果没有请求限制则其值将为 0。 此参数应当不加修改地传给递归调用。 第四个参数 level 给出于当前层级；传给递归调用的参数值应当小于当前调用的值。

示例

为了演示 pprint() 函数及其形参的几种用法，让我们从 PyPI 获取关于某个项目的信息:

  1. >>> import json
  2. >>> import pprint
  3. >>> from urllib.request import urlopen
  4. >>> with urlopen('https://pypi.org/pypi/sampleproject/json') as resp:
  5. ...     project_info = json.load(resp)['info']

pprint() 以其基本形式显示了整个对象:

  1. >>> pprint.pprint(project_info)
  2. {'author': 'The Python Packaging Authority',
  3.  'author_email': 'pypa-dev@googlegroups.com',
  4.  'bugtrack_url': None,
  5.  'classifiers': ['Development Status :: 3 - Alpha',
  6.                  'Intended Audience :: Developers',
  7.                  'License :: OSI Approved :: MIT License',
  8.                  'Programming Language :: Python :: 2',
  9.                  'Programming Language :: Python :: 2.6',
  10.                  'Programming Language :: Python :: 2.7',
  11.                  'Programming Language :: Python :: 3',
  12.                  'Programming Language :: Python :: 3.2',
  13.                  'Programming Language :: Python :: 3.3',
  14.                  'Programming Language :: Python :: 3.4',
  15.                  'Topic :: Software Development :: Build Tools'],
  16.  'description': 'A sample Python project\n'
  17.                 '=======================\n'
  18.                 '\n'
  19.                 'This is the description file for the project.\n'
  20.                 '\n'
  21.                 'The file should use UTF-8 encoding and be written using '
  22.                 'ReStructured Text. It\n'
  23.                 'will be used to generate the project webpage on PyPI, and '
  24.                 'should be written for\n'
  25.                 'that purpose.\n'
  26.                 '\n'
  27.                 'Typical contents for this file would include an overview of '
  28.                 'the project, basic\n'
  29.                 'usage examples, etc. Generally, including the project '
  30.                 'changelog in here is not\n'
  31.                 'a good idea, although a simple "What\'s New" section for the '
  32.                 'most recent version\n'
  33.                 'may be appropriate.',
  34.  'description_content_type': None,
  35.  'docs_url': None,
  36.  'download_url': 'UNKNOWN',
  37.  'downloads': {'last_day': -1, 'last_month': -1, 'last_week': -1},
  38.  'home_page': 'https://github.com/pypa/sampleproject',
  39.  'keywords': 'sample setuptools development',
  40.  'license': 'MIT',
  41.  'maintainer': None,
  42.  'maintainer_email': None,
  43.  'name': 'sampleproject',
  44.  'package_url': 'https://pypi.org/project/sampleproject/',
  45.  'platform': 'UNKNOWN',
  46.  'project_url': 'https://pypi.org/project/sampleproject/',
  47.  'project_urls': {'Download': 'UNKNOWN',
  48.                   'Homepage': 'https://github.com/pypa/sampleproject'},
  49.  'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
  50.  'requires_dist': None,
  51.  'requires_python': None,
  52.  'summary': 'A sample Python project',
  53.  'version': '1.2.0'}

结果可以被限制到特定的 depth (更深层的内容将使用省略号):

  1. >>> pprint.pprint(project_info, depth=1)
  2. {'author': 'The Python Packaging Authority',
  3.  'author_email': 'pypa-dev@googlegroups.com',
  4.  'bugtrack_url': None,
  5.  'classifiers': [...],
  6.  'description': 'A sample Python project\n'
  7.                 '=======================\n'
  8.                 '\n'
  9.                 'This is the description file for the project.\n'
  10.                 '\n'
  11.                 'The file should use UTF-8 encoding and be written using '
  12.                 'ReStructured Text. It\n'
  13.                 'will be used to generate the project webpage on PyPI, and '
  14.                 'should be written for\n'
  15.                 'that purpose.\n'
  16.                 '\n'
  17.                 'Typical contents for this file would include an overview of '
  18.                 'the project, basic\n'
  19.                 'usage examples, etc. Generally, including the project '
  20.                 'changelog in here is not\n'
  21.                 'a good idea, although a simple "What\'s New" section for the '
  22.                 'most recent version\n'
  23.                 'may be appropriate.',
  24.  'description_content_type': None,
  25.  'docs_url': None,
  26.  'download_url': 'UNKNOWN',
  27.  'downloads': {...},
  28.  'home_page': 'https://github.com/pypa/sampleproject',
  29.  'keywords': 'sample setuptools development',
  30.  'license': 'MIT',
  31.  'maintainer': None,
  32.  'maintainer_email': None,
  33.  'name': 'sampleproject',
  34.  'package_url': 'https://pypi.org/project/sampleproject/',
  35.  'platform': 'UNKNOWN',
  36.  'project_url': 'https://pypi.org/project/sampleproject/',
  37.  'project_urls': {...},
  38.  'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
  39.  'requires_dist': None,
  40.  'requires_python': None,
  41.  'summary': 'A sample Python project',
  42.  'version': '1.2.0'}

此外，还可以设置建议的最大字符 width。 如果一个对象无法被拆分，则将超出指定宽度:

  1. >>> pprint.pprint(project_info, depth=1, width=60)
  2. {'author': 'The Python Packaging Authority',
  3.  'author_email': 'pypa-dev@googlegroups.com',
  4.  'bugtrack_url': None,
  5.  'classifiers': [...],
  6.  'description': 'A sample Python project\n'
  7.                 '=======================\n'
  8.                 '\n'
  9.                 'This is the description file for the '
  10.                 'project.\n'
  11.                 '\n'
  12.                 'The file should use UTF-8 encoding and be '
  13.                 'written using ReStructured Text. It\n'
  14.                 'will be used to generate the project '
  15.                 'webpage on PyPI, and should be written '
  16.                 'for\n'
  17.                 'that purpose.\n'
  18.                 '\n'
  19.                 'Typical contents for this file would '
  20.                 'include an overview of the project, '
  21.                 'basic\n'
  22.                 'usage examples, etc. Generally, including '
  23.                 'the project changelog in here is not\n'
  24.                 'a good idea, although a simple "What\'s '
  25.                 'New" section for the most recent version\n'
  26.                 'may be appropriate.',
  27.  'description_content_type': None,
  28.  'docs_url': None,
  29.  'download_url': 'UNKNOWN',
  30.  'downloads': {...},
  31.  'home_page': 'https://github.com/pypa/sampleproject',
  32.  'keywords': 'sample setuptools development',
  33.  'license': 'MIT',
  34.  'maintainer': None,
  35.  'maintainer_email': None,
  36.  'name': 'sampleproject',
  37.  'package_url': 'https://pypi.org/project/sampleproject/',
  38.  'platform': 'UNKNOWN',
  39.  'project_url': 'https://pypi.org/project/sampleproject/',
  40.  'project_urls': {...},
  41.  'release_url': 'https://pypi.org/project/sampleproject/1.2.0/',
  42.  'requires_dist': None,
  43.  'requires_python': None,
  44.  'summary': 'A sample Python project',
  45.  'version': '1.2.0'}