rest25/library/repr.rst => rest262/library/repr.rst
f1
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
n9+.. 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.
9
10The :mod:`repr` module provides a means for producing object representations
11with limits on the size of the resulting strings. This is used in the Python
12debugger and may be useful in other contexts as well.
13
14This module provides a class, an instance, and a function:
15
16
40Repr Objects
41------------
42
43:class:`Repr` instances provide several members which can be used to provide
44size limits for the representations of different object types,  and methods
45which format specific object types.
46
47
n48-.. attribute:: XXX Class.maxlevel
n52+.. attribute:: Repr.maxlevel
49
50   Depth limit on the creation of recursive representations.  The default is ``6``.
51
52
n53-.. attribute:: XXX Class.maxdict
n57+.. attribute:: Repr.maxdict
54-               XXX Class.maxlist
58+               Repr.maxlist
55-               XXX Class.maxtuple
59+               Repr.maxtuple
56-               XXX Class.maxset
60+               Repr.maxset
57-               XXX Class.maxfrozenset
61+               Repr.maxfrozenset
58-               XXX Class.maxdeque
62+               Repr.maxdeque
59-               XXX Class.maxarray
63+               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
n68-   .
69
n70- 
71-.. attribute:: XXX Class.maxlong
73+.. attribute:: Repr.maxlong
72
73   Maximum number of characters in the representation for a long integer.  Digits
74   are dropped from the middle.  The default is ``40``.
75
76
n77-.. attribute:: XXX Class.maxstring
n79+.. attribute:: Repr.maxstring
78
79   Limit on the number of characters in the representation of the string.  Note
80   that the "normal" representation of the string is used as the character source:
81   if escape sequences are needed in the representation, these may be mangled when
82   the representation is shortened.  The default is ``30``.
83
84
n85-.. attribute:: XXX Class.maxother
n87+.. attribute:: Repr.maxother
86
87   This limit is used to control the size of object types for which no specific
88   formatting method is available on the :class:`Repr` object. It is applied in a
89   similar manner as :attr:`maxstring`.  The default is ``20``.
90
91
n92-.. method:: XXX Class.repr(obj)
n94+.. method:: Repr.repr(obj)
93
94   The equivalent to the built-in :func:`repr` that uses the formatting imposed by
95   the instance.
96
97
n98-.. method:: XXX Class.repr1(obj, level)
n100+.. method:: Repr.repr1(obj, level)
99
100   Recursive implementation used by :meth:`repr`.  This uses the type of *obj* to
101   determine which formatting method to call, passing it *obj* and *level*.  The
102   type-specific methods should call :meth:`repr1` to perform recursive formatting,
103   with ``level - 1`` for the value of *level* in the recursive  call.
104
105
n106-.. method:: XXX Class.repr_type(obj, level)
n108+.. method:: Repr.repr_TYPE(obj, level)
107   :noindex:
108
109   Formatting methods for specific types are implemented as methods with a name
n110-   based on the type name.  In the method name, *type* is replaced by
n112+   based on the type name.  In the method name, **TYPE** is replaced by
111   ``string.join(string.split(type(obj).__name__, '_'))``. Dispatch to these
112   methods is handled by :meth:`repr1`. Type-specific methods which need to
113   recursively format a value should call ``self.repr1(subobj, level - 1)``.
114
115
116.. _subclassing-reprs:
117
118Subclassing Repr Objects
119------------------------
120
121The use of dynamic dispatching by :meth:`Repr.repr1` allows subclasses of
122:class:`Repr` to add support for additional built-in object types or to modify
123the handling of types already supported. This example shows how special support
124for file objects could be added::
125
n126-   import repr
n128+   import repr as reprlib
127   import sys
128
n129-   class MyRepr(repr.Repr):
n131+   class MyRepr(reprlib.Repr):
130       def repr_file(self, obj, level):
131           if obj.name in ['<stdin>', '<stdout>', '<stderr>']:
132               return obj.name
133           else:
t134-               return `obj`
t136+               return repr(obj)
135
136   aRepr = MyRepr()
137   print aRepr.repr(sys.stdin)          # prints '<stdin>'
138
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op