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. <fdrake@acm.org>
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.maxlevel
80
81   Depth limit on the creation of recursive representations.  The default is ``6``.
82
83
84.. attribute:: Repr.maxdict
85               Repr.maxlist
86               Repr.maxtuple
87               Repr.maxset
88               Repr.maxfrozenset
89               Repr.maxdeque
90               Repr.maxarray
91
92   Limits on the number of entries represented for the named object type.  The
93   default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and  ``6`` for
94   the others.
95
96
97.. attribute:: Repr.maxlong
98
99   Maximum number of characters in the representation for an integer.  Digits
100   are dropped from the middle.  The default is ``40``.
101
102
103.. attribute:: Repr.maxstring
104
105   Limit on the number of characters in the representation of the string.  Note
106   that the "normal" representation of the string is used as the character source:
107   if escape sequences are needed in the representation, these may be mangled when
108   the representation is shortened.  The default is ``30``.
109
110
111.. attribute:: Repr.maxother
112
113   This limit is used to control the size of object types for which no specific
114   formatting method is available on the :class:`Repr` object. It is applied in a
115   similar manner as :attr:`maxstring`.  The default is ``20``.
116
117
118.. method:: Repr.repr(obj)
119
120   The equivalent to the built-in :func:`repr` that uses the formatting imposed by
121   the instance.
122
123
124.. method:: Repr.repr1(obj, level)
125
126   Recursive implementation used by :meth:`.repr`.  This uses the type of *obj* to
127   determine which formatting method to call, passing it *obj* and *level*.  The
128   type-specific methods should call :meth:`repr1` to perform recursive formatting,
129   with ``level - 1`` for the value of *level* in the recursive  call.
130
131
132.. method:: Repr.repr_TYPE(obj, level)
133   :noindex:
134
135   Formatting methods for specific types are implemented as methods with a name
136   based on the type name.  In the method name, **TYPE** is replaced by
137   ``'_'.join(type(obj).__name__.split())``. Dispatch to these methods is
138   handled by :meth:`repr1`. Type-specific methods which need to recursively
139   format a value should call ``self.repr1(subobj, level - 1)``.
140
141
142.. _subclassing-reprs:
143
144Subclassing Repr Objects
145------------------------
146
147The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
148:class:`Repr` to add support for additional built-in object types or to modify
149the handling of types already supported. This example shows how special support
150for file objects could be added::
151
152   import reprlib
153   import sys
154
155   class MyRepr(reprlib.Repr):
156
157       def repr_TextIOWrapper(self, obj, level):
158           if obj.name in {'<stdin>', '<stdout>', '<stderr>'}:
159               return obj.name
160           return repr(obj)
161
162   aRepr = MyRepr()
163   print(aRepr.repr(sys.stdin))         # prints '<stdin>'
164