# `pprint` — Impressão bonita de dados

Código-fonte: Lib/pprint.py

O módulo `pprint` fornece a capacidade de “imprimir de forma bonita” estruturas de dados Python arbitrárias em um formato que pode ser usado como entrada para o interpretador. Se as estruturas formatadas incluírem objetos que não sejam tipos fundamentais do Python, a representação poderá não ser carregável. Este pode ser o caso se objetos como arquivos, soquetes ou classes forem incluídos, bem como muitos outros objetos que não são representáveis como literais do Python.

A representação formatada mantém os objetos em uma única linha, se possível, e os divide em múltiplas linhas se eles não couberem na largura permitida, ajustável pelo parâmetro width padrão para 80 caracteres.

Os dicionários são classificados por chave antes que a exibição seja calculada.

Alterado na versão 3.9: Adicionado suporte para impressão bonita de `types.SimpleNamespace`.

Alterado na versão 3.10: Adicionado suporte para impressão bonita de `dataclasses.dataclass`.

## Funções

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

  Imprime a representação formatada de object, seguida por uma nova linha. Esta função pode ser usado no interpretador interativo em vez da função `print()` para inspecionar valores. Dica: você pode reatribuir `print = pprint.pp` para uso dentro de um escopo.

  Parâmetros:

    - object – O objeto a ser impresso.

    - stream (file-like object | None) – Um objeto arquivo ou similar no qual a saída será gravada chamando seu método `write()`. Se `None` (o padrão), `sys.stdout` será usado.

    - indent (int) – A quantidade de indentação adicionado para cada nível de aninhamento.

    - width (int) – O número máximo desejado de caracteres por linha na saída. Se uma estrutura não puder ser formatada dentro da restrição de largura, será feito o melhor esforço.

    - depth (int | None) – O número de níveis de aninhamento que podem ser impressos. Se a estrutura de dados que está sendo impressa for muito profunda, o próximo nível contido será substituído por `...`. Se `None` (o padrão), não há restrição na profundidade dos objetos que estão sendo formatados.

    - compact (bool) – Controla a forma como sequências são formatadas. Se `False` (o padrão), cada item de uma sequência será formatado em uma linha separada, caso contrário, tantos itens quantos couberem na largura serão formatados em cada linha de saída.

    - sort_dicts (bool) – Se `True`, os dicionários serão formatados com suas chaves classificadas, caso contrário, serão exibidos na ordem de inserção (o padrão).

    - underscore_numbers (bool) – Se `True`, os números inteiros serão formatados com o caractere `_` para um separador de milhares, caso contrário, os sublinhados não serão exibidos (o padrão).

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

  Adicionado na versão 3.8.

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

  Apelido para `pp()` com sort_dicts definido como `True` por padrão, o que classificaria automaticamente as chaves dos dicionários, você pode querer usar `pp()` em vez disso, onde é `False` por padrão.

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

  Retorna a representação formatada de object como uma string. indent, width, depth, compact, sort_dicts e underscore_numbers são passados para o construtor de `PrettyPrinter` como parâmetros de formatação e seus significados são descritos na documentação acima.

pprint.isreadable(object)

  Determina se a representação formatada de object é “legível” ou pode ser usada para reconstruir o valor usando `eval()`. Isso sempre retorna `False` para objetos recursivos.

      >>> pprint.isreadable(stuff)
      False

pprint.isrecursive(object)

  Determina se object requer uma representação recursiva. Esta função está sujeita às mesmas limitações mencionadas em `saferepr()` abaixo e pode levantar uma exceção `RecursionError` se falhar em detectar um objeto recursivo.

pprint.saferepr(object)

  Retorna uma representação de string de object, protegida contra recursão em algumas estruturas de dados comuns, nomeadamente instâncias de `dict`, `list` e `tuple` ou subclasses cujo `__repr__` não foi substituído. Se a representação do objeto expõe uma entrada recursiva, a referência recursiva será representada como `<Recursion on typename with id=number>`. A representação não é formatada de outra forma.

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

## Objetos PrettyPrinter

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

  Constrói uma instância `PrettyPrinter`.

  Os argumentos têm o mesmo significado que para `pp()`. Observe que eles estão em uma ordem diferente e que o padrão 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', (...)))))))

  Alterado na versão 3.4: Adicionado o parâmetro compact.

  Alterado na versão 3.8: Adicionado o parâmetro sort_dicts.

  Alterado na versão 3.10: Adicionado o parâmetro underscore_numbers.

  Alterado na versão 3.11: Não tenta mais escrever em `sys.stdout` se for `None`.

Instâncias `PrettyPrinter` contêm os seguintes métodos:

PrettyPrinter.pformat(object)

  Retorna a representação formatada de object. Isso leva em consideração as opções passadas para o construtor `PrettyPrinter`.

PrettyPrinter.pprint(object)

  Exibe a representação formatada de object no fluxo configurado, seguida por uma nova linha.

Os métodos a seguir fornecem as implementações para as funções correspondentes com os mesmos nomes. Usar esses métodos em uma instância é um pouco mais eficiente já que novos objetos `PrettyPrinter` não precisam ser criados.

PrettyPrinter.isreadable(object)

  Determina se a representação formatada do objeto é “legível” ou pode ser usada para reconstruir o valor usando `eval()`. Observe que isso retorna `False` para objetos recursivos. Se o parâmetro depth de `PrettyPrinter` estiver definido e o objeto for mais profundo que o permitido, isso retornará `False`.

PrettyPrinter.isrecursive(object)

  Determina se o objeto requer uma representação recursiva.

Este método é fornecido como um gancho para permitir que as subclasses modifiquem a maneira como os objetos são convertidos em strings. A implementação padrão usa os componentes internos da implementação de `saferepr()`.

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

  Retorna três valores: a versão formatada de object como uma string, um sinalizador indicando se o resultado é legível e um sinalizador indicando se a recursão foi detectada. O primeiro argumento é o objeto a ser apresentado. O segundo é um dicionário que contém o `id()` de objetos que fazem parte do contexto de apresentação atual (contêineres diretos e indiretos para objects que estão afetando a apresentação) como chaves; se for necessário apresentar um objeto que já esteja representado em context, o terceiro valor de retorno deverá ser `True`. Chamadas recursivas ao método `format()` devem adicionar entradas adicionais para contêineres neste dicionário. O terceiro argumento, maxlevels, fornece o limite solicitado para recursão; será `0` se não houver limite solicitado. Este argumento deve ser passado sem modificações para chamadas recursivas. O quarto argumento, level, fornece o nível atual; chamadas recursivas devem receber um valor menor que o da chamada atual.

## Exemplo

Para demonstrar vários usos da função `pp()` e seus parâmetros, vamos buscar informações sobre um projeto no 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']

Em sua forma básica, `pp()` mostra o objeto inteiro:

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

O resultado pode ser limitado a uma certa depth (reticências são usadas para conteúdos mais profundos):

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

Além disso, a largura width máxima do caractere pode ser sugerida. Se um objeto longo não puder ser dividido, a largura especificada será excedida:

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