pprint — Печать данных с красивым выводом

Исходный код: Lib/pprint.py

Модуль pprint предоставляет возможность «красивой печати» произвольных структур данных Python в формате, который можно использовать в качестве входных данных для интерпретатора. Если отформатированные структуры включают объекты, которые не являются фундаментальными типами Python, представление может быть не загружаемым. Это может быть случай, если включены такие объекты, как файлы, сокеты или классы, а также многие другие объекты, которые не могут быть представлены в виде литералов Python.

Отформатированное представление сохраняет объекты на одной строке, если это возможно, и разбивает их на несколько строк, если они не помещаются в разрешенную ширину. Явно создавайте объекты PrettyPrinter, если вам нужно скорректировать ограничение по ширине.

Словари сортируются по ключу перед вычислением отображения.

Модуль 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 имеет значение false (по умолчанию), каждый элемент длинной последовательности будет форматироваться на отдельной строке. Если compact имеет значение true, столько элементов, сколько поместится в width, будет отформатировано в каждой строке вывода.

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

>>> 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 также предоставляет несколько сокращённых функций:

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)

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

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

>>> 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 рекурсивного представления.

Также определена ещё одна вспомогательная функция:

pprint.saferepr(object)

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

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

1. Объекты PrettyPrinter

PrettyPrinter экземпляры имеют следующие методы:

PrettyPrinter.pformat(object)

Возвращает отформатированное представление object. Это учитывает параметры, переданные конструктору PrettyPrinter.

PrettyPrinter.pprint(object)

Выводит отформатированное представление object в настроенный поток, за которым следует перевод строки.

Следующие методы предоставляют реализации соответствующих функций с одинаковыми именами. Использование этих методов на экземпляре несколько эффективнее, так как для создания новых объектов PrettyPrinter не требуется.

PrettyPrinter.isreadable(object)

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

PrettyPrinter.isrecursive(object)

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

Этот метод предоставляется как крючок, позволяющий подклассам изменять способ преобразования объектов в строки. По умолчанию реализация использует внутренние механизмы реализации saferepr().

PrettyPrinter.format(object, context, maxlevels, level)

Возвращает три значения: отформатированную версию object в виде строки, флаг, указывающий, является ли результат читаемым, и флаг, указывающий, была ли обнаружена рекурсия. Первый аргумент — объект, который нужно представить. Второй — словарь, который содержит id() объектов, которые являются частью текущего контекста представления (прямые и косвенные контейнеры для object, которые влияют на представление), в качестве ключей; если нужно представить объект, который уже представлен в context, третье возвращаемое значение должно быть True. Рекурсивные вызовы метода format() должны добавлять дополнительные записи для контейнеров в этот словарь. Третий аргумент, maxlevels, задаёт требуемый лимит рекурсии; это будет 0 если лимит не запрошен. Этот аргумент должен передаваться без изменений рекурсивным вызовам. Четвёртый аргумент, level, представляет текущий уровень; рекурсивные вызовы должны передавать значение меньше, чем значение текущего вызова.

2. Пример

Чтобы продемонстрировать несколько способов использования функции pprint() и её параметров, давайте получим информацию о проекте из PyPI:

>>> import json
>>> import pprint
>>> from urllib.request import urlopen
>>> with urlopen('http://pypi.python.org/pypi/Twisted/json') as url:
...     http_info = url.info()
...     raw_data = url.read().decode(http_info.get_content_charset())
>>> project_info = json.loads(raw_data)

В базовом виде pprint() отображает весь объект:

>>> pprint.pprint(project_info)
{'info': {'_pypi_hidden': False,
          '_pypi_ordering': 125,
          'author': 'Glyph Lefkowitz',
          'author_email': 'glyph@twistedmatrix.com',
          'bugtrack_url': '',
          'cheesecake_code_kwalitee_id': None,
          'cheesecake_documentation_id': None,
          'cheesecake_installability_id': None,
          'classifiers': ['Programming Language :: Python :: 2.6',
                          'Programming Language :: Python :: 2.7',
                          'Programming Language :: Python :: 2 :: Only'],
          'description': 'An extensible framework for Python programming, with '
                         'special focus\r\n'
                         'on event-based network programming and multiprotocol '
                         'integration.',
          'docs_url': '',
          'download_url': 'UNKNOWN',
          'home_page': 'http://twistedmatrix.com/',
          'keywords': '',
          'license': 'MIT',
          'maintainer': '',
          'maintainer_email': '',
          'name': 'Twisted',
          'package_url': 'http://pypi.python.org/pypi/Twisted',
          'platform': 'UNKNOWN',
          'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0',
          'requires_python': None,
          'stable_version': None,
          'summary': 'An asynchronous networking framework written in Python',
          'version': '12.3.0'},
 'urls': [{'comment_text': '',
           'downloads': 71844,
           'filename': 'Twisted-12.3.0.tar.bz2',
           'has_sig': False,
           'md5_digest': '6e289825f3bf5591cfd670874cc0862d',
           'packagetype': 'sdist',
           'python_version': 'source',
           'size': 2615733,
           'upload_time': '2012-12-26T12:47:03',
           'url': 'https://pypi.python.org/packages/source/T/Twisted/Twisted-12.3.0.tar.bz2'},
          {'comment_text': '',
           'downloads': 5224,
           'filename': 'Twisted-12.3.0.win32-py2.7.msi',
           'has_sig': False,
           'md5_digest': '6b778f5201b622a5519a2aca1a2fe512',
           'packagetype': 'bdist_msi',
           'python_version': '2.7',
           'size': 2916352,
           'upload_time': '2012-12-26T12:48:15',
           'url': 'https://pypi.python.org/packages/2.7/T/Twisted/Twisted-12.3.0.win32-py2.7.msi'}]}

Результат можно ограничить определённой depth (для более глубоких содержимых используется многоточие):

>>> pprint.pprint(project_info, depth=2)
{'info': {'_pypi_hidden': False,
          '_pypi_ordering': 125,
          'author': 'Glyph Lefkowitz',
          'author_email': 'glyph@twistedmatrix.com',
          'bugtrack_url': '',
          'cheesecake_code_kwalitee_id': None,
          'cheesecake_documentation_id': None,
          'cheesecake_installability_id': None,
          'classifiers': [...],
          'description': 'An extensible framework for Python programming, with '
                         'special focus\r\n'
                         'on event-based network programming and multiprotocol '
                         'integration.',
          'docs_url': '',
          'download_url': 'UNKNOWN',
          'home_page': 'http://twistedmatrix.com/',
          'keywords': '',
          'license': 'MIT',
          'maintainer': '',
          'maintainer_email': '',
          'name': 'Twisted',
          'package_url': 'http://pypi.python.org/pypi/Twisted',
          'platform': 'UNKNOWN',
          'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0',
          'requires_python': None,
          'stable_version': None,
          'summary': 'An asynchronous networking framework written in Python',
          'version': '12.3.0'},
 'urls': [{...}, {...}]}

Кроме того, можно предложить максимальную ширину символов width. Если длинный объект нельзя разделить, указанная ширина будет превышена:

>>> pprint.pprint(project_info, depth=2, width=50)
{'info': {'_pypi_hidden': False,
          '_pypi_ordering': 125,
          'author': 'Glyph Lefkowitz',
          'author_email': 'glyph@twistedmatrix.com',
          'bugtrack_url': '',
          'cheesecake_code_kwalitee_id': None,
          'cheesecake_documentation_id': None,
          'cheesecake_installability_id': None,
          'classifiers': [...],
          'description': 'An extensible '
                         'framework for Python '
                         'programming, with '
                         'special focus\r\n'
                         'on event-based network '
                         'programming and '
                         'multiprotocol '
                         'integration.',
          'docs_url': '',
          'download_url': 'UNKNOWN',
          'home_page': 'http://twistedmatrix.com/',
          'keywords': '',
          'license': 'MIT',
          'maintainer': '',
          'maintainer_email': '',
          'name': 'Twisted',
          'package_url': 'http://pypi.python.org/pypi/Twisted',
          'platform': 'UNKNOWN',
          'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0',
          'requires_python': None,
          'stable_version': None,
          'summary': 'An asynchronous networking '
                     'framework written in '
                     'Python',
          'version': '12.3.0'},
 'urls': [{...}, {...}]}