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