"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" 则将不会尝试向其中写入
   。

   >>> 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', (...)))))))

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" 构
   造器，它们的含义见以上相应文档的说明。

   >>> 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']

pprint.isreadable(object)

   确定 *object* 的格式化表示是否“可读”，或是否可被用来通过 "eval()"
   重新构建对象的值。 此函数对于递归对象总是返回 "False"。

   >>> pprint.isreadable(stuff)
   False

pprint.isrecursive(object)

   确定 *object* 是否需要递归的表示。 此函数会受到下面 "saferepr()" 所
   提及的同样限制的影响并可能在无法检测到可递归对象时引发
   "RecursionError"。

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

pprint.saferepr(object)

   返回 *object* 的字符串表示，并为某些通用数据结构提供防递归保护，包
   括 "dict", "list" 和 "tuple" 或其未重载 "__repr__" 的子类的实例。
   如果该对象表示形式公开了一个递归条目，该递归引用会被表示为
   "<Recursion on typename with id=number>"。 否则该表示形式将不会被格
   式化。

   >>> pprint.saferepr(stuff)
   "[<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 获取关于某个
项目的信息:

   >>> 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']

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

   >>> 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'}

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

   >>> 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'}

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

   >>> 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'}
