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 has been renamed to :mod:`reprlib` in Python 3.0. The
11 :term:`2to3` tool will automatically adapt imports when converting your
14 The :mod:`repr` module provides a means for producing object representations
15 with limits on the size of the resulting strings. This is used in the Python
16 debugger and may be useful in other contexts as well.
18 This module provides a class, an instance, and a function:
23 Class which provides formatting services useful in implementing functions
24 similar to the built-in :func:`repr`; size limits for different object types
25 are added to avoid the generation of representations which are excessively long.
30 This is an instance of :class:`Repr` which is used to provide the :func:`repr`
31 function described below. Changing the attributes of this object will affect
32 the size limits used by :func:`repr` and the Python debugger.
35 .. function:: repr(obj)
37 This is the :meth:`repr` method of ``aRepr``. It returns a string similar to
38 that returned by the built-in function of the same name, but with limits on
47 :class:`Repr` instances provide several members which can be used to provide
48 size limits for the representations of different object types, and methods
49 which format specific object types.
52 .. attribute:: Repr.maxlevel
54 Depth limit on the creation of recursive representations. The default is ``6``.
57 .. attribute:: Repr.maxdict
65 Limits on the number of entries represented for the named object type. The
66 default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and ``6`` for
70 :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`.
73 .. attribute:: Repr.maxlong
75 Maximum number of characters in the representation for a long integer. Digits
76 are dropped from the middle. The default is ``40``.
79 .. attribute:: Repr.maxstring
81 Limit on the number of characters in the representation of the string. Note
82 that the "normal" representation of the string is used as the character source:
83 if escape sequences are needed in the representation, these may be mangled when
84 the representation is shortened. The default is ``30``.
87 .. attribute:: Repr.maxother
89 This limit is used to control the size of object types for which no specific
90 formatting method is available on the :class:`Repr` object. It is applied in a
91 similar manner as :attr:`maxstring`. The default is ``20``.
94 .. method:: Repr.repr(obj)
96 The equivalent to the built-in :func:`repr` that uses the formatting imposed by
100 .. method:: Repr.repr1(obj, level)
102 Recursive implementation used by :meth:`repr`. This uses the type of *obj* to
103 determine which formatting method to call, passing it *obj* and *level*. The
104 type-specific methods should call :meth:`repr1` to perform recursive formatting,
105 with ``level - 1`` for the value of *level* in the recursive call.
108 .. method:: Repr.repr_TYPE(obj, level)
111 Formatting methods for specific types are implemented as methods with a name
112 based on the type name. In the method name, **TYPE** is replaced by
113 ``string.join(string.split(type(obj).__name__, '_'))``. Dispatch to these
114 methods is handled by :meth:`repr1`. Type-specific methods which need to
115 recursively format a value should call ``self.repr1(subobj, level - 1)``.
118 .. _subclassing-reprs:
120 Subclassing Repr Objects
121 ------------------------
123 The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
124 :class:`Repr` to add support for additional built-in object types or to modify
125 the handling of types already supported. This example shows how special support
126 for file objects could be added::
128 import repr as reprlib
131 class MyRepr(reprlib.Repr):
132 def repr_file(self, obj, level):
133 if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
139 print aRepr.repr(sys.stdin) # prints '<stdin>'