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

   129    import sys

   130 

   131    class MyRepr(repr.Repr):

   132        def repr_file(self, obj, level):

   133            if obj.name in ['<stdin>', '<stdout>', '<stderr>']:

   134                return obj.name

   135            else:

   136                return `obj`

   137 

   138    aRepr = MyRepr()

   139    print aRepr.repr(sys.stdin)          # prints '<stdin>'

   140