"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 várias linhas se não couberem na largura
permitida. Construa objetos "PrettyPrinter" explicitamente se precisar
ajustar a restrição de largura.

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

The "pprint" module defines one class:

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

   Construct a "PrettyPrinter" instance.  This constructor understands
   several keyword parameters.  An output stream may be set using the
   *stream* keyword; the only method used on the stream object is the
   file protocol's "write()" method.  If not specified, the
   "PrettyPrinter" adopts "sys.stdout".  The amount of indentation
   added for each recursive level is specified by *indent*; the
   default is one.  Other values can cause output to look a little
   odd, but can make nesting easier to spot.  The number of levels
   which may be printed is controlled by *depth*; if the data
   structure being printed is too deep, the next contained level is
   replaced by "...".  By default, there is no constraint on the depth
   of the objects being formatted.  The desired output width is
   constrained using the *width* parameter; the default is 80
   characters.  If a structure cannot be formatted within the
   constrained width, a best effort will be made.  If *compact* is
   false (the default) each item of a long sequence will be formatted
   on a separate line.  If *compact* is true, as many items as will
   fit within the *width* will be formatted on each output line. If
   *sort_dicts* is true (the default), dictionaries will be formatted
   with their keys sorted, otherwise they will display in insertion
   order.

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

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

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

The "pprint" module also provides several shortcut functions:

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

   Return the formatted representation of *object* as a string.
   *indent*, *width*, *depth*, *compact* and *sort_dicts* will be
   passed to the "PrettyPrinter" constructor as formatting parameters.

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

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

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

   Prints the formatted representation of *object* followed by a
   newline. If *sort_dicts* is false (the default), dictionaries will
   be displayed with their keys in insertion order, otherwise the dict
   keys will be sorted. *args* and *kwargs* will be passed to
   "pprint()" as formatting parameters.

   Novo na versão 3.8.

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

   Prints the formatted representation of *object* on *stream*,
   followed by a newline.  If *stream* is "None", "sys.stdout" is
   used.  This may be used in the interactive interpreter instead of
   the "print()" function for inspecting values (you can even reassign
   "print = pprint.pprint" for use within a scope).  *indent*,
   *width*, *depth*, *compact* and *sort_dicts* will be passed to the
   "PrettyPrinter" constructor as formatting parameters.

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

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

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

   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)

   Determine if *object* requires a recursive representation.

One more support function is also defined:

pprint.saferepr(object)

   Return a string representation of *object*, protected against
   recursive data structures.  If the representation of *object*
   exposes a recursive entry, the recursive reference will be
   represented as "<Recursion on typename with id=number>".  The
   representation is not otherwise formatted.

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


Objetos PrettyPrinter
=====================

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

To demonstrate several uses of the "pprint()" function and its
parameters, let's fetch information about a project from 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']

In its basic form, "pprint()" shows the whole object:

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

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

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

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