diff options
author | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 +0000 |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2007-08-15 14:27:07 +0000 |
commit | 739c01d47b9118d04e5722333f0e6b4d0c8bdd9e (patch) | |
tree | f82b450d291927fc1758b96d981aa0610947b529 /Doc/lib/libpprint.tex | |
parent | 2d1649094402ef393ea2b128ba2c08c3937e6b93 (diff) | |
download | cpython-git-739c01d47b9118d04e5722333f0e6b4d0c8bdd9e.tar.gz |
Delete the LaTeX doc tree.
Diffstat (limited to 'Doc/lib/libpprint.tex')
-rw-r--r-- | Doc/lib/libpprint.tex | 210 |
1 files changed, 0 insertions, 210 deletions
diff --git a/Doc/lib/libpprint.tex b/Doc/lib/libpprint.tex deleted file mode 100644 index ce35b44b6c..0000000000 --- a/Doc/lib/libpprint.tex +++ /dev/null @@ -1,210 +0,0 @@ -\section{\module{pprint} --- - Data pretty printer} - -\declaremodule{standard}{pprint} -\modulesynopsis{Data pretty printer.} -\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} -\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} - - -The \module{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 \class{PrettyPrinter} objects explicitly if -you need to adjust the width constraint. - -\versionchanged[Dictionaries are sorted by key before the display is -computed; before 2.5, a dictionary was sorted only if its display -required more than one line, although that wasn't documented]{2.5} - -The \module{pprint} module defines one class: - - -% First the implementation class: - -\begin{classdesc}{PrettyPrinter}{...} -Construct a \class{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 \method{write()} method. If not -specified, the \class{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{classdesc} - - -% Now the derivative functions: - -The \class{PrettyPrinter} class supports several derivative functions: - -\begin{funcdesc}{pformat}{object\optional{, indent\optional{, -width\optional{, depth}}}} -Return the formatted representation of \var{object} as a string. \var{indent}, -\var{width} and \var{depth} will be passed to the \class{PrettyPrinter} -constructor as formatting parameters. -\versionchanged[The parameters \var{indent}, \var{width} and \var{depth} -were added]{2.4} -\end{funcdesc} - -\begin{funcdesc}{pprint}{object\optional{, stream\optional{, -indent\optional{, width\optional{, depth}}}}} -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 -\keyword{print} statement for inspecting values. \var{indent}, -\var{width} and \var{depth} will be passed to the \class{PrettyPrinter} -constructor as formatting parameters. - -\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} -\versionchanged[The parameters \var{indent}, \var{width} and \var{depth} -were added]{2.4} -\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 -\function{eval()}\bifuncindex{eval}. This always returns \code{False} for -recursive objects. - -\begin{verbatim} ->>> pprint.isreadable(stuff) -False -\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. -\end{funcdesc} - -% This example is outside the {funcdesc} to keep it from running over -% the right margin. -\begin{verbatim} ->>> pprint.saferepr(stuff) -"[<Recursion on list with id=682968>, '', '/usr/local/lib/python1.5', '/usr/loca -l/lib/python1.5/test', '/usr/local/lib/python1.5/sunos5', '/usr/local/lib/python -1.5/sharedmodules', '/usr/local/lib/python1.5/tkinter']" -\end{verbatim} - - -\subsection{PrettyPrinter Objects} -\label{PrettyPrinter Objects} - -\class{PrettyPrinter} instances have the following methods: - - -\begin{methoddesc}[PrettyPrinter]{pformat}{object} -Return the formatted representation of \var{object}. This takes into -account the options passed to the \class{PrettyPrinter} constructor. -\end{methoddesc} - -\begin{methoddesc}[PrettyPrinter]{pprint}{object} -Print the formatted representation of \var{object} on the configured -stream, followed by a newline. -\end{methoddesc} - -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 \class{PrettyPrinter} -objects don't need to be created. - -\begin{methoddesc}[PrettyPrinter]{isreadable}{object} -Determine if the formatted representation of the object is -``readable,'' or can be used to reconstruct the value using -\function{eval()}\bifuncindex{eval}. Note that this returns \code{False} for -recursive objects. If the \var{depth} parameter of the -\class{PrettyPrinter} is set and the object is deeper than allowed, -this returns \code{False}. -\end{methoddesc} - -\begin{methoddesc}[PrettyPrinter]{isrecursive}{object} -Determine if the object requires a recursive representation. -\end{methoddesc} - -This method is provided as a hook to allow subclasses to modify the -way objects are converted to strings. The default implementation uses -the internals of the \function{saferepr()} implementation. - -\begin{methoddesc}[PrettyPrinter]{format}{object, context, maxlevels, level} -Returns three values: the formatted version of \var{object} as a -string, a flag indicating whether the result is readable, and a flag -indicating whether recursion was detected. The first argument is the -object to be presented. The second is a dictionary which contains the -\function{id()} of objects that are part of the current presentation -context (direct and indirect containers for \var{object} that are -affecting the presentation) as the keys; if an object needs to be -presented which is already represented in \var{context}, the third -return value should be \code{True}. Recursive calls to the \method{format()} -method should add additional entries for containers to this -dictionary. The third argument, \var{maxlevels}, gives the requested -limit to recursion; this will be \code{0} if there is no requested -limit. This argument should be passed unmodified to recursive calls. -The fourth argument, \var{level}, gives the current level; recursive -calls should be passed a value less than that of the current call. -\versionadded{2.3} -\end{methoddesc} |