mirror of https://github.com/python/cpython
134 lines
4.5 KiB
TeX
134 lines
4.5 KiB
TeX
\section{\module{repr} ---
|
|
Alternate \function{repr()} implementation}
|
|
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
\declaremodule{standard}{repr}
|
|
\modulesynopsis{Alternate \function{repr()} implementation with size limits.}
|
|
|
|
|
|
The \module{repr} module provides a means for producing object
|
|
representations with limits on the size of the resulting strings.
|
|
This is used in the Python debugger and may be useful in other
|
|
contexts as well.
|
|
|
|
This module provides a class, an instance, and a function:
|
|
|
|
|
|
\begin{classdesc}{Repr}{}
|
|
Class which provides formatting services useful in implementing
|
|
functions similar to the built-in \function{repr()}; size limits for
|
|
different object types are added to avoid the generation of
|
|
representations which are excessively long.
|
|
\end{classdesc}
|
|
|
|
|
|
\begin{datadesc}{aRepr}
|
|
This is an instance of \class{Repr} which is used to provide the
|
|
\function{repr()} function described below. Changing the attributes
|
|
of this object will affect the size limits used by \function{repr()}
|
|
and the Python debugger.
|
|
\end{datadesc}
|
|
|
|
|
|
\begin{funcdesc}{repr}{obj}
|
|
This is the \method{repr()} method of \code{aRepr}. It returns a
|
|
string similar to that returned by the built-in function of the same
|
|
name, but with limits on most sizes.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Repr Objects \label{Repr-objects}}
|
|
|
|
\class{Repr} instances provide several members which can be used to
|
|
provide size limits for the representations of different object types,
|
|
and methods which format specific object types.
|
|
|
|
|
|
\begin{memberdesc}{maxlevel}
|
|
Depth limit on the creation of recursive representations. The
|
|
default is \code{6}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{maxdict}
|
|
\memberline{maxlist}
|
|
\memberline{maxtuple}
|
|
\memberline{maxset}
|
|
\memberline{maxfrozenset}
|
|
\memberline{maxdeque}
|
|
\memberline{maxarray}
|
|
Limits on the number of entries represented for the named object
|
|
type. The default is \code{4} for \member{maxdict}, \code{5} for
|
|
\member{maxarray}, and \code{6} for the others.
|
|
\versionadded[\member{maxset}, \member{maxfrozenset},
|
|
and \member{set}]{2.4}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{maxlong}
|
|
Maximum number of characters in the representation for a long
|
|
integer. Digits are dropped from the middle. The default is
|
|
\code{40}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{maxstring}
|
|
Limit on the number of characters in the representation of the
|
|
string. Note that the ``normal'' representation of the string is
|
|
used as the character source: if escape sequences are needed in the
|
|
representation, these may be mangled when the representation is
|
|
shortened. The default is \code{30}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{maxother}
|
|
This limit is used to control the size of object types for which no
|
|
specific formatting method is available on the \class{Repr} object.
|
|
It is applied in a similar manner as \member{maxstring}. The
|
|
default is \code{20}.
|
|
\end{memberdesc}
|
|
|
|
\begin{methoddesc}{repr}{obj}
|
|
The equivalent to the built-in \function{repr()} that uses the
|
|
formatting imposed by the instance.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{repr1}{obj, level}
|
|
Recursive implementation used by \method{repr()}. This uses the
|
|
type of \var{obj} to determine which formatting method to call,
|
|
passing it \var{obj} and \var{level}. The type-specific methods
|
|
should call \method{repr1()} to perform recursive formatting, with
|
|
\code{\var{level} - 1} for the value of \var{level} in the recursive
|
|
call.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddescni}{repr_\var{type}}{obj, level}
|
|
Formatting methods for specific types are implemented as methods
|
|
with a name based on the type name. In the method name, \var{type}
|
|
is replaced by
|
|
\code{string.join(string.split(type(\var{obj}).__name__, '_'))}.
|
|
Dispatch to these methods is handled by \method{repr1()}.
|
|
Type-specific methods which need to recursively format a value
|
|
should call \samp{self.repr1(\var{subobj}, \var{level} - 1)}.
|
|
\end{methoddescni}
|
|
|
|
|
|
\subsection{Subclassing Repr Objects \label{subclassing-reprs}}
|
|
|
|
The use of dynamic dispatching by \method{Repr.repr1()} allows
|
|
subclasses of \class{Repr} to add support for additional built-in
|
|
object types or to modify the handling of types already supported.
|
|
This example shows how special support for file objects could be
|
|
added:
|
|
|
|
\begin{verbatim}
|
|
import repr
|
|
import sys
|
|
|
|
class MyRepr(repr.Repr):
|
|
def repr_file(self, obj, level):
|
|
if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
|
|
return obj.name
|
|
else:
|
|
return `obj`
|
|
|
|
aRepr = MyRepr()
|
|
print aRepr.repr(sys.stdin) # prints '<stdin>'
|
|
\end{verbatim}
|