diff options
Diffstat (limited to 'devdocs/python~3.12/library%2Freprlib.html')
| -rw-r--r-- | devdocs/python~3.12/library%2Freprlib.html | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/devdocs/python~3.12/library%2Freprlib.html b/devdocs/python~3.12/library%2Freprlib.html new file mode 100644 index 00000000..d18293a7 --- /dev/null +++ b/devdocs/python~3.12/library%2Freprlib.html @@ -0,0 +1,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> |