← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.2-docs-html/_sources/library/reprlib.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

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