Debian Codegraph @

Doc/library/reprlib.rst

raw
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
13 The :mod:`!reprlib` module provides a means for producing object representations
14 with limits on the size of the resulting strings. This is used in the Python
15 debugger and may be useful in other contexts as well.
16
17 This module provides a class, an instance, and a function:
18
19
20 .. class:: Repr(*, maxlevel=6, maxtuple=6, maxlist=6, maxarray=5, maxdict=4, \
21 maxset=6, maxfrozenset=6, maxdeque=6, maxstring=30, maxlong=40, \
22 maxother=30, fillvalue="...", indent=None)
23
24 Class which provides formatting services useful in implementing functions
25 similar to the built-in :func:`repr`; size limits for different object types
26 are added to avoid the generation of representations which are excessively long.
27
28 The keyword arguments of the constructor can be used as a shortcut to set the
29 attributes of the :class:`Repr` instance. Which means that the following
30 initialization::
31
32 aRepr = reprlib.Repr(maxlevel=3)
33
34 Is equivalent to::
35
36 aRepr = reprlib.Repr()
37 aRepr.maxlevel = 3
38
39 See section `Repr Objects`_ for more information about :class:`Repr`
40 attributes.
41
42 .. versionchanged:: 3.12
43 Allow attributes to be set via keyword arguments.
44
45
46 .. data:: aRepr
47
48 This is an instance of :class:`Repr` which is used to provide the
49 :func:`.repr` function described below. Changing the attributes of this
50 object will affect the size limits used by :func:`.repr` and the Python
51 debugger.
52
53
54 .. function:: repr(obj)
55
56 This is the :meth:`~Repr.repr` method of ``aRepr``. It returns a string
57 similar to that returned by the built-in function of the same name, but with
58 limits on most sizes.
59
60 In addition to size-limiting tools, the module also provides a decorator for
61 detecting recursive calls to :meth:`~object.__repr__` and substituting a
62 placeholder string instead.
63
64
65 .. index:: single: ...; placeholder
66
67 .. decorator:: recursive_repr(fillvalue="...")
68
69 Decorator for :meth:`~object.__repr__` methods to detect recursive calls within the
70 same thread. If a recursive call is made, the *fillvalue* is returned,
71 otherwise, the usual :meth:`!__repr__` call is made. For example:
72
73 .. doctest::
74
75 >>> from reprlib import recursive_repr
76 >>> class MyList(list):
77 ... @recursive_repr()
78 ... def __repr__(self):
79 ... return '<' + '|'.join(map(repr, self)) + '>'
80 ...
81 >>> m = MyList('abc')
82 >>> m.append(m)
83 >>> m.append('x')
84 >>> print(m)
85 <'a'|'b'|'c'|...|'x'>
86
87 .. versionadded:: 3.2
88
89
90 .. _repr-objects:
91
92 Repr Objects
93 ------------
94
95 :class:`Repr` instances provide several attributes which can be used to provide
96 size limits for the representations of different object types, and methods
97 which format specific object types.
98
99
100 .. attribute:: Repr.fillvalue
101
102 This string is displayed for recursive references. It defaults to
103 ``...``.
104
105 .. versionadded:: 3.11
106
107
108 .. attribute:: Repr.maxlevel
109
110 Depth limit on the creation of recursive representations. The default is ``6``.
111
112
113 .. attribute:: Repr.maxdict
114 Repr.maxlist
115 Repr.maxtuple
116 Repr.maxset
117 Repr.maxfrozenset
118 Repr.maxdeque
119 Repr.maxarray
120
121 Limits on the number of entries represented for the named object type. The
122 default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and ``6`` for
123 the others.
124
125
126 .. attribute:: Repr.maxlong
127
128 Maximum number of characters in the representation for an integer. Digits
129 are dropped from the middle. The default is ``40``.
130
131
132 .. attribute:: Repr.maxstring
133
134 Limit on the number of characters in the representation of the string. Note
135 that the "normal" representation of the string is used as the character source:
136 if escape sequences are needed in the representation, these may be mangled when
137 the representation is shortened. The default is ``30``.
138
139
140 .. attribute:: Repr.maxother
141
142 This limit is used to control the size of object types for which no specific
143 formatting method is available on the :class:`Repr` object. It is applied in a
144 similar manner as :attr:`maxstring`. The default is ``20``.
145
146
147 .. attribute:: Repr.indent
148
149 If this attribute is set to ``None`` (the default), the output is formatted
150 with no line breaks or indentation, like the standard :func:`repr`.
151 For example:
152
153 .. doctest:: indent
154
155 >>> example = [
156 ... 1, 'spam', {'a': 2, 'b': 'spam eggs', 'c': {3: 4.5, 6: []}}, 'ham']
157 >>> import reprlib
158 >>> aRepr = reprlib.Repr()
159 >>> print(aRepr.repr(example))
160 [1, 'spam', {'a': 2, 'b': 'spam eggs', 'c': {3: 4.5, 6: []}}, 'ham']
161
162 If :attr:`~Repr.indent` is set to a string, each recursion level
163 is placed on its own line, indented by that string:
164
165 .. doctest:: indent
166
167 >>> aRepr.indent = '-->'
168 >>> print(aRepr.repr(example))
169 [
170 -->1,
171 -->'spam',
172 -->{
173 -->-->'a': 2,
174 -->-->'b': 'spam eggs',
175 -->-->'c': {
176 -->-->-->3: 4.5,
177 -->-->-->6: [],
178 -->-->},
179 -->},
180 -->'ham',
181 ]
182
183 Setting :attr:`~Repr.indent` to a positive integer value behaves as if it
184 was set to a string with that number of spaces:
185
186 .. doctest:: indent
187
188 >>> aRepr.indent = 4
189 >>> print(aRepr.repr(example))
190 [
191 1,
192 'spam',
193 {
194 'a': 2,
195 'b': 'spam eggs',
196 'c': {
197 3: 4.5,
198 6: [],
199 },
200 },
201 'ham',
202 ]
203
204 .. versionadded:: 3.12
205
206
207 .. method:: Repr.repr(obj)
208
209 The equivalent to the built-in :func:`repr` that uses the formatting imposed by
210 the instance.
211
212
213 .. method:: Repr.repr1(obj, level)
214
215 Recursive implementation used by :meth:`.repr`. This uses the type of *obj* to
216 determine which formatting method to call, passing it *obj* and *level*. The
217 type-specific methods should call :meth:`repr1` to perform recursive formatting,
218 with ``level - 1`` for the value of *level* in the recursive call.
219
220
221 .. method:: Repr.repr_TYPE(obj, level)
222 :noindex:
223
224 Formatting methods for specific types are implemented as methods with a name
225 based on the type name. In the method name, **TYPE** is replaced by
226 ``'_'.join(type(obj).__name__.split())``. Dispatch to these methods is
227 handled by :meth:`repr1`. Type-specific methods which need to recursively
228 format a value should call ``self.repr1(subobj, level - 1)``.
229
230
231 .. _subclassing-reprs:
232
233 Subclassing Repr Objects
234 ------------------------
235
236 The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
237 :class:`Repr` to add support for additional built-in object types or to modify
238 the handling of types already supported. This example shows how special support
239 for file objects could be added:
240
241 .. testcode::
242
243 import reprlib
244 import sys
245
246 class MyRepr(reprlib.Repr):
247
248 def repr_TextIOWrapper(self, obj, level):
249 if obj.name in {'<stdin>', '<stdout>', '<stderr>'}:
250 return obj.name
251 return repr(obj)
252
253 aRepr = MyRepr()
254 print(aRepr.repr(sys.stdin)) # prints '<stdin>'
255
256 .. testoutput::
257
258 <stdin>