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