2 :mod:`repr` --- Alternate :func:`repr` implementation
3 =====================================================
6 :synopsis: Alternate repr() implementation with size limits.
7 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
10 The :mod:`repr` module provides a means for producing object representations
11 with limits on the size of the resulting strings. This is used in the Python
12 debugger and may be useful in other contexts as well.
14 This module provides a class, an instance, and a function:
19 Class which provides formatting services useful in implementing functions
20 similar to the built-in :func:`repr`; size limits for different object types
21 are added to avoid the generation of representations which are excessively long.
26 This is an instance of :class:`Repr` which is used to provide the :func:`repr`
27 function described below. Changing the attributes of this object will affect
28 the size limits used by :func:`repr` and the Python debugger.
31 .. function:: repr(obj)
33 This is the :meth:`repr` method of ``aRepr``. It returns a string similar to
34 that returned by the built-in function of the same name, but with limits on
43 :class:`Repr` instances provide several members which can be used to provide
44 size limits for the representations of different object types, and methods
45 which format specific object types.
48 .. attribute:: Repr.maxlevel
50 Depth limit on the creation of recursive representations. The default is ``6``.
53 .. attribute:: Repr.maxdict
61 Limits on the number of entries represented for the named object type. The
62 default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and ``6`` for
66 :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`.
69 .. attribute:: Repr.maxlong
71 Maximum number of characters in the representation for a long integer. Digits
72 are dropped from the middle. The default is ``40``.
75 .. attribute:: Repr.maxstring
77 Limit on the number of characters in the representation of the string. Note
78 that the "normal" representation of the string is used as the character source:
79 if escape sequences are needed in the representation, these may be mangled when
80 the representation is shortened. The default is ``30``.
83 .. attribute:: Repr.maxother
85 This limit is used to control the size of object types for which no specific
86 formatting method is available on the :class:`Repr` object. It is applied in a
87 similar manner as :attr:`maxstring`. The default is ``20``.
90 .. method:: Repr.repr(obj)
92 The equivalent to the built-in :func:`repr` that uses the formatting imposed by
96 .. method:: Repr.repr1(obj, level)
98 Recursive implementation used by :meth:`repr`. This uses the type of *obj* to
99 determine which formatting method to call, passing it *obj* and *level*. The
100 type-specific methods should call :meth:`repr1` to perform recursive formatting,
101 with ``level - 1`` for the value of *level* in the recursive call.
104 .. method:: Repr.repr_TYPE(obj, level)
107 Formatting methods for specific types are implemented as methods with a name
108 based on the type name. In the method name, **TYPE** is replaced by
109 ``string.join(string.split(type(obj).__name__, '_'))``. Dispatch to these
110 methods is handled by :meth:`repr1`. Type-specific methods which need to
111 recursively format a value should call ``self.repr1(subobj, level - 1)``.
114 .. _subclassing-reprs:
116 Subclassing Repr Objects
117 ------------------------
119 The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
120 :class:`Repr` to add support for additional built-in object types or to modify
121 the handling of types already supported. This example shows how special support
122 for file objects could be added::
127 class MyRepr(repr.Repr):
128 def repr_file(self, obj, level):
129 if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
135 print aRepr.repr(sys.stdin) # prints '<stdin>'