171 lines
6.0 KiB
TeX
171 lines
6.0 KiB
TeX
%% Author: Fred L. Drake, Jr. <fdrake@acm.org>
|
|
|
|
\section{Standard Module \sectcode{pprint}}
|
|
\stmodindex{pprint}
|
|
\label{module-pprint}
|
|
|
|
The \code{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 builtin
|
|
objects which are not representable as Python constants.
|
|
|
|
The formatted representation keeps objects on a single line if it can,
|
|
and breaks them onto multiple lines if they don't fit within the
|
|
allowed width. Construct PrettyPrinter objects explicitly if you need
|
|
to adjust the width constraint.
|
|
|
|
The \code{pprint} module defines one class:
|
|
|
|
\setindexsubitem{(in module pprint)}
|
|
|
|
% First the implementation class:
|
|
|
|
\begin{funcdesc}{PrettyPrinter}{...}
|
|
Construct a PrettyPrinter instance. This constructor understands
|
|
several keyword parameters. An output stream may be set using the
|
|
\var{stream} keyword; the only method used on the stream object is the
|
|
file protocol's \code{write()} method. If not specified, the
|
|
PrettyPrinter adopts \code{sys.stdout}. Three additional parameters
|
|
may be used to control the formatted representation. The keywords are
|
|
\var{indent}, \var{depth}, and \var{width}. The amount of indentation
|
|
added for each recursive level is specified by \var{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 \var{depth}; if the data structure being
|
|
printed is too deep, the next contained level is replaced by
|
|
\samp{...}. By default, there is no constraint on the depth of the
|
|
objects being formatted. The desired output width is constrained
|
|
using the \var{width} parameter; the default is eighty characters. If
|
|
a structure cannot be formatted within the constrained width, a best
|
|
effort will be made.
|
|
|
|
\begin{verbatim}
|
|
>>> import pprint, sys
|
|
>>> stuff = sys.path[:]
|
|
>>> stuff.insert(0, stuff[:])
|
|
>>> pp = pprint.PrettyPrinter(indent=4)
|
|
>>> pp.pprint(stuff)
|
|
[ [ '',
|
|
'/usr/local/lib/python1.5',
|
|
'/usr/local/lib/python1.5/test',
|
|
'/usr/local/lib/python1.5/sunos5',
|
|
'/usr/local/lib/python1.5/sharedmodules',
|
|
'/usr/local/lib/python1.5/tkinter'],
|
|
'',
|
|
'/usr/local/lib/python1.5',
|
|
'/usr/local/lib/python1.5/test',
|
|
'/usr/local/lib/python1.5/sunos5',
|
|
'/usr/local/lib/python1.5/sharedmodules',
|
|
'/usr/local/lib/python1.5/tkinter']
|
|
>>>
|
|
>>> import parser
|
|
>>> tup = parser.ast2tuple(
|
|
... parser.suite(open('pprint.py').read()))[1][1][1]
|
|
>>> pp = pprint.PrettyPrinter(depth=6)
|
|
>>> pp.pprint(tup)
|
|
(266, (267, (307, (287, (288, (...))))))
|
|
\end{verbatim}
|
|
\end{funcdesc}
|
|
|
|
|
|
% Now the derivative functions:
|
|
|
|
The PrettyPrinter class supports several derivative functions:
|
|
|
|
\begin{funcdesc}{pformat}{object}
|
|
Return the formatted representation of \var{object} as a string. The
|
|
default parameters for formatting are used.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pprint}{object\optional{, stream}}
|
|
Prints the formatted representation of \var{object} on \var{stream},
|
|
followed by a newline. If \var{stream} is omitted, \code{sys.stdout}
|
|
is used. This may be used in the interactive interpreter instead of a
|
|
\code{print} command for inspecting values. The default parameters
|
|
for formatting are used.
|
|
|
|
\begin{verbatim}
|
|
>>> stuff = sys.path[:]
|
|
>>> stuff.insert(0, stuff)
|
|
>>> pprint.pprint(stuff)
|
|
[<Recursion on list with id=869440>,
|
|
'',
|
|
'/usr/local/lib/python1.5',
|
|
'/usr/local/lib/python1.5/test',
|
|
'/usr/local/lib/python1.5/sunos5',
|
|
'/usr/local/lib/python1.5/sharedmodules',
|
|
'/usr/local/lib/python1.5/tkinter']
|
|
\end{verbatim}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isreadable}{object}
|
|
Determine if the formatted representation of \var{object} is
|
|
``readable,'' or can be used to reconstruct the value using
|
|
\code{eval()}. Note that this returns false for recursive objects.
|
|
|
|
\begin{verbatim}
|
|
>>> pprint.isreadable(stuff)
|
|
0
|
|
\end{verbatim}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isrecursive}{object}
|
|
Determine if \var{object} requires a recursive representation.
|
|
\end{funcdesc}
|
|
|
|
|
|
One more support function is also defined:
|
|
|
|
\begin{funcdesc}{saferepr}{object}
|
|
Return a string representation of \var{object}, protected against
|
|
recursive data structures. If the representation of \var{object}
|
|
exposes a recursive entry, the recursive reference will be represented
|
|
as \samp{<Recursion on \var{typename} with id=\var{number}>}. The
|
|
representation is not otherwise formatted.
|
|
|
|
\begin{verbatim}
|
|
>>> pprint.saferepr(stuff)
|
|
"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.4', '/usr/loca
|
|
l/lib/python1.4/test', '/usr/local/lib/python1.4/sunos5', '/usr/local/lib/python
|
|
1.4/sharedmodules', '/usr/local/lib/python1.4/tkinter']"
|
|
\end{verbatim}
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{PrettyPrinter Objects}
|
|
|
|
PrettyPrinter instances (returned by \code{PrettyPrinter()} above)
|
|
have the following methods.
|
|
|
|
\setindexsubitem{(PrettyPrinter method)}
|
|
|
|
\begin{funcdesc}{pformat}{object}
|
|
Return the formatted representation of \var{object}. This takes into
|
|
account the options passed to the PrettyPrinter constructor.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pprint}{object}
|
|
Print the formatted representation of \var{object} on the configured
|
|
stream, followed by a newline.
|
|
\end{funcdesc}
|
|
|
|
The following methods provide the implementations for the
|
|
corresponding functions of the same names. Using these methods on an
|
|
instance is slightly more efficient since new PrettyPrinter objects
|
|
don't need to be created.
|
|
|
|
\begin{funcdesc}{isreadable}{object}
|
|
Determine if the formatted representation of the object is
|
|
``readable,'' or can be used to reconstruct the value using
|
|
\code{eval()}. Note that this returns false for recursive objects.
|
|
If the \var{depth} parameter of the PrettyPrinter is set and the
|
|
object is deeper than allowed, this returns false.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isrecursive}{object}
|
|
Determine if the object requires a recursive representation.
|
|
\end{funcdesc}
|