Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="ref.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="ref.html" title='Python Reference Manual' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="sequence-methods.html" /> | |
13 | <link rel="prev" href="callable-types.html" /> | |
14 | <link rel="parent" href="specialnames.html" /> | |
15 | <link rel="next" href="sequence-methods.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>3.3.5 Emulating container types</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="3.3.4 Emulating callable objects" | |
25 | href="callable-types.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="3.3 Special method names" | |
28 | href="specialnames.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="3.3.6 Additional methods for" | |
31 | href="sequence-methods.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Reference Manual</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><img src='../icons/blank.png' | |
38 | border='0' height='32' alt='' width='32' /></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="callable-types.html">3.3.4 Emulating callable objects</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="specialnames.html">3.3 Special method names</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="sequence-methods.html">3.3.6 Additional methods for</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION005350000000000000000"></A><A NAME="sequence-types"></A> | |
56 | <BR> | |
57 | 3.3.5 Emulating container types | |
58 | </H2> | |
59 | ||
60 | <P> | |
61 | The following methods can be defined to implement container | |
62 | objects. Containers usually are sequences (such as lists or tuples) | |
63 | or mappings (like dictionaries), but can represent other containers as | |
64 | well. The first set of methods is used either to emulate a | |
65 | sequence or to emulate a mapping; the difference is that for a | |
66 | sequence, the allowable keys should be the integers <var>k</var> for which | |
67 | <code>0 <= <var>k</var> < <var>N</var></code> where <var>N</var> is the length of the | |
68 | sequence, or slice objects, which define a range of items. (For backwards | |
69 | compatibility, the method <tt class="method">__getslice__()</tt> (see below) can also be | |
70 | defined to handle simple, but not extended slices.) It is also recommended | |
71 | that mappings provide the methods <tt class="method">keys()</tt>, <tt class="method">values()</tt>, | |
72 | <tt class="method">items()</tt>, <tt class="method">has_key()</tt>, <tt class="method">get()</tt>, <tt class="method">clear()</tt>, | |
73 | <tt class="method">setdefault()</tt>, <tt class="method">iterkeys()</tt>, <tt class="method">itervalues()</tt>, | |
74 | <tt class="method">iteritems()</tt>, <tt class="method">pop()</tt>, <tt class="method">popitem()</tt>, | |
75 | <tt class="method">copy()</tt>, and <tt class="method">update()</tt> behaving similar to those for | |
76 | Python's standard dictionary objects. The <tt class="module">UserDict</tt> module | |
77 | provides a <tt class="class">DictMixin</tt> class to help create those methods | |
78 | from a base set of <tt class="method">__getitem__()</tt>, <tt class="method">__setitem__()</tt>, | |
79 | <tt class="method">__delitem__()</tt>, and <tt class="method">keys()</tt>. | |
80 | Mutable sequences should provide | |
81 | methods <tt class="method">append()</tt>, <tt class="method">count()</tt>, <tt class="method">index()</tt>, | |
82 | <tt class="method">extend()</tt>, | |
83 | <tt class="method">insert()</tt>, <tt class="method">pop()</tt>, <tt class="method">remove()</tt>, <tt class="method">reverse()</tt> | |
84 | and <tt class="method">sort()</tt>, like Python standard list objects. Finally, | |
85 | sequence types should implement addition (meaning concatenation) and | |
86 | multiplication (meaning repetition) by defining the methods | |
87 | <tt class="method">__add__()</tt>, <tt class="method">__radd__()</tt>, <tt class="method">__iadd__()</tt>, | |
88 | <tt class="method">__mul__()</tt>, <tt class="method">__rmul__()</tt> and <tt class="method">__imul__()</tt> described | |
89 | below; they should not define <tt class="method">__coerce__()</tt> or other numerical | |
90 | operators. It is recommended that both mappings and sequences | |
91 | implement the <tt class="method">__contains__()</tt> method to allow efficient use of | |
92 | the <code>in</code> operator; for mappings, <code>in</code> should be equivalent | |
93 | of <tt class="method">has_key()</tt>; for sequences, it should search through the | |
94 | values. It is further recommended that both mappings and sequences | |
95 | implement the <tt class="method">__iter__()</tt> method to allow efficient iteration | |
96 | through the container; for mappings, <tt class="method">__iter__()</tt> should be | |
97 | the same as <tt class="method">iterkeys()</tt>; for sequences, it should iterate | |
98 | through the values. | |
99 | <a id='l2h-222' xml:id='l2h-222'></a><a id='l2h-224' xml:id='l2h-224'></a> | |
100 | <a id='l2h-226' xml:id='l2h-226'></a> | |
101 | <P> | |
102 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
103 | <td><nobr><b><tt id='l2h-227' xml:id='l2h-227' class="method">__len__</tt></b>(</nobr></td> | |
104 | <td><var>self</var>)</td></tr></table></dt> | |
105 | <dd> | |
106 | Called to implement the built-in function | |
107 | <tt class="function">len()</tt><a id='l2h-228' xml:id='l2h-228'></a>. Should return the length of the | |
108 | object, an integer <code>>=</code> 0. Also, an object that doesn't define a | |
109 | <tt class="method">__nonzero__()</tt> method and whose <tt class="method">__len__()</tt> method | |
110 | returns zero is considered to be false in a Boolean context. | |
111 | <a id='l2h-230' xml:id='l2h-230'></a></dl> | |
112 | ||
113 | <P> | |
114 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
115 | <td><nobr><b><tt id='l2h-231' xml:id='l2h-231' class="method">__getitem__</tt></b>(</nobr></td> | |
116 | <td><var>self, key</var>)</td></tr></table></dt> | |
117 | <dd> | |
118 | Called to implement evaluation of <code><var>self</var>[<var>key</var>]</code>. | |
119 | For sequence types, the accepted keys should be integers and slice | |
120 | objects.<a id='l2h-232' xml:id='l2h-232'></a> Note that | |
121 | the special interpretation of negative indexes (if the class wishes to | |
122 | emulate a sequence type) is up to the <tt class="method">__getitem__()</tt> method. | |
123 | If <var>key</var> is of an inappropriate type, <tt class="exception">TypeError</tt> may be | |
124 | raised; if of a value outside the set of indexes for the sequence | |
125 | (after any special interpretation of negative values), | |
126 | <tt class="exception">IndexError</tt> should be raised. | |
127 | For mapping types, if <var>key</var> is missing (not in the container), | |
128 | <tt class="exception">KeyError</tt> should be raised. | |
129 | <span class="note"><b class="label">Note:</b> | |
130 | <tt class="keyword">for</tt> loops expect that an | |
131 | <tt class="exception">IndexError</tt> will be raised for illegal indexes to allow | |
132 | proper detection of the end of the sequence.</span> | |
133 | </dl> | |
134 | ||
135 | <P> | |
136 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
137 | <td><nobr><b><tt id='l2h-233' xml:id='l2h-233' class="method">__setitem__</tt></b>(</nobr></td> | |
138 | <td><var>self, key, value</var>)</td></tr></table></dt> | |
139 | <dd> | |
140 | Called to implement assignment to <code><var>self</var>[<var>key</var>]</code>. Same | |
141 | note as for <tt class="method">__getitem__()</tt>. This should only be implemented | |
142 | for mappings if the objects support changes to the values for keys, or | |
143 | if new keys can be added, or for sequences if elements can be | |
144 | replaced. The same exceptions should be raised for improper | |
145 | <var>key</var> values as for the <tt class="method">__getitem__()</tt> method. | |
146 | </dl> | |
147 | ||
148 | <P> | |
149 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
150 | <td><nobr><b><tt id='l2h-234' xml:id='l2h-234' class="method">__delitem__</tt></b>(</nobr></td> | |
151 | <td><var>self, key</var>)</td></tr></table></dt> | |
152 | <dd> | |
153 | Called to implement deletion of <code><var>self</var>[<var>key</var>]</code>. Same | |
154 | note as for <tt class="method">__getitem__()</tt>. This should only be implemented | |
155 | for mappings if the objects support removal of keys, or for sequences | |
156 | if elements can be removed from the sequence. The same exceptions | |
157 | should be raised for improper <var>key</var> values as for the | |
158 | <tt class="method">__getitem__()</tt> method. | |
159 | </dl> | |
160 | ||
161 | <P> | |
162 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
163 | <td><nobr><b><tt id='l2h-235' xml:id='l2h-235' class="method">__iter__</tt></b>(</nobr></td> | |
164 | <td><var>self</var>)</td></tr></table></dt> | |
165 | <dd> | |
166 | This method is called when an iterator is required for a container. | |
167 | This method should return a new iterator object that can iterate over | |
168 | all the objects in the container. For mappings, it should iterate | |
169 | over the keys of the container, and should also be made available as | |
170 | the method <tt class="method">iterkeys()</tt>. | |
171 | ||
172 | <P> | |
173 | Iterator objects also need to implement this method; they are required | |
174 | to return themselves. For more information on iterator objects, see | |
175 | ``<a class="ulink" href="../lib/typeiter.html" | |
176 | >Iterator Types</a>'' in the | |
177 | <em class="citetitle"><a | |
178 | href="../lib/lib.html" | |
179 | title="Python Library Reference" | |
180 | >Python Library Reference</a></em>. | |
181 | </dl> | |
182 | ||
183 | <P> | |
184 | The membership test operators (<tt class="keyword">in</tt> and <tt class="keyword">not in</tt>) are | |
185 | normally implemented as an iteration through a sequence. However, | |
186 | container objects can supply the following special method with a more | |
187 | efficient implementation, which also does not require the object be a | |
188 | sequence. | |
189 | ||
190 | <P> | |
191 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
192 | <td><nobr><b><tt id='l2h-236' xml:id='l2h-236' class="method">__contains__</tt></b>(</nobr></td> | |
193 | <td><var>self, item</var>)</td></tr></table></dt> | |
194 | <dd> | |
195 | Called to implement membership test operators. Should return true if | |
196 | <var>item</var> is in <var>self</var>, false otherwise. For mapping objects, | |
197 | this should consider the keys of the mapping rather than the values or | |
198 | the key-item pairs. | |
199 | </dl> | |
200 | ||
201 | <P> | |
202 | ||
203 | <DIV CLASS="navigation"> | |
204 | <div class='online-navigation'> | |
205 | <p></p><hr /> | |
206 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
207 | <tr> | |
208 | <td class='online-navigation'><a rel="prev" title="3.3.4 Emulating callable objects" | |
209 | href="callable-types.html"><img src='../icons/previous.png' | |
210 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
211 | <td class='online-navigation'><a rel="parent" title="3.3 Special method names" | |
212 | href="specialnames.html"><img src='../icons/up.png' | |
213 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
214 | <td class='online-navigation'><a rel="next" title="3.3.6 Additional methods for" | |
215 | href="sequence-methods.html"><img src='../icons/next.png' | |
216 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
217 | <td align="center" width="100%">Python Reference Manual</td> | |
218 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
219 | href="contents.html"><img src='../icons/contents.png' | |
220 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
221 | <td class='online-navigation'><img src='../icons/blank.png' | |
222 | border='0' height='32' alt='' width='32' /></td> | |
223 | <td class='online-navigation'><a rel="index" title="Index" | |
224 | href="genindex.html"><img src='../icons/index.png' | |
225 | border='0' height='32' alt='Index' width='32' /></A></td> | |
226 | </tr></table> | |
227 | <div class='online-navigation'> | |
228 | <b class="navlabel">Previous:</b> | |
229 | <a class="sectref" rel="prev" href="callable-types.html">3.3.4 Emulating callable objects</A> | |
230 | <b class="navlabel">Up:</b> | |
231 | <a class="sectref" rel="parent" href="specialnames.html">3.3 Special method names</A> | |
232 | <b class="navlabel">Next:</b> | |
233 | <a class="sectref" rel="next" href="sequence-methods.html">3.3.6 Additional methods for</A> | |
234 | </div> | |
235 | </div> | |
236 | <hr /> | |
237 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
238 | </DIV> | |
239 | <!--End of Navigation Panel--> | |
240 | <ADDRESS> | |
241 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
242 | </ADDRESS> | |
243 | </BODY> | |
244 | </HTML> |