Doc/lib/libpprint.tex

   1 \section{\module{pprint} ---
   2          Data pretty printer}
   3
   4 \declaremodule{standard}{pprint}
   5 \modulesynopsis{Data pretty printer.}
   6 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   7 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   8
   9
  10 The \module{pprint} module provides a capability to ``pretty-print''
  11 arbitrary Python data structures in a form which can be used as input
  12 to the interpreter.  If the formatted structures include objects which
  13 are not fundamental Python types, the representation may not be
  14 loadable.  This may be the case if objects such as files, sockets,
  15 classes, or instances are included, as well as many other builtin
  16 objects which are not representable as Python constants.
  17
  18 The formatted representation keeps objects on a single line if it can,
  19 and breaks them onto multiple lines if they don't fit within the
  20 allowed width.  Construct \class{PrettyPrinter} objects explicitly if
  21 you need to adjust the width constraint.
  22
  23 The \module{pprint} module defines one class:
  24
  25
  26 % First the implementation class:
  27
  28 \begin{classdesc}{PrettyPrinter}{...}
  29 Construct a \class{PrettyPrinter} instance.  This constructor
  30 understands several keyword parameters.  An output stream may be set
  31 using the \var{stream} keyword; the only method used on the stream
  32 object is the file protocol's \method{write()} method.  If not
  33 specified, the \class{PrettyPrinter} adopts \code{sys.stdout}.  Three
  34 additional parameters may be used to control the formatted
  35 representation.  The keywords are \var{indent}, \var{depth}, and
  36 \var{width}.  The amount of indentation added for each recursive level
  37 is specified by \var{indent}; the default is one.  Other values can
  38 cause output to look a little odd, but can make nesting easier to
  39 spot.  The number of levels which may be printed is controlled by
  40 \var{depth}; if the data structure being printed is too deep, the next
  41 contained level is replaced by \samp{...}.  By default, there is no
  42 constraint on the depth of the objects being formatted.  The desired
  43 output width is constrained using the \var{width} parameter; the
  44 default is eighty characters.  If a structure cannot be formatted
  45 within the constrained width, a best effort will be made.
  46
  47 \begin{verbatim}
  48 >>> import pprint, sys
  49 >>> stuff = sys.path[:]
  50 >>> stuff.insert(0, stuff[:])
  51 >>> pp = pprint.PrettyPrinter(indent=4)
  52 >>> pp.pprint(stuff)
  53 [   [   '',
  54         '/usr/local/lib/python1.5',
  55         '/usr/local/lib/python1.5/test',
  56         '/usr/local/lib/python1.5/sunos5',
  57         '/usr/local/lib/python1.5/sharedmodules',
  58         '/usr/local/lib/python1.5/tkinter'],
  59     '',
  60     '/usr/local/lib/python1.5',
  61     '/usr/local/lib/python1.5/test',
  62     '/usr/local/lib/python1.5/sunos5',
  63     '/usr/local/lib/python1.5/sharedmodules',
  64     '/usr/local/lib/python1.5/tkinter']
  65 >>>
  66 >>> import parser
  67 >>> tup = parser.ast2tuple(
  68 ...     parser.suite(open('pprint.py').read()))[1][1][1]
  69 >>> pp = pprint.PrettyPrinter(depth=6)
  70 >>> pp.pprint(tup)
  71 (266, (267, (307, (287, (288, (...))))))
  72 \end{verbatim}
  73 \end{classdesc}
  74
  75
  76 % Now the derivative functions:
  77
  78 The \class{PrettyPrinter} class supports several derivative functions:
  79
  80 \begin{funcdesc}{pformat}{object}
  81 Return the formatted representation of \var{object} as a string.  The
  82 default parameters for formatting are used.
  83 \end{funcdesc}
  84
  85 \begin{funcdesc}{pprint}{object\optional{, stream}}
  86 Prints the formatted representation of \var{object} on \var{stream},
  87 followed by a newline.  If \var{stream} is omitted, \code{sys.stdout}
  88 is used.  This may be used in the interactive interpreter instead of a
  89 \keyword{print} statement for inspecting values.  The default
  90 parameters for formatting are used.
  91
  92 \begin{verbatim}
  93 >>> stuff = sys.path[:]
  94 >>> stuff.insert(0, stuff)
  95 >>> pprint.pprint(stuff)
  96 [<Recursion on list with id=869440>,
  97  '',
  98  '/usr/local/lib/python1.5',
  99  '/usr/local/lib/python1.5/test',
 100  '/usr/local/lib/python1.5/sunos5',
 101  '/usr/local/lib/python1.5/sharedmodules',
 102  '/usr/local/lib/python1.5/tkinter']
 103 \end{verbatim}
 104 \end{funcdesc}
 105
 106 \begin{funcdesc}{isreadable}{object}
 107 Determine if the formatted representation of \var{object} is
 108 ``readable,'' or can be used to reconstruct the value using
 109 \function{eval()}\bifuncindex{eval}.  This always returns false for
 110 recursive objects.
 111
 112 \begin{verbatim}
 113 >>> pprint.isreadable(stuff)
 114 0
 115 \end{verbatim}
 116 \end{funcdesc}
 117
 118 \begin{funcdesc}{isrecursive}{object}
 119 Determine if \var{object} requires a recursive representation.
 120 \end{funcdesc}
 121
 122
 123 One more support function is also defined:
 124
 125 \begin{funcdesc}{saferepr}{object}
 126 Return a string representation of \var{object}, protected against
 127 recursive data structures.  If the representation of \var{object}
 128 exposes a recursive entry, the recursive reference will be represented
 129 as \samp{<Recursion on \var{typename} with id=\var{number}>}.  The
 130 representation is not otherwise formatted.
 131 \end{funcdesc}
 132
 133 % This example is outside the {funcdesc} to keep it from running over
 134 % the right margin.
 135 \begin{verbatim}
 136 >>> pprint.saferepr(stuff)
 137 "[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca
 138 l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python
 139 1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']"
 140 \end{verbatim}
 141
 142
 143 \subsection{PrettyPrinter Objects}
 144 \label{PrettyPrinter Objects}
 145
 146 \class{PrettyPrinter} instances have the following methods:
 147
 148
 149 \begin{methoddesc}{pformat}{object}
 150 Return the formatted representation of \var{object}.  This takes into
 151 Account the options passed to the \class{PrettyPrinter} constructor.
 152 \end{methoddesc}
 153
 154 \begin{methoddesc}{pprint}{object}
 155 Print the formatted representation of \var{object} on the configured
 156 stream, followed by a newline.
 157 \end{methoddesc}
 158
 159 The following methods provide the implementations for the
 160 corresponding functions of the same names.  Using these methods on an
 161 instance is slightly more efficient since new \class{PrettyPrinter}
 162 objects don't need to be created.
 163
 164 \begin{methoddesc}{isreadable}{object}
 165 Determine if the formatted representation of the object is
 166 ``readable,'' or can be used to reconstruct the value using
 167 \function{eval()}\bifuncindex{eval}.  Note that this returns false for
 168 recursive objects.  If the \var{depth} parameter of the
 169 \class{PrettyPrinter} is set and the object is deeper than allowed,
 170 this returns false.
 171 \end{methoddesc}
 172
 173 \begin{methoddesc}{isrecursive}{object}
 174 Determine if the object requires a recursive representation.
 175 \end{methoddesc}