diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libpprint.tex | 147 | ||||
| -rw-r--r-- | Doc/libpprint.tex | 147 |
2 files changed, 164 insertions, 130 deletions
diff --git a/Doc/lib/libpprint.tex b/Doc/lib/libpprint.tex index a602482..aabc8c7 100644 --- a/Doc/lib/libpprint.tex +++ b/Doc/lib/libpprint.tex @@ -12,46 +12,15 @@ 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. +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 the following functions: +The \code{pprint} module defines one class: \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: +% First the implementation class: \begin{funcdesc}{PrettyPrinter}{...} Construct a PrettyPrinter instance. This constructor understands @@ -71,42 +40,25 @@ 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 +>>> import pprint, sys >>> 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:] +>>> stuff.insert(0, stuff[:]) >>> 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.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.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.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( @@ -115,6 +67,71 @@ Example: >>> 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} diff --git a/Doc/libpprint.tex b/Doc/libpprint.tex index a602482..aabc8c7 100644 --- a/Doc/libpprint.tex +++ b/Doc/libpprint.tex @@ -12,46 +12,15 @@ 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. +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 the following functions: +The \code{pprint} module defines one class: \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: +% First the implementation class: \begin{funcdesc}{PrettyPrinter}{...} Construct a PrettyPrinter instance. This constructor understands @@ -71,42 +40,25 @@ 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 +>>> import pprint, sys >>> 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:] +>>> stuff.insert(0, stuff[:]) >>> 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.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.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.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( @@ -115,6 +67,71 @@ Example: >>> 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} |