1:mod:`repr` --- Alternate :func:`repr` implementation
2=====================================================
3
4.. module:: repr
5   :synopsis: Alternate repr() implementation with size limits.
6   :noindex:
7.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
8
9.. note::
10   The :mod:`repr` module has been renamed to :mod:`reprlib` in Python 3.  The
11   :term:`2to3` tool will automatically adapt imports when converting your
12   sources to Python 3.
13
14**Source code:** :source:`Lib/repr.py`
15
16--------------
17
18The :mod:`repr` module provides a means for producing object representations
19with limits on the size of the resulting strings. This is used in the Python
20debugger and may be useful in other contexts as well.
21
22This module provides a class, an instance, and a function:
23
24
25.. class:: Repr()
26
27   Class which provides formatting services useful in implementing functions
28   similar to the built-in :ref:`repr() <func-repr>`; size limits for different
29   object types are added to avoid the generation of representations which are
30   excessively long.
31
32
33.. data:: aRepr
34
35   This is an instance of :class:`Repr` which is used to provide the :func:`.repr`
36   function described below.  Changing the attributes of this object will affect
37   the size limits used by :func:`.repr` and the Python debugger.
38
39
40.. function:: repr(obj)
41
42   This is the :meth:`~Repr.repr` method of ``aRepr``.  It returns a string
43   similar to that returned by the built-in function of the same name, but with
44   limits on most sizes.
45
46
47.. _repr-objects:
48
49Repr Objects
50------------
51
52:class:`Repr` instances provide several attributes which can be used to provide
53size limits for the representations of different object types,  and methods
54which format specific object types.
55
56
57.. attribute:: Repr.maxlevel
58
59   Depth limit on the creation of recursive representations.  The default is ``6``.
60
61
62.. attribute:: Repr.maxdict
63               Repr.maxlist
64               Repr.maxtuple
65               Repr.maxset
66               Repr.maxfrozenset
67               Repr.maxdeque
68               Repr.maxarray
69
70   Limits on the number of entries represented for the named object type.  The
71   default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and  ``6`` for
72   the others.
73
74   .. versionadded:: 2.4
75      :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`.
76
77
78.. attribute:: Repr.maxlong
79
80   Maximum number of characters in the representation for a long integer.  Digits
81   are dropped from the middle.  The default is ``40``.
82
83
84.. attribute:: Repr.maxstring
85
86   Limit on the number of characters in the representation of the string.  Note
87   that the "normal" representation of the string is used as the character source:
88   if escape sequences are needed in the representation, these may be mangled when
89   the representation is shortened.  The default is ``30``.
90
91
92.. attribute:: Repr.maxother
93
94   This limit is used to control the size of object types for which no specific
95   formatting method is available on the :class:`Repr` object. It is applied in a
96   similar manner as :attr:`maxstring`.  The default is ``20``.
97
98
99.. method:: Repr.repr(obj)
100
101   The equivalent to the built-in :ref:`repr() <func-repr>` that uses the
102   formatting imposed by the instance.
103
104
105.. method:: Repr.repr1(obj, level)
106
107   Recursive implementation used by :meth:`.repr`.  This uses the type of *obj* to
108   determine which formatting method to call, passing it *obj* and *level*.  The
109   type-specific methods should call :meth:`repr1` to perform recursive formatting,
110   with ``level - 1`` for the value of *level* in the recursive  call.
111
112
113.. method:: Repr.repr_TYPE(obj, level)
114   :noindex:
115
116   Formatting methods for specific types are implemented as methods with a name
117   based on the type name.  In the method name, **TYPE** is replaced by
118   ``string.join(string.split(type(obj).__name__, '_'))``. Dispatch to these
119   methods is handled by :meth:`repr1`. Type-specific methods which need to
120   recursively format a value should call ``self.repr1(subobj, level - 1)``.
121
122
123.. _subclassing-reprs:
124
125Subclassing Repr Objects
126------------------------
127
128The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
129:class:`Repr` to add support for additional built-in object types or to modify
130the handling of types already supported. This example shows how special support
131for file objects could be added::
132
133   import repr as reprlib
134   import sys
135
136   class MyRepr(reprlib.Repr):
137       def repr_file(self, obj, level):
138           if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
139               return obj.name
140           else:
141               return repr(obj)
142
143   aRepr = MyRepr()
144   print aRepr.repr(sys.stdin)          # prints '<stdin>'
145
146