diff options
| -rw-r--r-- | Doc/lib/libpprint.tex | 152 | ||||
| -rw-r--r-- | Doc/libpprint.tex | 152 |
2 files changed, 304 insertions, 0 deletions
diff --git a/Doc/lib/libpprint.tex b/Doc/lib/libpprint.tex new file mode 100644 index 0000000..a602482 --- /dev/null +++ b/Doc/lib/libpprint.tex @@ -0,0 +1,152 @@ +%% Author: Fred L. Drake, Jr. <fdrake@acm.org> + +\section{Standard module \sectcode{pprint}} +\stmodindex{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 out onto multiple lines if they won't fit within the +width allowed width. Construct PrettyPrinter objects explicitly if +you need to adjust the width constraint. + +The \code{pprint} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module pprint)} + +\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. +\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. +\end{funcdesc} + +\begin{funcdesc}{isrecursive}{object} +Determine if \var{object} requires a recursive representation. +\end{funcdesc} + +\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}$>$}. +\end{funcdesc} + + +% Now for 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. +\end{funcdesc} + + +% Guido marked this as a good spot for an example in the template, +% but I think this needs a better location in this module. Not sure where. + +Example: + +\begin{verbatim} +>>> import pprint +>>> stuff = sys.path[:] +>>> stuff.insert(0, stuff) +>>> pprint.pprint(stuff) +[<Recursion on list with id=869440>, + '', + '/usr/local/lib/python1.4', + '/usr/local/lib/python1.4/test', + '/usr/local/lib/python1.4/sunos5', + '/usr/local/lib/python1.4/sharedmodules', + '/usr/local/lib/python1.4/tkinter'] +>>> +>>> stuff[0] = stuff[1:] +>>> pp = pprint.PrettyPrinter(indent=4) +>>> pp.pprint(stuff) +[ [ '', + '/usr/local/lib/python1.4', + '/usr/local/lib/python1.4/test', + '/usr/local/lib/python1.4/sunos5', + '/usr/local/lib/python1.4/sharedmodules', + '/usr/local/lib/python1.4/tkinter'], + '', + '/usr/local/lib/python1.4', + '/usr/local/lib/python1.4/test', + '/usr/local/lib/python1.4/sunos5', + '/usr/local/lib/python1.4/sharedmodules', + '/usr/local/lib/python1.4/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} + + +\subsection{PrettyPrinter Objects} + +PrettyPrinter instances (returned by \code{PrettyPrinter()} above) +have the following methods. + +\renewcommand{\indexsubitem}{(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} diff --git a/Doc/libpprint.tex b/Doc/libpprint.tex new file mode 100644 index 0000000..a602482 --- /dev/null +++ b/Doc/libpprint.tex @@ -0,0 +1,152 @@ +%% Author: Fred L. Drake, Jr. <fdrake@acm.org> + +\section{Standard module \sectcode{pprint}} +\stmodindex{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 out onto multiple lines if they won't fit within the +width allowed width. Construct PrettyPrinter objects explicitly if +you need to adjust the width constraint. + +The \code{pprint} module defines the following functions: + +\renewcommand{\indexsubitem}{(in module pprint)} + +\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. +\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. +\end{funcdesc} + +\begin{funcdesc}{isrecursive}{object} +Determine if \var{object} requires a recursive representation. +\end{funcdesc} + +\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}$>$}. +\end{funcdesc} + + +% Now for 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. +\end{funcdesc} + + +% Guido marked this as a good spot for an example in the template, +% but I think this needs a better location in this module. Not sure where. + +Example: + +\begin{verbatim} +>>> import pprint +>>> stuff = sys.path[:] +>>> stuff.insert(0, stuff) +>>> pprint.pprint(stuff) +[<Recursion on list with id=869440>, + '', + '/usr/local/lib/python1.4', + '/usr/local/lib/python1.4/test', + '/usr/local/lib/python1.4/sunos5', + '/usr/local/lib/python1.4/sharedmodules', + '/usr/local/lib/python1.4/tkinter'] +>>> +>>> stuff[0] = stuff[1:] +>>> pp = pprint.PrettyPrinter(indent=4) +>>> pp.pprint(stuff) +[ [ '', + '/usr/local/lib/python1.4', + '/usr/local/lib/python1.4/test', + '/usr/local/lib/python1.4/sunos5', + '/usr/local/lib/python1.4/sharedmodules', + '/usr/local/lib/python1.4/tkinter'], + '', + '/usr/local/lib/python1.4', + '/usr/local/lib/python1.4/test', + '/usr/local/lib/python1.4/sunos5', + '/usr/local/lib/python1.4/sharedmodules', + '/usr/local/lib/python1.4/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} + + +\subsection{PrettyPrinter Objects} + +PrettyPrinter instances (returned by \code{PrettyPrinter()} above) +have the following methods. + +\renewcommand{\indexsubitem}{(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} |