source: trunk/essentials/dev-lang/python/Doc/lib/librepr.tex@ 3398

\section{\module{repr} ---
         Alternate \function{repr()} implementation}

\sectionauthor{Fred L. Drake, Jr.}{[email protected]}
\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}