8.18. pprint — L’affichage élégant de données

Code source : Lib/pprint.py

The pprint module provides a capability to « pretty-print » arbitrary Python data structures in a form which can be used as input to the interpreter. If the formatted structures include objects which are not fundamental Python types, the representation may not be loadable. This may be the case if objects such as files, sockets, classes, or instances are included, as well as many other built-in objects which are not representable as Python constants.

L’affichage formaté affiche tant que possible les objets sur une seule ligne, et les sépare sur plusieurs lignes s’ils dépassent la largeur autorisée par l’interpréteur. Créez explicitement des objets PrettyPrinter si vous avez besoin de modifier les limites de largeur.

Modifié dans la version 2.5: Dictionaries are sorted by key before the display is computed; before 2.5, a dictionary was sorted only if its display required more than one line, although that wasn’t documented.

Modifié dans la version 2.6: Added support for set and frozenset.

Le module pprint définit une seule classe :

class pprint.PrettyPrinter(indent=1, width=80, depth=None, stream=None)

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. Three additional parameters may be used to control the formatted representation. The keywords are indent, depth, and width. 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.

>>> 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']
>>> 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 PrettyPrinter class supports several derivative functions:

pprint.pformat(object, indent=1, width=80, depth=None)

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

Modifié dans la version 2.4: The parameters indent, width and depth were added.

pprint.pprint(object, stream=None, indent=1, width=80, depth=None)

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 a print statement for inspecting values. indent, width and depth will be passed to the PrettyPrinter constructor as formatting parameters.

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

Modifié dans la version 2.4: The parameters indent, width and depth were added.

pprint.isreadable(object)

Détermine si la représentation formatée de object est « lisible », ou s’il peut être utilisé pour recomposer sa valeur en utilisant la fonction eval(). Cela renvoie toujours False pour les objets récursifs.

>>> pprint.isreadable(stuff)
False
pprint.isrecursive(object)

Détermine si object requiert une représentation récursive.

Une dernière fonction de support est définie ainsi :

pprint.saferepr(object)

Renvoie une représentation de object sous forme de chaîne de caractère, celle-ci est protégée contre les structures de données récursives. Si la représentation de object présente une entrée récursive, celle-ci sera représentée telle que <Recursion on typename with id=number>. Par ailleurs, la représentation de l’objet n’est pas formatée.

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

8.18.1. Les Objets PrettyPrinter

Les instances de la classe PrettyPrinter ont les méthodes suivantes :

PrettyPrinter.pformat(object)

Renvoie la représentation formatée de object. Cela prend en compte les options passées au constructeur de la classe PrettyPrinter.

PrettyPrinter.pprint(object)

Affiche sur le flux configuré la représentation formatée de object, suivie d’une fin de ligne.

Les méthodes suivantes fournissent les implémentations pour les fonctions correspondantes de mêmes noms. L’utilisation de ces méthodes sur une instance est légèrement plus efficace, car les nouveaux objets PrettyPrinter n’ont pas besoin d’être créés.

PrettyPrinter.isreadable(object)

Détermine si la représentation formatée de object est « lisible », ou si elle peut être utilisée pour recomposer sa valeur en utilisant la fonction eval(). Cela renvoie toujours False pour les objets récursifs. Si le paramètre depth de la classe PrettyPrinter est initialisé et que l’objet est plus « profond » que permis, cela renvoie False.

PrettyPrinter.isrecursive(object)

Détermine si l’objet nécessite une représentation récursive.

Cette méthode est fournie sous forme de point d’entrée ou méthode (à déclenchement) automatique (hook en anglais) pour permettre aux sous-classes de modifier la façon dont les objets sont convertis en chaînes. L’implémentation par défaut est celle de la fonction saferepr().

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

Renvoie trois valeurs : la version formatée de object sous forme de chaîne de caractères, une option indiquant si le résultat est « lisible », et une option indiquant si une récursion a été détectée. Le premier argument est l’objet à représenter. Le deuxième est un dictionnaire qui contient l”id() des objets (conteneurs directs ou indirects de objet qui affectent sa représentation) qui font partie du contexte de représentation courant tel que les clés; si un objet doit être représenté, mais l’a déjà été dans ce contexte, le troisième argument renvoie True. Des appels récursifs à la méthode format() doivent ajouter des entrés additionnelles aux conteneurs de ce dictionnaire. Le troisième argument maxlevels, donne la limite maximale de récursivité; la valeur par défaut est 0. Cet argument doit être passé non modifié pour des appels non récursifs. Le quatrième argument, level, donne le niveau de récursivité courant; les appels récursifs doivent être passés à une valeur inférieure à celle de l’appel courant.

Nouveau dans la version 2.3.

8.18.2. pprint Example

This example demonstrates several uses of the pprint() function and its parameters.

>>> import pprint
>>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',
... ('parrot', ('fresh fruit',))))))))
>>> stuff = ['a' * 10, tup, ['a' * 30, 'b' * 30], ['c' * 20, 'd' * 20]]
>>> pprint.pprint(stuff)
['aaaaaaaaaa',
 ('spam',
  ('eggs',
   ('lumberjack',
    ('knights', ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
>>> pprint.pprint(stuff, depth=3)
['aaaaaaaaaa',
 ('spam', ('eggs', (...))),
 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]
>>> pprint.pprint(stuff, width=60)
['aaaaaaaaaa',
 ('spam',
  ('eggs',
   ('lumberjack',
    ('knights',
     ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),
 ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
  'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],
 ['cccccccccccccccccccc', 'dddddddddddddddddddd']]