pprint — модуль форматированного вывода данных

Функции

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

Выводит форматированное представление object с последующим переводом строки. Если sort_dicts имеет значение false (по умолчанию), словари будут отображаться в порядке вставки ключей; в противном случае ключи словарей будут отсортированы. args и kwargs передаются в pprint() в качестве параметров форматирования.

>>> import pprint
>>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']
>>> stuff.insert(0, stuff)
>>> pprint.pp(stuff)
[<Recursion on list with id=...>,
 'spam',
 'eggs',
 'lumberjack',
 'knights',
 'ni']

Добавлено в версии 3.8.

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

Выводит форматированное представление object в stream с последующим переводом строки. Если stream — None, используется sys.stdout. Эту функцию можно использовать в интерактивном интерпретаторе вместо функции print() для просмотра значений (можно даже переназначить print = pprint.pprint для использования в пределах области видимости).

Параметры конфигурации stream, indent, width, depth, compact, sort_dicts и underscore_numbers передаются конструктору PrettyPrinter; их значения описаны ниже в документации к нему.

Обратите внимание: по умолчанию sort_dicts имеет значение True; возможно, вместо него стоит использовать pp(), для которого по умолчанию установлено значение False.

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.isreadable(object)

Определяет, является ли форматированное представление object «читаемым» или можно ли с его помощью восстановить значение посредством eval(). Для рекурсивных объектов всегда возвращает False.

>>> pprint.isreadable(stuff)
False

pprint.isrecursive(object)

Определяет, требуется ли для object рекурсивное представление.

pprint.saferepr(object)

Возвращает строковое представление object, защищённое от рекурсивных структур данных. Если в представлении object обнаруживается рекурсивная ссылка, она представляется как <Recursion on typename with id=number>. В остальном представление не форматируется.

>>> pprint.saferepr(stuff)
"[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"

Объекты PrettyPrinter

Этот модуль определяет один класс:

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

Создаёт экземпляр PrettyPrinter. Этот конструктор принимает несколько именованных параметров.

stream (по умолчанию sys.stdout) — это объект, похожий на файл, в который будет записан вывод путём вызова его метода write(). Если и stream, и sys.stdout имеют значение None, то pprint() незаметно возвращает управление.

Другие значения настраивают способ отображения вложенности сложных структур данных.

indent (по умолчанию 1) задаёт величину отступа для каждого уровня вложенности.

depth задаёт количество уровней вложенности, которые можно вывести; если выводимая структура данных слишком глубока, следующий вложенный уровень заменяется на .... По умолчанию глубина форматируемых объектов не ограничена.

width (по умолчанию 80) задаёт желаемое максимальное количество символов в строке вывода. Если структуру невозможно отформатировать с учётом ограничения ширины, будет предпринята наилучшая попытка.

compact влияет на форматирование длинных последовательностей (списков, кортежей, множеств и т. д.). Если compact имеет значение false (по умолчанию), каждый элемент последовательности форматируется в отдельной строке. Если compact имеет значение true, в каждой строке вывода будет отформатировано столько элементов, сколько помещается в пределах width.

Если sort_dicts имеет значение true (по умолчанию), словари форматируются с сортировкой ключей; в противном случае они отображаются в порядке вставки.

Если underscore_numbers имеет значение true, целые числа форматируются с символом _ в качестве разделителя тысяч; в противном случае подчёркивания не отображаются (по умолчанию).

Изменено в версии 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', (...)))))))

Экземпляры 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, задаёт текущий уровень; в рекурсивные вызовы следует передавать значение меньшее, чем в текущем вызове.

Пример

Чтобы продемонстрировать несколько способов использования функции pp() и её параметров, получим сведения о проекте с 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']

В простейшем случае pp() отображает весь объект:

>>> pprint.pp(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.pp(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.pp(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'}