1 :mod:`repr` --- Alternate :func:`repr` implementation 2 ===================================================== 3 4 .. module:: repr 5 :synopsis: Alternate repr() implementation with size limits. 6 :noindex: 7 .. sectionauthor:: Fred L. Drake, Jr. <fdrake (a] acm.org> 8 9 .. note:: 10 The :mod:`repr` module has been renamed to :mod:`reprlib` in Python 3. The 11 :term:`2to3` tool will automatically adapt imports when converting your 12 sources to Python 3. 13 14 **Source code:** :source:`Lib/repr.py` 15 16 -------------- 17 18 The :mod:`repr` module provides a means for producing object representations 19 with limits on the size of the resulting strings. This is used in the Python 20 debugger and may be useful in other contexts as well. 21 22 This module provides a class, an instance, and a function: 23 24 25 .. class:: Repr() 26 27 Class which provides formatting services useful in implementing functions 28 similar to the built-in :ref:`repr() <func-repr>`; size limits for different 29 object types are added to avoid the generation of representations which are 30 excessively long. 31 32 33 .. data:: aRepr 34 35 This is an instance of :class:`Repr` which is used to provide the :func:`.repr` 36 function described below. Changing the attributes of this object will affect 37 the size limits used by :func:`.repr` and the Python debugger. 38 39 40 .. function:: repr(obj) 41 42 This is the :meth:`~Repr.repr` method of ``aRepr``. It returns a string 43 similar to that returned by the built-in function of the same name, but with 44 limits on most sizes. 45 46 47 .. _repr-objects: 48 49 Repr Objects 50 ------------ 51 52 :class:`Repr` instances provide several attributes which can be used to provide 53 size limits for the representations of different object types, and methods 54 which format specific object types. 55 56 57 .. attribute:: Repr.maxlevel 58 59 Depth limit on the creation of recursive representations. The default is ``6``. 60 61 62 .. attribute:: Repr.maxdict 63 Repr.maxlist 64 Repr.maxtuple 65 Repr.maxset 66 Repr.maxfrozenset 67 Repr.maxdeque 68 Repr.maxarray 69 70 Limits on the number of entries represented for the named object type. The 71 default is ``4`` for :attr:`maxdict`, ``5`` for :attr:`maxarray`, and ``6`` for 72 the others. 73 74 .. versionadded:: 2.4 75 :attr:`maxset`, :attr:`maxfrozenset`, and :attr:`set`. 76 77 78 .. attribute:: Repr.maxlong 79 80 Maximum number of characters in the representation for a long integer. Digits 81 are dropped from the middle. The default is ``40``. 82 83 84 .. attribute:: Repr.maxstring 85 86 Limit on the number of characters in the representation of the string. Note 87 that the "normal" representation of the string is used as the character source: 88 if escape sequences are needed in the representation, these may be mangled when 89 the representation is shortened. The default is ``30``. 90 91 92 .. attribute:: Repr.maxother 93 94 This limit is used to control the size of object types for which no specific 95 formatting method is available on the :class:`Repr` object. It is applied in a 96 similar manner as :attr:`maxstring`. The default is ``20``. 97 98 99 .. method:: Repr.repr(obj) 100 101 The equivalent to the built-in :ref:`repr() <func-repr>` that uses the 102 formatting imposed by the instance. 103 104 105 .. method:: Repr.repr1(obj, level) 106 107 Recursive implementation used by :meth:`.repr`. This uses the type of *obj* to 108 determine which formatting method to call, passing it *obj* and *level*. The 109 type-specific methods should call :meth:`repr1` to perform recursive formatting, 110 with ``level - 1`` for the value of *level* in the recursive call. 111 112 113 .. method:: Repr.repr_TYPE(obj, level) 114 :noindex: 115 116 Formatting methods for specific types are implemented as methods with a name 117 based on the type name. In the method name, **TYPE** is replaced by 118 ``string.join(string.split(type(obj).__name__, '_'))``. Dispatch to these 119 methods is handled by :meth:`repr1`. Type-specific methods which need to 120 recursively format a value should call ``self.repr1(subobj, level - 1)``. 121 122 123 .. _subclassing-reprs: 124 125 Subclassing Repr Objects 126 ------------------------ 127 128 The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of 129 :class:`Repr` to add support for additional built-in object types or to modify 130 the handling of types already supported. This example shows how special support 131 for file objects could be added:: 132 133 import repr as reprlib 134 import sys 135 136 class MyRepr(reprlib.Repr): 137 def repr_file(self, obj, level): 138 if obj.name in ['<stdin>', '<stdout>', '<stderr>']: 139 return obj.name 140 else: 141 return repr(obj) 142 143 aRepr = MyRepr() 144 print aRepr.repr(sys.stdin) # prints '<stdin>' 145 146
