mirror of
https://github.com/python/cpython.git
synced 2025-11-01 10:45:30 +00:00
A couple of grammatical nits.
Re-sequenced the function descriptions so that the formatting is described before the assumption is made that the reader has a clue about the formatting. Moved examples to be closer to the functions being demonstrated. Added example of saferepr() result.
This commit is contained in:
Fred Drake
parent
ed57d7663e
commit
12d9eac0a2
2 changed files with 164 additions and 130 deletions
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue