pprint —- 数据美化输出

源代码： Lib/pprint.py

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

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

字典在计算其显示形式前会先根据键来排序。

在 3.9 版更改: 添加了对美化打印 types.SimpleNamespace 的支持。

在 3.10 版更改: 添加了对美化打印 dataclasses.dataclass 的支持。

pprint 模块定义了一个类：

class pprint.PrettyPrinter(indent=1, width=80, depth=None, stream=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

构造一个 PrettyPrinter 实例。 这个构造器支持一些关键字形参。

stream (默认为 sys.stdout) 是一个 file-like object，它是当调用其 write() 方法时的输出将要写入的目标。 如果 stream 和 sys.stdout 均为 None，则 pprint() 将静默地返回。

其他值可用来配置复杂数据结构嵌套要以何种形式被展示。

indent (默认为 1) 指定要为每个缩进层级添加的缩进量。

depth 控制可被打印的缩进层级数量；如果要打印的数据结构层级过深，则其所包含的下一层级将用 ... 替换。 默认情况下，对于被格式化对象的层级深度没有任何限制。

width (默认为 80) 指定输出中每行所允许的最大字符数。 如果一个数据结构无法在宽度限制之内被格式化，将显示尽可能多的内容。

compact 影响长序列（列表、元组、集合等等）的格式化方式。 如果 compact 为假值（默认）则序列的每一项将格式化为单独的行。 如果 compact 为真值，则每个输出行格式化时将在 width 的限制之内尽可能地容纳多个条目。

如果 sort_dicts 为真值（默认），字典在格式化时将基于键进行排序，否则它们将按插入顺序显示。

如果 underscore_numbers 为真值，整数在格式化时将使用 _ 字符作为千位分隔符，否则不显示下划线（默认）。

在 3.4 版更改: 增加了 compact 形参。

在 3.8 版更改: 增加了 sort_dicts 形参。

在 3.10 版更改: 添加了 underscore_numbers 形参。

在 3.11 版更改: 如果 sys.stdout 为 None 则将不会尝试向其中写入。

  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.pformat(object, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

将 object 的格式化表示形式作为字符串返回。 indent, width, depth, compact, sort_dicts 和 underscore_numbers 将作为格式化形参传递给 PrettyPrinter 构造器，它们的含义见以上相应文档的说明。

pprint.pp(object, *args, sort_dicts=False, **kwargs)

打印 object 的格式化表示并附带一个换行符。 如果 sort_dicts 为假值（默认），字典将按键的插入顺序显示，否则将按字典键排序。 args 和 kwargs 将作为格式化形参被传给 pprint()。

3.8 新版功能.

pprint.pprint(object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)

在 stream 上打印 object 的格式化表示形式。 如果 stream 为 None，则会使用 sys.stdout。 这可以在交互式解释器中代替 print() 函数使用以便检查对象的值（你甚至可以通过重赋值 print = pprint.pprint 在特定作用域内使用）。

配置形参 stream, indent, width, depth, compact, sort_dicts 和 underscore_numbers 将被传递给 PrettyPrinter 构造器，它们的含义见以上相应文档的说明。

  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 是否需要递归的表示。 此函数会受到下面 saferepr() 所提及的同样限制的影响并可能在无法检测到可递归对象时引发 RecursionError。

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

pprint.saferepr(object)

返回 object 的字符串表示，并为某些通用数据结构提供防递归保护，包括 dict, list 和 tuple 或其未重载 __repr__ 的子类的实例。 如果该对象表示形式公开了一个递归条目，该递归引用会被表示为 <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'}