pprint — средство форматированного вывода данных

Функции

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

Выводит отформатированное представление object, а затем символ новой строки. Эту функцию можно использовать в интерактивном интерпретаторе вместо функции print() для просмотра значений. Совет: для использования в области видимости можно переназначить print = pprint.pp.

Параметры:

• object – Объект для вывода.
• stream (файлоподобный объект | None) – Файлоподобный объект, в который будет записан вывод посредством вызова его метода write(). Если задано None (по умолчанию), используется sys.stdout.
• indent (int) – Величина отступа для каждого уровня вложенности.
• width (int) – Желаемое максимальное число символов в строке вывода. Если структуру нельзя отформатировать в пределах заданной ширины, будет предпринята попытка максимально приблизиться к этому ограничению.
• depth (int | None) – Число уровней вложенности, которые можно вывести. Если выводимая структура данных слишком глубока, следующий вложенный уровень заменяется на .... Если задано None (по умолчанию), глубина форматируемых объектов не ограничивается.
• compact (bool) – Управляет форматированием длинных последовательностей. Если задано False (по умолчанию), каждый элемент последовательности форматируется в отдельной строке; в противном случае в каждой строке вывода форматируется столько элементов, сколько помещается в пределах width.
• sort_dicts (bool) – Если задано True, словари форматируются с сортировкой ключей; в противном случае они выводятся в порядке вставки (по умолчанию).
• underscore_numbers (bool) – Если задано True, целые числа форматируются с символом _ в качестве разделителя тысяч; в противном случае подчёркивания не выводятся (по умолчанию).

>>> 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)

Псевдоним для pp(), у которого по умолчанию параметр 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 рекурсивного представления. На эту функцию распространяются те же ограничения, что и на 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

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

Создаёт экземпляр PrettyPrinter.

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

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

Изменено в версии 3.4: Добавлен параметр compact.

Изменено в версии 3.8: Добавлен параметр sort_dicts.

Изменено в версии 3.10: Добавлен параметр underscore_numbers.

Изменено в версии 3.11: Больше не предпринимается попытка записи в sys.stdout, если он задан как None.

Экземпляры 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/1.2.0/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'}