Fred Drake | 9d814c6 | 1999-01-27 17:20:33 +0000 | [diff] [blame] | 1 | \section{\module{repr} --- |
Fred Drake | f8ca7d8 | 2000-10-10 17:03:45 +0000 | [diff] [blame] | 2 | Alternate \function{repr()} implementation} |
Fred Drake | 9d814c6 | 1999-01-27 17:20:33 +0000 | [diff] [blame] | 3 | |
Fred Drake | 703b70e | 1999-01-28 19:30:49 +0000 | [diff] [blame] | 4 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
Fred Drake | 9d814c6 | 1999-01-27 17:20:33 +0000 | [diff] [blame] | 5 | \declaremodule{standard}{repr} |
Fred Drake | 703b70e | 1999-01-28 19:30:49 +0000 | [diff] [blame] | 6 | \modulesynopsis{Alternate \function{repr()} implementation with size limits.} |
Fred Drake | 9d814c6 | 1999-01-27 17:20:33 +0000 | [diff] [blame] | 7 | |
| 8 | |
| 9 | The \module{repr} module provides a means for producing object |
| 10 | representations with limits on the size of the resulting strings. |
| 11 | This is used in the Python debugger and may be useful in other |
| 12 | contexts as well. |
| 13 | |
| 14 | This module provides a class, an instance, and a function: |
| 15 | |
| 16 | |
| 17 | \begin{classdesc}{Repr}{} |
| 18 | Class which provides formatting services useful in implementing |
| 19 | functions similar to the built-in \function{repr()}; size limits for |
| 20 | different object types are added to avoid the generation of |
| 21 | representations which are excessively long. |
| 22 | \end{classdesc} |
| 23 | |
| 24 | |
| 25 | \begin{datadesc}{aRepr} |
| 26 | This is an instance of \class{Repr} which is used to provide the |
| 27 | \function{repr()} function described below. Changing the attributes |
| 28 | of this object will affect the size limits used by \function{repr()} |
| 29 | and the Python debugger. |
| 30 | \end{datadesc} |
| 31 | |
| 32 | |
| 33 | \begin{funcdesc}{repr}{obj} |
| 34 | This is the \method{repr()} method of \code{aRepr}. It returns a |
| 35 | string similar to that returned by the built-in function of the same |
| 36 | name, but with limits on most sizes. |
| 37 | \end{funcdesc} |
| 38 | |
| 39 | |
| 40 | \subsection{Repr Objects \label{Repr-objects}} |
| 41 | |
| 42 | \class{Repr} instances provide several members which can be used to |
| 43 | provide size limits for the representations of different object types, |
| 44 | and methods which format specific object types. |
| 45 | |
| 46 | |
| 47 | \begin{memberdesc}{maxlevel} |
| 48 | Depth limit on the creation of recursive representations. The |
| 49 | default is \code{6}. |
| 50 | \end{memberdesc} |
| 51 | |
| 52 | \begin{memberdesc}{maxdict} |
| 53 | \memberline{maxlist} |
| 54 | \memberline{maxtuple} |
Raymond Hettinger | e36894d | 2004-05-22 16:38:11 +0000 | [diff] [blame] | 55 | \memberline{maxset} |
| 56 | \memberline{maxfrozenset} |
| 57 | \memberline{maxdeque} |
| 58 | \memberline{maxarray} |
Fred Drake | 9d814c6 | 1999-01-27 17:20:33 +0000 | [diff] [blame] | 59 | Limits on the number of entries represented for the named object |
Raymond Hettinger | e36894d | 2004-05-22 16:38:11 +0000 | [diff] [blame] | 60 | type. The default is \code{4} for \member{maxdict}, \code{5} for |
| 61 | \member{maxarray}, and \code{6} for the others. |
| 62 | \versionadded[\member{maxset}, \member{maxfrozenset}, |
| 63 | and \member{set}]{2.4}. |
Fred Drake | 9d814c6 | 1999-01-27 17:20:33 +0000 | [diff] [blame] | 64 | \end{memberdesc} |
| 65 | |
| 66 | \begin{memberdesc}{maxlong} |
| 67 | Maximum number of characters in the representation for a long |
| 68 | integer. Digits are dropped from the middle. The default is |
| 69 | \code{40}. |
| 70 | \end{memberdesc} |
| 71 | |
| 72 | \begin{memberdesc}{maxstring} |
| 73 | Limit on the number of characters in the representation of the |
| 74 | string. Note that the ``normal'' representation of the string is |
| 75 | used as the character source: if escape sequences are needed in the |
| 76 | representation, these may be mangled when the representation is |
| 77 | shortened. The default is \code{30}. |
| 78 | \end{memberdesc} |
| 79 | |
| 80 | \begin{memberdesc}{maxother} |
| 81 | This limit is used to control the size of object types for which no |
| 82 | specific formatting method is available on the \class{Repr} object. |
| 83 | It is applied in a similar manner as \member{maxstring}. The |
| 84 | default is \code{20}. |
| 85 | \end{memberdesc} |
| 86 | |
| 87 | \begin{methoddesc}{repr}{obj} |
| 88 | The equivalent to the built-in \function{repr()} that uses the |
| 89 | formatting imposed by the instance. |
| 90 | \end{methoddesc} |
| 91 | |
| 92 | \begin{methoddesc}{repr1}{obj, level} |
| 93 | Recursive implementation used by \method{repr()}. This uses the |
| 94 | type of \var{obj} to determine which formatting method to call, |
| 95 | passing it \var{obj} and \var{level}. The type-specific methods |
| 96 | should call \method{repr1()} to perform recursive formatting, with |
| 97 | \code{\var{level} - 1} for the value of \var{level} in the recursive |
| 98 | call. |
| 99 | \end{methoddesc} |
| 100 | |
| 101 | \begin{methoddescni}{repr_\var{type}}{obj, level} |
| 102 | Formatting methods for specific types are implemented as methods |
| 103 | with a name based on the type name. In the method name, \var{type} |
| 104 | is replaced by |
Raymond Hettinger | bf3a752 | 2003-05-12 03:23:51 +0000 | [diff] [blame] | 105 | \code{string.join(string.split(type(\var{obj}).__name__, '_'))}. |
Fred Drake | 9d814c6 | 1999-01-27 17:20:33 +0000 | [diff] [blame] | 106 | Dispatch to these methods is handled by \method{repr1()}. |
| 107 | Type-specific methods which need to recursively format a value |
| 108 | should call \samp{self.repr1(\var{subobj}, \var{level} - 1)}. |
| 109 | \end{methoddescni} |
| 110 | |
| 111 | |
| 112 | \subsection{Subclassing Repr Objects \label{subclassing-reprs}} |
| 113 | |
| 114 | The use of dynamic dispatching by \method{Repr.repr1()} allows |
| 115 | subclasses of \class{Repr} to add support for additional built-in |
| 116 | object types or to modify the handling of types already supported. |
| 117 | This example shows how special support for file objects could be |
| 118 | added: |
| 119 | |
| 120 | \begin{verbatim} |
| 121 | import repr |
| 122 | import sys |
| 123 | |
| 124 | class MyRepr(repr.Repr): |
| 125 | def repr_file(self, obj, level): |
| 126 | if obj.name in ['<stdin>', '<stdout>', '<stderr>']: |
| 127 | return obj.name |
| 128 | else: |
| 129 | return `obj` |
| 130 | |
| 131 | aRepr = MyRepr() |
| 132 | print aRepr.repr(sys.stdin) # prints '<stdin>' |
| 133 | \end{verbatim} |