Document the repr module. This removes the entire "Code objects and

files, debugger etc." section from "Undocumented Modules"!

1 files changed, 125 insertions, 0 deletions

diff --git a/Doc/lib/librepr.tex b/Doc/lib/librepr.tex
new file mode 100644
index 0000000..76bf942
--- /dev/null
+++ b/Doc/lib/librepr.tex
@@ -0,0 +1,125 @@
+\section{\module{repr} ---
+         Alternate \function{repr()} implementation.}
+
+\declaremodule{standard}{repr}
+
+
+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}
+  Limits on the number of entries represented for the named object
+  type.  The default for \member{maxdict} is \code{4}, for the others, 
+  \code{6}.
+\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}