Doc/library/repr.rst

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