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