Doc/library/repr.rst

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