1 

     2 :mod:`pprint` --- Data pretty printer

     3 =====================================

     4 

     5 .. module:: pprint

     6    :synopsis: Data pretty printer.

     7 .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

     8 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

     9 

    10 

    11 The :mod:`pprint` module provides a capability to "pretty-print" arbitrary

    12 Python data structures in a form which can be used as input to the interpreter.

    13 If the formatted structures include objects which are not fundamental Python

    14 types, the representation may not be loadable.  This may be the case if objects

    15 such as files, sockets, classes, or instances are included, as well as many

    16 other builtin objects which are not representable as Python constants.

    17 

    18 The formatted representation keeps objects on a single line if it can, and

    19 breaks them onto multiple lines if they don't fit within the allowed width.

    20 Construct :class:`PrettyPrinter` objects explicitly if you need to adjust the

    21 width constraint.

    22 

    23 .. versionchanged:: 2.5

    24    Dictionaries are sorted by key before the display is computed; before 2.5, a

    25    dictionary was sorted only if its display required more than one line, although

    26    that wasn't documented.

    27 

    28 .. versionchanged:: 2.6

    29    Added support for :class:`set` and :class:`frozenset`.

    30 

    31 The :mod:`pprint` module defines one class:

    32 

    33 .. First the implementation class:

    34 

    35 

    36 .. class:: PrettyPrinter(...)

    37 

    38    Construct a :class:`PrettyPrinter` instance.  This constructor understands

    39    several keyword parameters.  An output stream may be set using the *stream*

    40    keyword; the only method used on the stream object is the file protocol's

    41    :meth:`write` method.  If not specified, the :class:`PrettyPrinter` adopts

    42    ``sys.stdout``.  Three additional parameters may be used to control the

    43    formatted representation.  The keywords are *indent*, *depth*, and *width*.  The

    44    amount of indentation added for each recursive level is specified by *indent*;

    45    the default is one.  Other values can cause output to look a little odd, but can

    46    make nesting easier to spot.  The number of levels which may be printed is

    47    controlled by *depth*; if the data structure being printed is too deep, the next

    48    contained level is replaced by ``...``.  By default, there is no constraint on

    49    the depth of the objects being formatted.  The desired output width is

    50    constrained using the *width* parameter; the default is 80 characters.  If a

    51    structure cannot be formatted within the constrained width, a best effort will

    52    be made.

    53 

    54       >>> import pprint

    55       >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']

    56       >>> stuff.insert(0, stuff[:])

    57       >>> pp = pprint.PrettyPrinter(indent=4)

    58       >>> pp.pprint(stuff)

    59       [   ['spam', 'eggs', 'lumberjack', 'knights', 'ni'],

    60           'spam',

    61           'eggs',

    62           'lumberjack',

    63           'knights',

    64           'ni']

    65       >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',

    66       ... ('parrot', ('fresh fruit',))))))))

    67       >>> pp = pprint.PrettyPrinter(depth=6)

    68       >>> pp.pprint(tup)

    69       ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...)))))))

    70 

    71 The :class:`PrettyPrinter` class supports several derivative functions:

    72 

    73 .. Now the derivative functions:

    74 

    75 .. function:: pformat(object[, indent[, width[, depth]]])

    76 

    77    Return the formatted representation of *object* as a string.  *indent*, *width*

    78    and *depth* will be passed to the :class:`PrettyPrinter` constructor as

    79    formatting parameters.

    80 

    81    .. versionchanged:: 2.4

    82       The parameters *indent*, *width* and *depth* were added.

    83 

    84 

    85 .. function:: pprint(object[, stream[, indent[, width[, depth]]]])

    86 

    87    Prints the formatted representation of *object* on *stream*, followed by a

    88    newline.  If *stream* is omitted, ``sys.stdout`` is used.  This may be used in

    89    the interactive interpreter instead of a :keyword:`print` statement for

    90    inspecting values.    *indent*, *width* and *depth* will be passed to the

    91    :class:`PrettyPrinter` constructor as formatting parameters.

    92 

    93       >>> import pprint

    94       >>> stuff = ['spam', 'eggs', 'lumberjack', 'knights', 'ni']

    95       >>> stuff.insert(0, stuff)

    96       >>> pprint.pprint(stuff)

    97       [<Recursion on list with id=...>,

    98        'spam',

    99        'eggs',

   100        'lumberjack',

   101        'knights',

   102        'ni']

   103 

   104    .. versionchanged:: 2.4

   105       The parameters *indent*, *width* and *depth* were added.

   106 

   107 

   108 .. function:: isreadable(object)

   109 

   110    .. index:: builtin: eval

   111 

   112    Determine if the formatted representation of *object* is "readable," or can be

   113    used to reconstruct the value using :func:`eval`.  This always returns ``False``

   114    for recursive objects.

   115 

   116       >>> pprint.isreadable(stuff)

   117       False

   118 

   119 

   120 .. function:: isrecursive(object)

   121 

   122    Determine if *object* requires a recursive representation.

   123 

   124 

   125 One more support function is also defined:

   126 

   127 .. function:: saferepr(object)

   128 

   129    Return a string representation of *object*, protected against recursive data

   130    structures.  If the representation of *object* exposes a recursive entry, the

   131    recursive reference will be represented as ``<Recursion on typename with

   132    id=number>``.  The representation is not otherwise formatted.

   133 

   134    >>> pprint.saferepr(stuff)

   135    "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"

   136 

   137 

   138 .. _prettyprinter-objects:

   139 

   140 PrettyPrinter Objects

   141 ---------------------

   142 

   143 :class:`PrettyPrinter` instances have the following methods:

   144 

   145 

   146 .. method:: PrettyPrinter.pformat(object)

   147 

   148    Return the formatted representation of *object*.  This takes into account the

   149    options passed to the :class:`PrettyPrinter` constructor.

   150 

   151 

   152 .. method:: PrettyPrinter.pprint(object)

   153 

   154    Print the formatted representation of *object* on the configured stream,

   155    followed by a newline.

   156 

   157 The following methods provide the implementations for the corresponding

   158 functions of the same names.  Using these methods on an instance is slightly

   159 more efficient since new :class:`PrettyPrinter` objects don't need to be

   160 created.

   161 

   162 

   163 .. method:: PrettyPrinter.isreadable(object)

   164 

   165    .. index:: builtin: eval

   166 

   167    Determine if the formatted representation of the object is "readable," or can be

   168    used to reconstruct the value using :func:`eval`.  Note that this returns

   169    ``False`` for recursive objects.  If the *depth* parameter of the

   170    :class:`PrettyPrinter` is set and the object is deeper than allowed, this

   171    returns ``False``.

   172 

   173 

   174 .. method:: PrettyPrinter.isrecursive(object)

   175 

   176    Determine if the object requires a recursive representation.

   177 

   178 This method is provided as a hook to allow subclasses to modify the way objects

   179 are converted to strings.  The default implementation uses the internals of the

   180 :func:`saferepr` implementation.

   181 

   182 

   183 .. method:: PrettyPrinter.format(object, context, maxlevels, level)

   184 

   185    Returns three values: the formatted version of *object* as a string, a flag

   186    indicating whether the result is readable, and a flag indicating whether

   187    recursion was detected.  The first argument is the object to be presented.  The

   188    second is a dictionary which contains the :func:`id` of objects that are part of

   189    the current presentation context (direct and indirect containers for *object*

   190    that are affecting the presentation) as the keys; if an object needs to be

   191    presented which is already represented in *context*, the third return value

   192    should be ``True``.  Recursive calls to the :meth:`format` method should add

   193    additional entries for containers to this dictionary.  The third argument,

   194    *maxlevels*, gives the requested limit to recursion; this will be ``0`` if there

   195    is no requested limit.  This argument should be passed unmodified to recursive

   196    calls. The fourth argument, *level*, gives the current level; recursive calls

   197    should be passed a value less than that of the current call.

   198 

   199    .. versionadded:: 2.3

   200 

   201 .. _pprint-example:

   202 

   203 pprint Example

   204 --------------

   205 

   206 This example demonstrates several uses of the :func:`pprint` function and its parameters.

   207 

   208    >>> import pprint

   209    >>> tup = ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead',

   210    ... ('parrot', ('fresh fruit',))))))))

   211    >>> stuff = ['a' * 10, tup, ['a' * 30, 'b' * 30], ['c' * 20, 'd' * 20]]

   212    >>> pprint.pprint(stuff)

   213    ['aaaaaaaaaa',

   214     ('spam',

   215      ('eggs',

   216       ('lumberjack',

   217        ('knights', ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),

   218     ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],

   219     ['cccccccccccccccccccc', 'dddddddddddddddddddd']]

   220    >>> pprint.pprint(stuff, depth=3)

   221    ['aaaaaaaaaa',

   222     ('spam', ('eggs', (...))),

   223     ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],

   224     ['cccccccccccccccccccc', 'dddddddddddddddddddd']]

   225    >>> pprint.pprint(stuff, width=60)

   226    ['aaaaaaaaaa',

   227     ('spam',

   228      ('eggs',

   229       ('lumberjack',

   230        ('knights',

   231         ('ni', ('dead', ('parrot', ('fresh fruit',)))))))),

   232     ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',

   233      'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'],

   234     ['cccccccccccccccccccc', 'dddddddddddddddddddd']]

   235