1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
<span id="reprlib-alternate-repr-implementation"></span><h1>reprlib — Alternate repr() implementation</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/reprlib.py">Lib/reprlib.py</a></p> <p>The <code>reprlib</code> module provides a means for producing object representations with limits on the size of the resulting strings. This is used in the Python debugger and may be useful in other contexts as well.</p> <p>This module provides a class, an instance, and a function:</p> <dl class="py class"> <dt class="sig sig-object py" id="reprlib.Repr">
<code>class reprlib.Repr(*, maxlevel=6, maxtuple=6, maxlist=6, maxarray=5, maxdict=4, maxset=6, maxfrozenset=6, maxdeque=6, maxstring=30, maxlong=40, maxother=30, fillvalue='...', indent=None)</code> </dt> <dd>
<p>Class which provides formatting services useful in implementing functions similar to the built-in <a class="reference internal" href="functions#repr" title="repr"><code>repr()</code></a>; size limits for different object types are added to avoid the generation of representations which are excessively long.</p> <p>The keyword arguments of the constructor can be used as a shortcut to set the attributes of the <a class="reference internal" href="#reprlib.Repr" title="reprlib.Repr"><code>Repr</code></a> instance. Which means that the following initialization:</p> <pre data-language="python">aRepr = reprlib.Repr(maxlevel=3)
</pre> <p>Is equivalent to:</p> <pre data-language="python">aRepr = reprlib.Repr()
aRepr.maxlevel = 3
</pre> <p>See section <a class="reference internal" href="#id1">Repr Objects</a> for more information about <a class="reference internal" href="#reprlib.Repr" title="reprlib.Repr"><code>Repr</code></a> attributes.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.12: </span>Allow attributes to be set via keyword arguments.</p> </div> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="reprlib.aRepr">
<code>reprlib.aRepr</code> </dt> <dd>
<p>This is an instance of <a class="reference internal" href="#reprlib.Repr" title="reprlib.Repr"><code>Repr</code></a> which is used to provide the <a class="reference internal" href="#reprlib.repr" title="reprlib.repr"><code>repr()</code></a> function described below. Changing the attributes of this object will affect the size limits used by <a class="reference internal" href="#reprlib.repr" title="reprlib.repr"><code>repr()</code></a> and the Python debugger.</p> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="reprlib.repr">
<code>reprlib.repr(obj)</code> </dt> <dd>
<p>This is the <a class="reference internal" href="#reprlib.Repr.repr" title="reprlib.Repr.repr"><code>repr()</code></a> method of <code>aRepr</code>. It returns a string similar to that returned by the built-in function of the same name, but with limits on most sizes.</p> </dd>
</dl> <p>In addition to size-limiting tools, the module also provides a decorator for detecting recursive calls to <a class="reference internal" href="../reference/datamodel#object.__repr__" title="object.__repr__"><code>__repr__()</code></a> and substituting a placeholder string instead.</p> <span class="target" id="index-0"></span><dl class="py function"> <dt class="sig sig-object py" id="reprlib.recursive_repr">
<code>@reprlib.recursive_repr(fillvalue='...')</code> </dt> <dd>
<p>Decorator for <a class="reference internal" href="../reference/datamodel#object.__repr__" title="object.__repr__"><code>__repr__()</code></a> methods to detect recursive calls within the same thread. If a recursive call is made, the <em>fillvalue</em> is returned, otherwise, the usual <code>__repr__()</code> call is made. For example:</p> <pre data-language="pycon3">>>> from reprlib import recursive_repr
>>> class MyList(list):
... @recursive_repr()
... def __repr__(self):
... return '<' + '|'.join(map(repr, self)) + '>'
...
>>> m = MyList('abc')
>>> m.append(m)
>>> m.append('x')
>>> print(m)
<'a'|'b'|'c'|...|'x'>
</pre> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> </dd>
</dl> <section id="repr-objects"> <span id="id1"></span><h2>Repr Objects</h2> <p><a class="reference internal" href="#reprlib.Repr" title="reprlib.Repr"><code>Repr</code></a> instances provide several attributes which can be used to provide size limits for the representations of different object types, and methods which format specific object types.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="reprlib.Repr.fillvalue">
<code>Repr.fillvalue</code> </dt> <dd>
<p>This string is displayed for recursive references. It defaults to <code>...</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.11.</span></p> </div> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="reprlib.Repr.maxlevel">
<code>Repr.maxlevel</code> </dt> <dd>
<p>Depth limit on the creation of recursive representations. The default is <code>6</code>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="reprlib.Repr.maxdict">
<code>Repr.maxdict</code> </dt> <dt class="sig sig-object py" id="reprlib.Repr.maxlist">
<code>Repr.maxlist</code> </dt> <dt class="sig sig-object py" id="reprlib.Repr.maxtuple">
<code>Repr.maxtuple</code> </dt> <dt class="sig sig-object py" id="reprlib.Repr.maxset">
<code>Repr.maxset</code> </dt> <dt class="sig sig-object py" id="reprlib.Repr.maxfrozenset">
<code>Repr.maxfrozenset</code> </dt> <dt class="sig sig-object py" id="reprlib.Repr.maxdeque">
<code>Repr.maxdeque</code> </dt> <dt class="sig sig-object py" id="reprlib.Repr.maxarray">
<code>Repr.maxarray</code> </dt> <dd>
<p>Limits on the number of entries represented for the named object type. The default is <code>4</code> for <a class="reference internal" href="#reprlib.Repr.maxdict" title="reprlib.Repr.maxdict"><code>maxdict</code></a>, <code>5</code> for <a class="reference internal" href="#reprlib.Repr.maxarray" title="reprlib.Repr.maxarray"><code>maxarray</code></a>, and <code>6</code> for the others.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="reprlib.Repr.maxlong">
<code>Repr.maxlong</code> </dt> <dd>
<p>Maximum number of characters in the representation for an integer. Digits are dropped from the middle. The default is <code>40</code>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="reprlib.Repr.maxstring">
<code>Repr.maxstring</code> </dt> <dd>
<p>Limit on the number of characters in the representation of the string. Note that the “normal” representation of the string is used as the character source: if escape sequences are needed in the representation, these may be mangled when the representation is shortened. The default is <code>30</code>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="reprlib.Repr.maxother">
<code>Repr.maxother</code> </dt> <dd>
<p>This limit is used to control the size of object types for which no specific formatting method is available on the <a class="reference internal" href="#reprlib.Repr" title="reprlib.Repr"><code>Repr</code></a> object. It is applied in a similar manner as <a class="reference internal" href="#reprlib.Repr.maxstring" title="reprlib.Repr.maxstring"><code>maxstring</code></a>. The default is <code>20</code>.</p> </dd>
</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="reprlib.Repr.indent">
<code>Repr.indent</code> </dt> <dd>
<p>If this attribute is set to <code>None</code> (the default), the output is formatted with no line breaks or indentation, like the standard <a class="reference internal" href="functions#repr" title="repr"><code>repr()</code></a>. For example:</p> <pre data-language="pycon3">>>> example = [
... 1, 'spam', {'a': 2, 'b': 'spam eggs', 'c': {3: 4.5, 6: []}}, 'ham']
>>> import reprlib
>>> aRepr = reprlib.Repr()
>>> print(aRepr.repr(example))
[1, 'spam', {'a': 2, 'b': 'spam eggs', 'c': {3: 4.5, 6: []}}, 'ham']
</pre> <p>If <a class="reference internal" href="#reprlib.Repr.indent" title="reprlib.Repr.indent"><code>indent</code></a> is set to a string, each recursion level is placed on its own line, indented by that string:</p> <pre data-language="pycon3">>>> aRepr.indent = '-->'
>>> print(aRepr.repr(example))
[
-->1,
-->'spam',
-->{
-->-->'a': 2,
-->-->'b': 'spam eggs',
-->-->'c': {
-->-->-->3: 4.5,
-->-->-->6: [],
-->-->},
-->},
-->'ham',
]
</pre> <p>Setting <a class="reference internal" href="#reprlib.Repr.indent" title="reprlib.Repr.indent"><code>indent</code></a> to a positive integer value behaves as if it was set to a string with that number of spaces:</p> <pre data-language="pycon3">>>> aRepr.indent = 4
>>> print(aRepr.repr(example))
[
1,
'spam',
{
'a': 2,
'b': 'spam eggs',
'c': {
3: 4.5,
6: [],
},
},
'ham',
]
</pre> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.12.</span></p> </div> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="reprlib.Repr.repr">
<code>Repr.repr(obj)</code> </dt> <dd>
<p>The equivalent to the built-in <a class="reference internal" href="functions#repr" title="repr"><code>repr()</code></a> that uses the formatting imposed by the instance.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py" id="reprlib.Repr.repr1">
<code>Repr.repr1(obj, level)</code> </dt> <dd>
<p>Recursive implementation used by <a class="reference internal" href="#reprlib.Repr.repr" title="reprlib.Repr.repr"><code>repr()</code></a>. This uses the type of <em>obj</em> to determine which formatting method to call, passing it <em>obj</em> and <em>level</em>. The type-specific methods should call <a class="reference internal" href="#reprlib.Repr.repr1" title="reprlib.Repr.repr1"><code>repr1()</code></a> to perform recursive formatting, with <code>level - 1</code> for the value of <em>level</em> in the recursive call.</p> </dd>
</dl> <dl class="py method"> <dt class="sig sig-object py"> <span class="sig-prename descclassname">Repr.</span><span class="sig-name descname">repr_TYPE</span><span class="sig-paren">(</span><em class="sig-param"><span class="n">obj</span></em>, <em class="sig-param"><span class="n">level</span></em><span class="sig-paren">)</span>
</dt> <dd>
<p>Formatting methods for specific types are implemented as methods with a name based on the type name. In the method name, <strong>TYPE</strong> is replaced by <code>'_'.join(type(obj).__name__.split())</code>. Dispatch to these methods is handled by <a class="reference internal" href="#reprlib.Repr.repr1" title="reprlib.Repr.repr1"><code>repr1()</code></a>. Type-specific methods which need to recursively format a value should call <code>self.repr1(subobj, level - 1)</code>.</p> </dd>
</dl> </section> <section id="subclassing-repr-objects"> <span id="subclassing-reprs"></span><h2>Subclassing Repr Objects</h2> <p>The use of dynamic dispatching by <a class="reference internal" href="#reprlib.Repr.repr1" title="reprlib.Repr.repr1"><code>Repr.repr1()</code></a> allows subclasses of <a class="reference internal" href="#reprlib.Repr" title="reprlib.Repr"><code>Repr</code></a> to add support for additional built-in object types or to modify the handling of types already supported. This example shows how special support for file objects could be added:</p> <pre data-language="python">import reprlib
import sys
class MyRepr(reprlib.Repr):
def repr_TextIOWrapper(self, obj, level):
if obj.name in {'<stdin>', '<stdout>', '<stderr>'}:
return obj.name
return repr(obj)
aRepr = MyRepr()
print(aRepr.repr(sys.stdin)) # prints '<stdin>'
</pre> <pre data-language="none"><stdin>
</pre> </section> <div class="_attribution">
<p class="_attribution-p">
© 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br>
<a href="https://docs.python.org/3.12/library/reprlib.html" class="_attribution-link">https://docs.python.org/3.12/library/reprlib.html</a>
</p>
</div>
|
