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="specialnames.html" /> | |
13 | <link rel="prev" href="objects.html" /> | |
14 | <link rel="parent" href="datamodel.html" /> | |
15 | <link rel="next" href="specialnames.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>3.2 The standard type hierarchy</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.1 Objects, values and" | |
25 | href="objects.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. Data model" | |
28 | href="datamodel.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 Special method names" | |
31 | href="specialnames.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="objects.html">3.1 Objects, values and</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="datamodel.html">3. Data model</A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="specialnames.html">3.3 Special method names</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H1><A NAME="SECTION005200000000000000000"></A><A NAME="types"></A><a id='l2h-22' xml:id='l2h-22'></a> | |
56 | <BR> | |
57 | 3.2 The standard type hierarchy | |
58 | </H1> | |
59 | ||
60 | <P> | |
61 | Below is a list of the types that are built into Python. Extension | |
62 | modules (written in C, Java, or other languages, depending on | |
63 | the implementation) can define additional types. Future versions of | |
64 | Python may add types to the type hierarchy (e.g., rational | |
65 | numbers, efficiently stored arrays of integers, etc.). | |
66 | ||
67 | <a id='l2h-23' xml:id='l2h-23'></a><a id='l2h-24' xml:id='l2h-24'></a><a id='l2h-25' xml:id='l2h-25'></a><a id='l2h-26' xml:id='l2h-26'></a> | |
68 | <P> | |
69 | Some of the type descriptions below contain a paragraph listing | |
70 | `special attributes.' These are attributes that provide access to the | |
71 | implementation and are not intended for general use. Their definition | |
72 | may change in the future. | |
73 | ||
74 | <a id='l2h-27' xml:id='l2h-27'></a><a id='l2h-28' xml:id='l2h-28'></a> | |
75 | <P> | |
76 | <DL> | |
77 | <DT><STRONG>None</STRONG></DT> | |
78 | <DD>This type has a single value. There is a single object with this value. | |
79 | This object is accessed through the built-in name <code>None</code>. | |
80 | It is used to signify the absence of a value in many situations, e.g., | |
81 | it is returned from functions that don't explicitly return anything. | |
82 | Its truth value is false. | |
83 | <a id='l2h-29' xml:id='l2h-29'></a> | |
84 | <P> | |
85 | </DD> | |
86 | <DT><STRONG>NotImplemented</STRONG></DT> | |
87 | <DD>This type has a single value. There is a single object with this value. | |
88 | This object is accessed through the built-in name <code>NotImplemented</code>. | |
89 | Numeric methods and rich comparison methods may return this value if | |
90 | they do not implement the operation for the operands provided. (The | |
91 | interpreter will then try the reflected operation, or some other | |
92 | fallback, depending on the operator.) Its truth value is true. | |
93 | <a id='l2h-30' xml:id='l2h-30'></a> | |
94 | <P> | |
95 | </DD> | |
96 | <DT><STRONG>Ellipsis</STRONG></DT> | |
97 | <DD>This type has a single value. There is a single object with this value. | |
98 | This object is accessed through the built-in name <code>Ellipsis</code>. | |
99 | It is used to indicate the presence of the "<tt class="samp">...</tt>" syntax in a | |
100 | slice. Its truth value is true. | |
101 | <a id='l2h-31' xml:id='l2h-31'></a> | |
102 | <P> | |
103 | </DD> | |
104 | <DT><STRONG>Numbers</STRONG></DT> | |
105 | <DD>These are created by numeric literals and returned as results by | |
106 | arithmetic operators and arithmetic built-in functions. Numeric | |
107 | objects are immutable; once created their value never changes. Python | |
108 | numbers are of course strongly related to mathematical numbers, but | |
109 | subject to the limitations of numerical representation in computers. | |
110 | <a id='l2h-32' xml:id='l2h-32'></a> | |
111 | <P> | |
112 | Python distinguishes between integers, floating point numbers, and | |
113 | complex numbers: | |
114 | ||
115 | <P> | |
116 | <DL> | |
117 | <DT><STRONG>Integers</STRONG></DT> | |
118 | <DD>These represent elements from the mathematical set of integers | |
119 | (positive and negative). | |
120 | <a id='l2h-33' xml:id='l2h-33'></a> | |
121 | <P> | |
122 | There are three types of integers: | |
123 | ||
124 | <P> | |
125 | <DL> | |
126 | <DT><STRONG>Plain integers</STRONG></DT> | |
127 | <DD>These represent numbers in the range -2147483648 through 2147483647. | |
128 | (The range may be larger on machines with a larger natural word | |
129 | size, but not smaller.) | |
130 | When the result of an operation would fall outside this range, the | |
131 | result is normally returned as a long integer (in some cases, the | |
132 | exception <tt class="exception">OverflowError</tt> is raised instead). | |
133 | For the purpose of shift and mask operations, integers are assumed to | |
134 | have a binary, 2's complement notation using 32 or more bits, and | |
135 | hiding no bits from the user (i.e., all 4294967296 different bit | |
136 | patterns correspond to different values). | |
137 | <a id='l2h-34' xml:id='l2h-34'></a><a id='l2h-36' xml:id='l2h-36'></a> | |
138 | <P> | |
139 | </DD> | |
140 | <DT><STRONG>Long integers</STRONG></DT> | |
141 | <DD>These represent numbers in an unlimited range, subject to available | |
142 | (virtual) memory only. For the purpose of shift and mask operations, | |
143 | a binary representation is assumed, and negative numbers are | |
144 | represented in a variant of 2's complement which gives the illusion of | |
145 | an infinite string of sign bits extending to the left. | |
146 | <a id='l2h-37' xml:id='l2h-37'></a> | |
147 | <P> | |
148 | </DD> | |
149 | <DT><STRONG>Booleans</STRONG></DT> | |
150 | <DD>These represent the truth values False and True. The two objects | |
151 | representing the values False and True are the only Boolean objects. | |
152 | The Boolean type is a subtype of plain integers, and Boolean values | |
153 | behave like the values 0 and 1, respectively, in almost all contexts, | |
154 | the exception being that when converted to a string, the strings | |
155 | <code>"False"</code> or <code>"True"</code> are returned, respectively. | |
156 | <a id='l2h-38' xml:id='l2h-38'></a><a id='l2h-161' xml:id='l2h-161'></a> | |
157 | ||
158 | <P> | |
159 | </DD> | |
160 | </DL> | |
161 | <P> | |
162 | The rules for integer representation are intended to give the most | |
163 | meaningful interpretation of shift and mask operations involving | |
164 | negative integers and the least surprises when switching between the | |
165 | plain and long integer domains. Any operation except left shift, | |
166 | if it yields a result in the plain integer domain without causing | |
167 | overflow, will yield the same result in the long integer domain or | |
168 | when using mixed operands. | |
169 | <a id='l2h-39' xml:id='l2h-39'></a> | |
170 | <P> | |
171 | </DD> | |
172 | <DT><STRONG>Floating point numbers</STRONG></DT> | |
173 | <DD>These represent machine-level double precision floating point numbers. | |
174 | You are at the mercy of the underlying machine architecture (and | |
175 | C or Java implementation) for the accepted range and handling of overflow. | |
176 | Python does not support single-precision floating point numbers; the | |
177 | savings in processor and memory usage that are usually the reason for using | |
178 | these is dwarfed by the overhead of using objects in Python, so there | |
179 | is no reason to complicate the language with two kinds of floating | |
180 | point numbers. | |
181 | <a id='l2h-40' xml:id='l2h-40'></a><a id='l2h-41' xml:id='l2h-41'></a><a id='l2h-42' xml:id='l2h-42'></a><a id='l2h-43' xml:id='l2h-43'></a> | |
182 | <P> | |
183 | </DD> | |
184 | <DT><STRONG>Complex numbers</STRONG></DT> | |
185 | <DD>These represent complex numbers as a pair of machine-level double | |
186 | precision floating point numbers. The same caveats apply as for | |
187 | floating point numbers. The real and imaginary parts of a complex | |
188 | number <code>z</code> can be retrieved through the read-only attributes | |
189 | <code>z.real</code> and <code>z.imag</code>. | |
190 | <a id='l2h-44' xml:id='l2h-44'></a><a id='l2h-45' xml:id='l2h-45'></a> | |
191 | <P> | |
192 | </DD> | |
193 | </DL> | |
194 | <P> | |
195 | </DD> | |
196 | <DT><STRONG>Sequences</STRONG></DT> | |
197 | <DD>These represent finite ordered sets indexed by non-negative numbers. | |
198 | The built-in function <tt class="function">len()</tt><a id='l2h-46' xml:id='l2h-46'></a> returns the | |
199 | number of items of a sequence. | |
200 | When the length of a sequence is <var>n</var>, the | |
201 | index set contains the numbers 0, 1, ..., <var>n</var>-1. Item | |
202 | <var>i</var> of sequence <var>a</var> is selected by <code><var>a</var>[<var>i</var>]</code>. | |
203 | <a id='l2h-47' xml:id='l2h-47'></a> | |
204 | <P> | |
205 | Sequences also support slicing: <code><var>a</var>[<var>i</var>:<var>j</var>]</code> | |
206 | selects all items with index <var>k</var> such that <var>i</var> <code><=</code> | |
207 | <var>k</var> <code><</code> <var>j</var>. When used as an expression, a slice is a | |
208 | sequence of the same type. This implies that the index set is | |
209 | renumbered so that it starts at 0. | |
210 | ||
211 | <P> | |
212 | Some sequences also support ``extended slicing'' with a third ``step'' | |
213 | parameter: <code><var>a</var>[<var>i</var>:<var>j</var>:<var>k</var>]</code> selects all items | |
214 | of <var>a</var> with index <var>x</var> where <code><var>x</var> = <var>i</var> + | |
215 | <var>n</var>*<var>k</var></code>, <var>n</var> <code>>=</code> <code>0</code> and <var>i</var> <code><=</code> | |
216 | <var>x</var> <code><</code> <var>j</var>. | |
217 | ||
218 | <P> | |
219 | Sequences are distinguished according to their mutability: | |
220 | ||
221 | <P> | |
222 | <DL> | |
223 | <DT><STRONG>Immutable sequences</STRONG></DT> | |
224 | <DD>An object of an immutable sequence type cannot change once it is | |
225 | created. (If the object contains references to other objects, | |
226 | these other objects may be mutable and may be changed; however, | |
227 | the collection of objects directly referenced by an immutable object | |
228 | cannot change.) | |
229 | <a id='l2h-48' xml:id='l2h-48'></a><a id='l2h-49' xml:id='l2h-49'></a> | |
230 | <P> | |
231 | The following types are immutable sequences: | |
232 | ||
233 | <P> | |
234 | <DL> | |
235 | <DT><STRONG>Strings</STRONG></DT> | |
236 | <DD>The items of a string are characters. There is no separate | |
237 | character type; a character is represented by a string of one item. | |
238 | Characters represent (at least) 8-bit bytes. The built-in | |
239 | functions <tt class="function">chr()</tt><a id='l2h-50' xml:id='l2h-50'></a> and | |
240 | <tt class="function">ord()</tt><a id='l2h-51' xml:id='l2h-51'></a> convert between characters and | |
241 | nonnegative integers representing the byte values. Bytes with the | |
242 | values 0-127 usually represent the corresponding ASCII values, but | |
243 | the interpretation of values is up to the program. The string | |
244 | data type is also used to represent arrays of bytes, e.g., to hold data | |
245 | read from a file. | |
246 | <a id='l2h-52' xml:id='l2h-52'></a> | |
247 | <P> | |
248 | (On systems whose native character set is not ASCII, strings may use | |
249 | EBCDIC in their internal representation, provided the functions | |
250 | <tt class="function">chr()</tt> and <tt class="function">ord()</tt> implement a mapping between ASCII and | |
251 | EBCDIC, and string comparison preserves the ASCII order. | |
252 | Or perhaps someone can propose a better rule?) | |
253 | <a id='l2h-53' xml:id='l2h-53'></a><a id='l2h-54' xml:id='l2h-54'></a><a id='l2h-55' xml:id='l2h-55'></a> | |
254 | <P> | |
255 | </DD> | |
256 | <DT><STRONG>Unicode</STRONG></DT> | |
257 | <DD>The items of a Unicode object are Unicode code units. A Unicode code | |
258 | unit is represented by a Unicode object of one item and can hold | |
259 | either a 16-bit or 32-bit value representing a Unicode ordinal (the | |
260 | maximum value for the ordinal is given in <code>sys.maxunicode</code>, and | |
261 | depends on how Python is configured at compile time). Surrogate pairs | |
262 | may be present in the Unicode object, and will be reported as two | |
263 | separate items. The built-in functions | |
264 | <tt class="function">unichr()</tt><a id='l2h-56' xml:id='l2h-56'></a> and | |
265 | <tt class="function">ord()</tt><a id='l2h-57' xml:id='l2h-57'></a> convert between code units and | |
266 | nonnegative integers representing the Unicode ordinals as defined in | |
267 | the Unicode Standard 3.0. Conversion from and to other encodings are | |
268 | possible through the Unicode method <tt class="method">encode()</tt> and the built-in | |
269 | function <tt class="function">unicode()</tt>.<a id='l2h-58' xml:id='l2h-58'></a><a id='l2h-59' xml:id='l2h-59'></a> | |
270 | <P> | |
271 | </DD> | |
272 | <DT><STRONG>Tuples</STRONG></DT> | |
273 | <DD>The items of a tuple are arbitrary Python objects. | |
274 | Tuples of two or more items are formed by comma-separated lists | |
275 | of expressions. A tuple of one item (a `singleton') can be formed | |
276 | by affixing a comma to an expression (an expression by itself does | |
277 | not create a tuple, since parentheses must be usable for grouping of | |
278 | expressions). An empty tuple can be formed by an empty pair of | |
279 | parentheses. | |
280 | <a id='l2h-60' xml:id='l2h-60'></a><a id='l2h-61' xml:id='l2h-61'></a><a id='l2h-62' xml:id='l2h-62'></a> | |
281 | <P> | |
282 | </DD> | |
283 | </DL> | |
284 | <P> | |
285 | </DD> | |
286 | <DT><STRONG>Mutable sequences</STRONG></DT> | |
287 | <DD>Mutable sequences can be changed after they are created. The | |
288 | subscription and slicing notations can be used as the target of | |
289 | assignment and <tt class="keyword">del</tt> (delete) statements. | |
290 | <a id='l2h-63' xml:id='l2h-63'></a><a id='l2h-64' xml:id='l2h-64'></a><a id='l2h-65' xml:id='l2h-65'></a> | |
291 | <a id='l2h-66' xml:id='l2h-66'></a> | |
292 | ||
293 | <P> | |
294 | There is currently a single intrinsic mutable sequence type: | |
295 | ||
296 | <P> | |
297 | <DL> | |
298 | <DT><STRONG>Lists</STRONG></DT> | |
299 | <DD>The items of a list are arbitrary Python objects. Lists are formed | |
300 | by placing a comma-separated list of expressions in square brackets. | |
301 | (Note that there are no special cases needed to form lists of length 0 | |
302 | or 1.) | |
303 | <a id='l2h-67' xml:id='l2h-67'></a> | |
304 | <P> | |
305 | </DD> | |
306 | </DL> | |
307 | <P> | |
308 | The extension module <tt class="module">array</tt><a id='l2h-162' xml:id='l2h-162'></a> provides an | |
309 | additional example of a mutable sequence type. | |
310 | ||
311 | <P> | |
312 | </DD> | |
313 | </DL> | |
314 | <P> | |
315 | </DD> | |
316 | <DT><STRONG>Mappings</STRONG></DT> | |
317 | <DD>These represent finite sets of objects indexed by arbitrary index sets. | |
318 | The subscript notation <code>a[k]</code> selects the item indexed | |
319 | by <code>k</code> from the mapping <code>a</code>; this can be used in | |
320 | expressions and as the target of assignments or <tt class="keyword">del</tt> statements. | |
321 | The built-in function <tt class="function">len()</tt> returns the number of items | |
322 | in a mapping. | |
323 | <a id='l2h-68' xml:id='l2h-68'></a> | |
324 | <a id='l2h-69' xml:id='l2h-69'></a> | |
325 | <P> | |
326 | There is currently a single intrinsic mapping type: | |
327 | ||
328 | <P> | |
329 | <DL> | |
330 | <DT><STRONG>Dictionaries</STRONG></DT> | |
331 | <DD>These<a id='l2h-70' xml:id='l2h-70'></a> represent finite sets of objects indexed by | |
332 | nearly arbitrary values. The only types of values not acceptable as | |
333 | keys are values containing lists or dictionaries or other mutable | |
334 | types that are compared by value rather than by object identity, the | |
335 | reason being that the efficient implementation of dictionaries | |
336 | requires a key's hash value to remain constant. | |
337 | Numeric types used for keys obey the normal rules for numeric | |
338 | comparison: if two numbers compare equal (e.g., <code>1</code> and | |
339 | <code>1.0</code>) then they can be used interchangeably to index the same | |
340 | dictionary entry. | |
341 | ||
342 | <P> | |
343 | Dictionaries are mutable; they can be created by the | |
344 | <code>{...}</code> notation (see section <A href="dict.html#dict">5.2.6</A>, ``Dictionary | |
345 | Displays''). | |
346 | ||
347 | <P> | |
348 | The extension modules <tt class="module">dbm</tt><a id='l2h-163' xml:id='l2h-163'></a>, | |
349 | <tt class="module">gdbm</tt><a id='l2h-164' xml:id='l2h-164'></a>, <tt class="module">bsddb</tt><a id='l2h-165' xml:id='l2h-165'></a> | |
350 | provide additional examples of mapping types. | |
351 | ||
352 | <P> | |
353 | </DD> | |
354 | </DL> | |
355 | <P> | |
356 | </DD> | |
357 | <DT><STRONG>Callable types</STRONG></DT> | |
358 | <DD>These<a id='l2h-71' xml:id='l2h-71'></a> are the types to which the function call | |
359 | operation (see section <A href="calls.html#calls">5.3.4</A>, ``Calls'') can be applied: | |
360 | <a id='l2h-72' xml:id='l2h-72'></a><a id='l2h-73' xml:id='l2h-73'></a> | |
361 | <P> | |
362 | <DL> | |
363 | <DT><STRONG>User-defined functions</STRONG></DT> | |
364 | <DD>A user-defined function object is created by a function definition | |
365 | (see section <A href="function.html#function">7.5</A>, ``Function definitions''). It should be | |
366 | called with an argument | |
367 | list containing the same number of items as the function's formal | |
368 | parameter list. | |
369 | <a id='l2h-74' xml:id='l2h-74'></a><a id='l2h-75' xml:id='l2h-75'></a><a id='l2h-76' xml:id='l2h-76'></a> | |
370 | <P> | |
371 | Special attributes: | |
372 | ||
373 | <P> | |
374 | <div class="center"><table class="realtable"> | |
375 | <thead> | |
376 | <tr> | |
377 | <th class="left" >Attribute</th> | |
378 | <th>Meaning</th> | |
379 | <th></th> | |
380 | </tr> | |
381 | </thead> | |
382 | <tbody> | |
383 | <tr><td class="left" valign="baseline"><tt class="member">func_doc</tt></td> | |
384 | <td>The function's documentation string, or | |
385 | <code>None</code> if unavailable</td> | |
386 | <td>Writable</td></tr><P> | |
387 | ||
388 | <tr><td class="left" valign="baseline"><tt class="member">__doc__</tt></td> | |
389 | <td>Another way of spelling | |
390 | <tt class="member">func_doc</tt></td> | |
391 | <td>Writable</td></tr><P> | |
392 | ||
393 | <tr><td class="left" valign="baseline"><tt class="member">func_name</tt></td> | |
394 | <td>The function's name</td> | |
395 | <td>Writable</td></tr><P> | |
396 | ||
397 | <tr><td class="left" valign="baseline"><tt class="member">__name__</tt></td> | |
398 | <td>Another way of spelling | |
399 | <tt class="member">func_name</tt></td> | |
400 | <td>Writable</td></tr><P> | |
401 | ||
402 | <tr><td class="left" valign="baseline"><tt class="member">__module__</tt></td> | |
403 | <td>The name of the module the function was defined | |
404 | in, or <code>None</code> if unavailable.</td> | |
405 | <td>Writable</td></tr><P> | |
406 | ||
407 | <tr><td class="left" valign="baseline"><tt class="member">func_defaults</tt></td> | |
408 | <td>A tuple containing default argument values | |
409 | for those arguments that have defaults, or <code>None</code> if no | |
410 | arguments have a default value</td> | |
411 | <td>Writable</td></tr><P> | |
412 | ||
413 | <tr><td class="left" valign="baseline"><tt class="member">func_code</tt></td> | |
414 | <td>The code object representing the compiled | |
415 | function body.</td> | |
416 | <td>Writable</td></tr><P> | |
417 | ||
418 | <tr><td class="left" valign="baseline"><tt class="member">func_globals</tt></td> | |
419 | <td>A reference to the dictionary that holds the | |
420 | function's global variables -- the global namespace of the module | |
421 | in which the function was defined.</td> | |
422 | <td>Read-only</td></tr><P> | |
423 | ||
424 | <tr><td class="left" valign="baseline"><tt class="member">func_dict</tt></td> | |
425 | <td>The namespace supporting arbitrary function | |
426 | attributes.</td> | |
427 | <td>Writable</td></tr><P> | |
428 | ||
429 | <tr><td class="left" valign="baseline"><tt class="member">func_closure</tt></td> | |
430 | <td><code>None</code> or a tuple of cells that contain | |
431 | bindings for the function's free variables.</td> | |
432 | <td>Read-only</td></tr></tbody> | |
433 | </table></div> | |
434 | ||
435 | <P> | |
436 | Most of the attributes labelled ``Writable'' check the type of the | |
437 | assigned value. | |
438 | ||
439 | <P> | |
440 | ||
441 | <span class="versionnote">Changed in version 2.4: | |
442 | <code>func_name</code> is now writable.</span> | |
443 | ||
444 | <P> | |
445 | Function objects also support getting and setting arbitrary | |
446 | attributes, which can be used, for example, to attach metadata to | |
447 | functions. Regular attribute dot-notation is used to get and set such | |
448 | attributes. <em>Note that the current implementation only supports | |
449 | function attributes on user-defined functions. Function attributes on | |
450 | built-in functions may be supported in the future.</em> | |
451 | ||
452 | <P> | |
453 | Additional information about a function's definition can be retrieved | |
454 | from its code object; see the description of internal types below. | |
455 | ||
456 | <P> | |
457 | <a id='l2h-78' xml:id='l2h-78'></a><a id='l2h-79' xml:id='l2h-79'></a> | |
458 | <P> | |
459 | </DD> | |
460 | <DT><STRONG>User-defined methods</STRONG></DT> | |
461 | <DD>A user-defined method object combines a class, a class instance (or | |
462 | <code>None</code>) and any callable object (normally a user-defined | |
463 | function). | |
464 | <a id='l2h-80' xml:id='l2h-80'></a><a id='l2h-81' xml:id='l2h-81'></a><a id='l2h-82' xml:id='l2h-82'></a> | |
465 | <P> | |
466 | Special read-only attributes: <tt class="member">im_self</tt> is the class instance | |
467 | object, <tt class="member">im_func</tt> is the function object; | |
468 | <tt class="member">im_class</tt> is the class of <tt class="member">im_self</tt> for bound methods | |
469 | or the class that asked for the method for unbound methods; | |
470 | <tt class="member">__doc__</tt> is the method's documentation (same as | |
471 | <code>im_func.__doc__</code>); <tt class="member">__name__</tt> is the method name (same as | |
472 | <code>im_func.__name__</code>); <tt class="member">__module__</tt> is the name of the | |
473 | module the method was defined in, or <code>None</code> if unavailable. | |
474 | ||
475 | <span class="versionnote">Changed in version 2.2: | |
476 | <tt class="member">im_self</tt> used to refer to the class that | |
477 | defined the method.</span> | |
478 | ||
479 | <a id='l2h-84' xml:id='l2h-84'></a> | |
480 | <P> | |
481 | Methods also support accessing (but not setting) the arbitrary | |
482 | function attributes on the underlying function object. | |
483 | ||
484 | <P> | |
485 | User-defined method objects may be created when getting an attribute | |
486 | of a class (perhaps via an instance of that class), if that attribute | |
487 | is a user-defined function object, an unbound user-defined method object, | |
488 | or a class method object. | |
489 | When the attribute is a user-defined method object, a new | |
490 | method object is only created if the class from which it is being | |
491 | retrieved is the same as, or a derived class of, the class stored | |
492 | in the original method object; otherwise, the original method object | |
493 | is used as it is. | |
494 | ||
495 | <P> | |
496 | When a user-defined method object is created by retrieving | |
497 | a user-defined function object from a class, its <tt class="member">im_self</tt> | |
498 | attribute is <code>None</code> and the method object is said to be unbound. | |
499 | When one is created by retrieving a user-defined function object | |
500 | from a class via one of its instances, its <tt class="member">im_self</tt> attribute | |
501 | is the instance, and the method object is said to be bound. | |
502 | In either case, the new method's <tt class="member">im_class</tt> attribute | |
503 | is the class from which the retrieval takes place, and | |
504 | its <tt class="member">im_func</tt> attribute is the original function object. | |
505 | <a id='l2h-86' xml:id='l2h-86'></a> | |
506 | <P> | |
507 | When a user-defined method object is created by retrieving another | |
508 | method object from a class or instance, the behaviour is the same | |
509 | as for a function object, except that the <tt class="member">im_func</tt> attribute | |
510 | of the new instance is not the original method object but its | |
511 | <tt class="member">im_func</tt> attribute. | |
512 | <a id='l2h-88' xml:id='l2h-88'></a> | |
513 | <P> | |
514 | When a user-defined method object is created by retrieving a | |
515 | class method object from a class or instance, its <tt class="member">im_self</tt> | |
516 | attribute is the class itself (the same as the <tt class="member">im_class</tt> | |
517 | attribute), and its <tt class="member">im_func</tt> attribute is the function | |
518 | object underlying the class method. | |
519 | <a id='l2h-90' xml:id='l2h-90'></a> | |
520 | <P> | |
521 | When an unbound user-defined method object is called, the underlying | |
522 | function (<tt class="member">im_func</tt>) is called, with the restriction that the | |
523 | first argument must be an instance of the proper class | |
524 | (<tt class="member">im_class</tt>) or of a derived class thereof. | |
525 | ||
526 | <P> | |
527 | When a bound user-defined method object is called, the underlying | |
528 | function (<tt class="member">im_func</tt>) is called, inserting the class instance | |
529 | (<tt class="member">im_self</tt>) in front of the argument list. For instance, when | |
530 | <tt class="class">C</tt> is a class which contains a definition for a function | |
531 | <tt class="method">f()</tt>, and <code>x</code> is an instance of <tt class="class">C</tt>, calling | |
532 | <code>x.f(1)</code> is equivalent to calling <code>C.f(x, 1)</code>. | |
533 | ||
534 | <P> | |
535 | When a user-defined method object is derived from a class method object, | |
536 | the ``class instance'' stored in <tt class="member">im_self</tt> will actually be the | |
537 | class itself, so that calling either <code>x.f(1)</code> or <code>C.f(1)</code> is | |
538 | equivalent to calling <code>f(C,1)</code> where <code>f</code> is the underlying | |
539 | function. | |
540 | ||
541 | <P> | |
542 | Note that the transformation from function object to (unbound or | |
543 | bound) method object happens each time the attribute is retrieved from | |
544 | the class or instance. In some cases, a fruitful optimization is to | |
545 | assign the attribute to a local variable and call that local variable. | |
546 | Also notice that this transformation only happens for user-defined | |
547 | functions; other callable objects (and all non-callable objects) are | |
548 | retrieved without transformation. It is also important to note that | |
549 | user-defined functions which are attributes of a class instance are | |
550 | not converted to bound methods; this <em>only</em> happens when the | |
551 | function is an attribute of the class. | |
552 | ||
553 | <P> | |
554 | </DD> | |
555 | <DT><STRONG>Generator functions<a id='l2h-91' xml:id='l2h-91'></a></STRONG></DT> | |
556 | <DD>A function or method which uses the <tt class="keyword">yield</tt> statement (see | |
557 | section <A href="yield.html#yield">6.8</A>, ``The <tt class="keyword">yield</tt> statement'') is called a | |
558 | <i class="dfn">generator function</i>. Such a function, when called, always | |
559 | returns an iterator object which can be used to execute the body of | |
560 | the function: calling the iterator's <tt class="method">next()</tt> method will | |
561 | cause the function to execute until it provides a value using the | |
562 | <tt class="keyword">yield</tt> statement. When the function executes a | |
563 | <tt class="keyword">return</tt> statement or falls off the end, a | |
564 | <tt class="exception">StopIteration</tt> exception is raised and the iterator will | |
565 | have reached the end of the set of values to be returned. | |
566 | ||
567 | <P> | |
568 | </DD> | |
569 | <DT><STRONG>Built-in functions</STRONG></DT> | |
570 | <DD>A built-in function object is a wrapper around a C function. Examples | |
571 | of built-in functions are <tt class="function">len()</tt> and <tt class="function">math.sin()</tt> | |
572 | (<tt class="module">math</tt> is a standard built-in module). | |
573 | The number and type of the arguments are | |
574 | determined by the C function. | |
575 | Special read-only attributes: <tt class="member">__doc__</tt> is the function's | |
576 | documentation string, or <code>None</code> if unavailable; <tt class="member">__name__</tt> | |
577 | is the function's name; <tt class="member">__self__</tt> is set to <code>None</code> (but see | |
578 | the next item); <tt class="member">__module__</tt> is the name of the module the | |
579 | function was defined in or <code>None</code> if unavailable. | |
580 | <a id='l2h-92' xml:id='l2h-92'></a><a id='l2h-93' xml:id='l2h-93'></a><a id='l2h-94' xml:id='l2h-94'></a> | |
581 | <P> | |
582 | </DD> | |
583 | <DT><STRONG>Built-in methods</STRONG></DT> | |
584 | <DD>This is really a different disguise of a built-in function, this time | |
585 | containing an object passed to the C function as an implicit extra | |
586 | argument. An example of a built-in method is | |
587 | <code><var>alist</var>.append()</code>, assuming | |
588 | <var>alist</var> is a list object. | |
589 | In this case, the special read-only attribute <tt class="member">__self__</tt> is set | |
590 | to the object denoted by <var>list</var>. | |
591 | <a id='l2h-95' xml:id='l2h-95'></a><a id='l2h-96' xml:id='l2h-96'></a><a id='l2h-97' xml:id='l2h-97'></a> | |
592 | <P> | |
593 | </DD> | |
594 | <DT><STRONG>Class Types</STRONG></DT> | |
595 | <DD>Class types, or ``new-style classes,'' are callable. These objects | |
596 | normally act as factories for new instances of themselves, but | |
597 | variations are possible for class types that override | |
598 | <tt class="method">__new__()</tt>. The arguments of the call are passed to | |
599 | <tt class="method">__new__()</tt> and, in the typical case, to <tt class="method">__init__()</tt> to | |
600 | initialize the new instance. | |
601 | ||
602 | <P> | |
603 | </DD> | |
604 | <DT><STRONG>Classic Classes</STRONG></DT> | |
605 | <DD>Class objects are described below. When a class object is called, | |
606 | a new class instance (also described below) is created and | |
607 | returned. This implies a call to the class's <tt class="method">__init__()</tt> method | |
608 | if it has one. Any arguments are passed on to the <tt class="method">__init__()</tt> | |
609 | method. If there is no <tt class="method">__init__()</tt> method, the class must be called | |
610 | without arguments. | |
611 | <a id='l2h-99' xml:id='l2h-99'></a><a id='l2h-100' xml:id='l2h-100'></a><a id='l2h-101' xml:id='l2h-101'></a><a id='l2h-102' xml:id='l2h-102'></a><a id='l2h-103' xml:id='l2h-103'></a> | |
612 | <P> | |
613 | </DD> | |
614 | <DT><STRONG>Class instances</STRONG></DT> | |
615 | <DD>Class instances are described below. Class instances are callable | |
616 | only when the class has a <tt class="method">__call__()</tt> method; <code>x(arguments)</code> | |
617 | is a shorthand for <code>x.__call__(arguments)</code>. | |
618 | ||
619 | <P> | |
620 | </DD> | |
621 | </DL> | |
622 | ||
623 | <P> | |
624 | </DD> | |
625 | <DT><STRONG>Modules</STRONG></DT> | |
626 | <DD>Modules are imported by the <tt class="keyword">import</tt> statement (see | |
627 | section <A href="import.html#import">6.12</A>, ``The <tt class="keyword">import</tt> statement'').<a id='l2h-104' xml:id='l2h-104'></a><a id='l2h-105' xml:id='l2h-105'></a>A module object has a namespace implemented by a dictionary object | |
628 | (this is the dictionary referenced by the func_globals attribute of | |
629 | functions defined in the module). Attribute references are translated | |
630 | to lookups in this dictionary, e.g., <code>m.x</code> is equivalent to | |
631 | <code>m.__dict__["x"]</code>. | |
632 | A module object does not contain the code object used to | |
633 | initialize the module (since it isn't needed once the initialization | |
634 | is done). | |
635 | ||
636 | <P> | |
637 | Attribute assignment updates the module's namespace dictionary, | |
638 | e.g., "<tt class="samp">m.x = 1</tt>" is equivalent to "<tt class="samp">m.__dict__["x"] = 1</tt>". | |
639 | ||
640 | <P> | |
641 | Special read-only attribute: <tt class="member">__dict__</tt> is the module's | |
642 | namespace as a dictionary object. | |
643 | <a id='l2h-107' xml:id='l2h-107'></a> | |
644 | <P> | |
645 | Predefined (writable) attributes: <tt class="member">__name__</tt> | |
646 | is the module's name; <tt class="member">__doc__</tt> is the | |
647 | module's documentation string, or | |
648 | <code>None</code> if unavailable; <tt class="member">__file__</tt> is the pathname of the | |
649 | file from which the module was loaded, if it was loaded from a file. | |
650 | The <tt class="member">__file__</tt> attribute is not present for C modules that are | |
651 | statically linked into the interpreter; for extension modules loaded | |
652 | dynamically from a shared library, it is the pathname of the shared | |
653 | library file. | |
654 | <a id='l2h-109' xml:id='l2h-109'></a><a id='l2h-110' xml:id='l2h-110'></a> | |
655 | <P> | |
656 | </DD> | |
657 | <DT><STRONG>Classes</STRONG></DT> | |
658 | <DD>Class objects are created by class definitions (see | |
659 | section <A href="class.html#class">7.6</A>, ``Class definitions''). | |
660 | A class has a namespace implemented by a dictionary object. | |
661 | Class attribute references are translated to | |
662 | lookups in this dictionary, | |
663 | e.g., "<tt class="samp">C.x</tt>" is translated to "<tt class="samp">C.__dict__["x"]</tt>". | |
664 | When the attribute name is not found | |
665 | there, the attribute search continues in the base classes. The search | |
666 | is depth-first, left-to-right in the order of occurrence in the | |
667 | base class list. | |
668 | ||
669 | <P> | |
670 | When a class attribute reference (for class <tt class="class">C</tt>, say) | |
671 | would yield a user-defined function object or | |
672 | an unbound user-defined method object whose associated class is either | |
673 | <tt class="class">C</tt> or one of its base classes, it is transformed into an unbound | |
674 | user-defined method object whose <tt class="member">im_class</tt> attribute is <tt class="class">C</tt>. | |
675 | When it would yield a class method object, it is transformed into | |
676 | a bound user-defined method object whose <tt class="member">im_class</tt> and | |
677 | <tt class="member">im_self</tt> attributes are both <tt class="class">C</tt>. When it would yield | |
678 | a static method object, it is transformed into the object wrapped | |
679 | by the static method object. See section <A href="descriptors.html#descriptors">3.3.2</A> for another | |
680 | way in which attributes retrieved from a class may differ from those | |
681 | actually contained in its <tt class="member">__dict__</tt>. | |
682 | <a id='l2h-111' xml:id='l2h-111'></a><a id='l2h-112' xml:id='l2h-112'></a><a id='l2h-113' xml:id='l2h-113'></a><a id='l2h-114' xml:id='l2h-114'></a><a id='l2h-115' xml:id='l2h-115'></a><a id='l2h-116' xml:id='l2h-116'></a> | |
683 | <P> | |
684 | Class attribute assignments update the class's dictionary, never the | |
685 | dictionary of a base class. | |
686 | <a id='l2h-117' xml:id='l2h-117'></a> | |
687 | <P> | |
688 | A class object can be called (see above) to yield a class instance (see | |
689 | below). | |
690 | <a id='l2h-118' xml:id='l2h-118'></a> | |
691 | <P> | |
692 | Special attributes: <tt class="member">__name__</tt> is the class name; | |
693 | <tt class="member">__module__</tt> is the module name in which the class was defined; | |
694 | <tt class="member">__dict__</tt> is the dictionary containing the class's namespace; | |
695 | <tt class="member">__bases__</tt> is a tuple (possibly empty or a singleton) | |
696 | containing the base classes, in the order of their occurrence in the | |
697 | base class list; <tt class="member">__doc__</tt> is the class's documentation string, | |
698 | or None if undefined. | |
699 | <a id='l2h-120' xml:id='l2h-120'></a> | |
700 | <P> | |
701 | </DD> | |
702 | <DT><STRONG>Class instances</STRONG></DT> | |
703 | <DD>A class instance is created by calling a class object (see above). | |
704 | A class instance has a namespace implemented as a dictionary which | |
705 | is the first place in which | |
706 | attribute references are searched. When an attribute is not found | |
707 | there, and the instance's class has an attribute by that name, | |
708 | the search continues with the class attributes. If a class attribute | |
709 | is found that is a user-defined function object or an unbound | |
710 | user-defined method object whose associated class is the class | |
711 | (call it <tt class="class">C</tt>) of the instance for which the attribute reference | |
712 | was initiated or one of its bases, | |
713 | it is transformed into a bound user-defined method object whose | |
714 | <tt class="member">im_class</tt> attribute is <tt class="class">C</tt> whose <tt class="member">im_self</tt> attribute | |
715 | is the instance. Static method and class method objects are also | |
716 | transformed, as if they had been retrieved from class <tt class="class">C</tt>; | |
717 | see above under ``Classes''. See section <A href="descriptors.html#descriptors">3.3.2</A> for | |
718 | another way in which attributes of a class retrieved via its | |
719 | instances may differ from the objects actually stored in the | |
720 | class's <tt class="member">__dict__</tt>. | |
721 | If no class attribute is found, and the object's class has a | |
722 | <tt class="method">__getattr__()</tt> method, that is called to satisfy the lookup. | |
723 | <a id='l2h-121' xml:id='l2h-121'></a><a id='l2h-122' xml:id='l2h-122'></a><a id='l2h-123' xml:id='l2h-123'></a><a id='l2h-124' xml:id='l2h-124'></a> | |
724 | <P> | |
725 | Attribute assignments and deletions update the instance's dictionary, | |
726 | never a class's dictionary. If the class has a <tt class="method">__setattr__()</tt> or | |
727 | <tt class="method">__delattr__()</tt> method, this is called instead of updating the | |
728 | instance dictionary directly. | |
729 | <a id='l2h-125' xml:id='l2h-125'></a> | |
730 | <P> | |
731 | Class instances can pretend to be numbers, sequences, or mappings if | |
732 | they have methods with certain special names. See | |
733 | section <A href="specialnames.html#specialnames">3.3</A>, ``Special method names.'' | |
734 | <a id='l2h-126' xml:id='l2h-126'></a><a id='l2h-127' xml:id='l2h-127'></a><a id='l2h-128' xml:id='l2h-128'></a> | |
735 | <P> | |
736 | Special attributes: <tt class="member">__dict__</tt> is the attribute | |
737 | dictionary; <tt class="member">__class__</tt> is the instance's class. | |
738 | <a id='l2h-130' xml:id='l2h-130'></a> | |
739 | <P> | |
740 | </DD> | |
741 | <DT><STRONG>Files</STRONG></DT> | |
742 | <DD>A file<a id='l2h-131' xml:id='l2h-131'></a> object represents an open file. File objects are | |
743 | created by the <tt class="function">open()</tt><a id='l2h-132' xml:id='l2h-132'></a> built-in function, | |
744 | and also by | |
745 | <a id='l2h-134' xml:id='l2h-134'></a><tt class="function">os.popen()</tt>, | |
746 | <tt class="function">os.fdopen()</tt>, and the | |
747 | <tt class="method">makefile()</tt><a id='l2h-136' xml:id='l2h-136'></a>method of socket objects (and perhaps by other functions or methods | |
748 | provided by extension modules). The objects | |
749 | <code>sys.stdin</code>, | |
750 | <code>sys.stdout</code> and | |
751 | <code>sys.stderr</code> are initialized to file objects | |
752 | corresponding to the interpreter's standard<a id='l2h-166' xml:id='l2h-166'></a> input, output | |
753 | and error streams. See the <em class="citetitle"><a | |
754 | href="../lib/lib.html" | |
755 | title="Python Library | |
756 | Reference" | |
757 | >Python Library | |
758 | Reference</a></em> for complete documentation of file objects. | |
759 | <a id='l2h-138' xml:id='l2h-138'></a> | |
760 | <P> | |
761 | </DD> | |
762 | <DT><STRONG>Internal types</STRONG></DT> | |
763 | <DD>A few types used internally by the interpreter are exposed to the user. | |
764 | Their definitions may change with future versions of the interpreter, | |
765 | but they are mentioned here for completeness. | |
766 | ||
767 | <P> | |
768 | <DL> | |
769 | <DT><STRONG>Code objects</STRONG></DT> | |
770 | <DD>Code objects represent <em>byte-compiled</em> executable Python code, or | |
771 | <em>bytecode</em>. | |
772 | The difference between a code | |
773 | object and a function object is that the function object contains an | |
774 | explicit reference to the function's globals (the module in which it | |
775 | was defined), while a code object contains no context; | |
776 | also the default argument values are stored in the function object, | |
777 | not in the code object (because they represent values calculated at | |
778 | run-time). Unlike function objects, code objects are immutable and | |
779 | contain no references (directly or indirectly) to mutable objects. | |
780 | <a id='l2h-139' xml:id='l2h-139'></a> | |
781 | <P> | |
782 | Special read-only attributes: <tt class="member">co_name</tt> gives the function | |
783 | name; <tt class="member">co_argcount</tt> is the number of positional arguments | |
784 | (including arguments with default values); <tt class="member">co_nlocals</tt> is the | |
785 | number of local variables used by the function (including arguments); | |
786 | <tt class="member">co_varnames</tt> is a tuple containing the names of the local | |
787 | variables (starting with the argument names); <tt class="member">co_cellvars</tt> is | |
788 | a tuple containing the names of local variables that are referenced by | |
789 | nested functions; <tt class="member">co_freevars</tt> is a tuple containing the names | |
790 | of free variables; <tt class="member">co_code</tt> is a string representing the | |
791 | sequence of bytecode instructions; | |
792 | <tt class="member">co_consts</tt> is a tuple containing the literals used by the | |
793 | bytecode; <tt class="member">co_names</tt> is a tuple containing the names used by | |
794 | the bytecode; <tt class="member">co_filename</tt> is the filename from which the code | |
795 | was compiled; <tt class="member">co_firstlineno</tt> is the first line number of the | |
796 | function; <tt class="member">co_lnotab</tt> is a string encoding the mapping from | |
797 | byte code offsets to line numbers (for details see the source code of | |
798 | the interpreter); <tt class="member">co_stacksize</tt> is the required stack size | |
799 | (including local variables); <tt class="member">co_flags</tt> is an integer encoding | |
800 | a number of flags for the interpreter. | |
801 | ||
802 | <P> | |
803 | <a id='l2h-141' xml:id='l2h-141'></a> | |
804 | <P> | |
805 | The following flag bits are defined for <tt class="member">co_flags</tt>: bit | |
806 | <code>0x04</code> is set if the function uses the "<tt class="samp">*arguments</tt>" syntax | |
807 | to accept an arbitrary number of positional arguments; bit | |
808 | <code>0x08</code> is set if the function uses the "<tt class="samp">**keywords</tt>" syntax | |
809 | to accept arbitrary keyword arguments; bit <code>0x20</code> is set if the | |
810 | function is a generator. | |
811 | <a id='l2h-142' xml:id='l2h-142'></a> | |
812 | <P> | |
813 | Future feature declarations ("<tt class="samp">from __future__ import division</tt>") | |
814 | also use bits in <tt class="member">co_flags</tt> to indicate whether a code object | |
815 | was compiled with a particular feature enabled: bit <code>0x2000</code> is | |
816 | set if the function was compiled with future division enabled; bits | |
817 | <code>0x10</code> and <code>0x1000</code> were used in earlier versions of Python. | |
818 | ||
819 | <P> | |
820 | Other bits in <tt class="member">co_flags</tt> are reserved for internal use. | |
821 | ||
822 | <P> | |
823 | If<a id='l2h-167' xml:id='l2h-167'></a> a code object represents a function, | |
824 | the first item in | |
825 | <tt class="member">co_consts</tt> is the documentation string of the function, or | |
826 | <code>None</code> if undefined. | |
827 | ||
828 | <P> | |
829 | </DD> | |
830 | <DT><STRONG>Frame objects</STRONG></DT> | |
831 | <DD>Frame objects represent execution frames. They may occur in traceback | |
832 | objects (see below). | |
833 | <a id='l2h-143' xml:id='l2h-143'></a> | |
834 | <P> | |
835 | Special read-only attributes: <tt class="member">f_back</tt> is to the previous | |
836 | stack frame (towards the caller), or <code>None</code> if this is the bottom | |
837 | stack frame; <tt class="member">f_code</tt> is the code object being executed in this | |
838 | frame; <tt class="member">f_locals</tt> is the dictionary used to look up local | |
839 | variables; <tt class="member">f_globals</tt> is used for global variables; | |
840 | <tt class="member">f_builtins</tt> is used for built-in (intrinsic) names; | |
841 | <tt class="member">f_restricted</tt> is a flag indicating whether the function is | |
842 | executing in restricted execution mode; <tt class="member">f_lasti</tt> gives the | |
843 | precise instruction (this is an index into the bytecode string of | |
844 | the code object). | |
845 | <a id='l2h-145' xml:id='l2h-145'></a> | |
846 | <P> | |
847 | Special writable attributes: <tt class="member">f_trace</tt>, if not <code>None</code>, is | |
848 | a function called at the start of each source code line (this is used | |
849 | by the debugger); <tt class="member">f_exc_type</tt>, <tt class="member">f_exc_value</tt>, | |
850 | <tt class="member">f_exc_traceback</tt> represent the last exception raised in the | |
851 | parent frame provided another exception was ever raised in the current | |
852 | frame (in all other cases they are None); <tt class="member">f_lineno</tt> is the | |
853 | current line number of the frame -- writing to this from within a | |
854 | trace function jumps to the given line (only for the bottom-most | |
855 | frame). A debugger can implement a Jump command (aka Set Next | |
856 | Statement) by writing to f_lineno. | |
857 | <a id='l2h-147' xml:id='l2h-147'></a> | |
858 | <P> | |
859 | </DD> | |
860 | <DT><STRONG>Traceback objects</STRONG></DT> | |
861 | <DD><A NAME="traceback"></A>Traceback objects represent a stack trace of an exception. A | |
862 | traceback object is created when an exception occurs. When the search | |
863 | for an exception handler unwinds the execution stack, at each unwound | |
864 | level a traceback object is inserted in front of the current | |
865 | traceback. When an exception handler is entered, the stack trace is | |
866 | made available to the program. | |
867 | (See section <A href="try.html#try">7.4</A>, ``The <code>try</code> statement.'') | |
868 | It is accessible as <code>sys.exc_traceback</code>, and also as the third | |
869 | item of the tuple returned by <code>sys.exc_info()</code>. The latter is | |
870 | the preferred interface, since it works correctly when the program is | |
871 | using multiple threads. | |
872 | When the program contains no suitable handler, the stack trace is written | |
873 | (nicely formatted) to the standard error stream; if the interpreter is | |
874 | interactive, it is also made available to the user as | |
875 | <code>sys.last_traceback</code>. | |
876 | <a id='l2h-148' xml:id='l2h-148'></a><a id='l2h-149' xml:id='l2h-149'></a><a id='l2h-150' xml:id='l2h-150'></a><a id='l2h-151' xml:id='l2h-151'></a><a id='l2h-153' xml:id='l2h-153'></a><a id='l2h-168' xml:id='l2h-168'></a> | |
877 | ||
878 | <P> | |
879 | Special read-only attributes: <tt class="member">tb_next</tt> is the next level in the | |
880 | stack trace (towards the frame where the exception occurred), or | |
881 | <code>None</code> if there is no next level; <tt class="member">tb_frame</tt> points to the | |
882 | execution frame of the current level; <tt class="member">tb_lineno</tt> gives the line | |
883 | number where the exception occurred; <tt class="member">tb_lasti</tt> indicates the | |
884 | precise instruction. The line number and last instruction in the | |
885 | traceback may differ from the line number of its frame object if the | |
886 | exception occurred in a <tt class="keyword">try</tt> statement with no matching | |
887 | except clause or with a finally clause. | |
888 | <a id='l2h-155' xml:id='l2h-155'></a><a id='l2h-156' xml:id='l2h-156'></a> | |
889 | <P> | |
890 | </DD> | |
891 | <DT><STRONG>Slice objects</STRONG></DT> | |
892 | <DD>Slice objects are used to represent slices when <em>extended slice | |
893 | syntax</em> is used. This is a slice using two colons, or multiple slices | |
894 | or ellipses separated by commas, e.g., <code>a[i:j:step]</code>, <code>a[i:j, | |
895 | k:l]</code>, or <code>a[..., i:j]</code>. They are also created by the built-in | |
896 | <tt class="function">slice()</tt><a id='l2h-157' xml:id='l2h-157'></a> function. | |
897 | ||
898 | <P> | |
899 | Special read-only attributes: <tt class="member">start</tt> is the lower bound; | |
900 | <tt class="member">stop</tt> is the upper bound; <tt class="member">step</tt> is the step value; each is | |
901 | <code>None</code> if omitted. These attributes can have any type. | |
902 | <a id='l2h-159' xml:id='l2h-159'></a> | |
903 | <P> | |
904 | Slice objects support one method: | |
905 | ||
906 | <P> | |
907 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
908 | <td><nobr><b><tt id='l2h-160' xml:id='l2h-160' class="method">indices</tt></b>(</nobr></td> | |
909 | <td><var>self, length</var>)</td></tr></table></dt> | |
910 | <dd> | |
911 | This method takes a single integer argument <var>length</var> and computes | |
912 | information about the extended slice that the slice object would | |
913 | describe if applied to a sequence of <var>length</var> items. It returns a | |
914 | tuple of three integers; respectively these are the <var>start</var> and | |
915 | <var>stop</var> indices and the <var>step</var> or stride length of the slice. | |
916 | Missing or out-of-bounds indices are handled in a manner consistent | |
917 | with regular slices. | |
918 | ||
919 | <span class="versionnote">New in version 2.3.</span> | |
920 | ||
921 | </dl> | |
922 | ||
923 | <P> | |
924 | </DD> | |
925 | <DT><STRONG>Static method objects</STRONG></DT> | |
926 | <DD>Static method objects provide a way of defeating the transformation | |
927 | of function objects to method objects described above. A static method | |
928 | object is a wrapper around any other object, usually a user-defined | |
929 | method object. When a static method object is retrieved from a class | |
930 | or a class instance, the object actually returned is the wrapped object, | |
931 | which is not subject to any further transformation. Static method | |
932 | objects are not themselves callable, although the objects they | |
933 | wrap usually are. Static method objects are created by the built-in | |
934 | <tt class="function">staticmethod()</tt> constructor. | |
935 | ||
936 | <P> | |
937 | </DD> | |
938 | <DT><STRONG>Class method objects</STRONG></DT> | |
939 | <DD>A class method object, like a static method object, is a wrapper | |
940 | around another object that alters the way in which that object | |
941 | is retrieved from classes and class instances. The behaviour of | |
942 | class method objects upon such retrieval is described above, | |
943 | under ``User-defined methods''. Class method objects are created | |
944 | by the built-in <tt class="function">classmethod()</tt> constructor. | |
945 | ||
946 | <P> | |
947 | </DD> | |
948 | </DL> | |
949 | <P> | |
950 | </DD> | |
951 | </DL> | |
952 | <P> | |
953 | ||
954 | <DIV CLASS="navigation"> | |
955 | <div class='online-navigation'> | |
956 | <p></p><hr /> | |
957 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
958 | <tr> | |
959 | <td class='online-navigation'><a rel="prev" title="3.1 Objects, values and" | |
960 | href="objects.html"><img src='../icons/previous.png' | |
961 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
962 | <td class='online-navigation'><a rel="parent" title="3. Data model" | |
963 | href="datamodel.html"><img src='../icons/up.png' | |
964 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
965 | <td class='online-navigation'><a rel="next" title="3.3 Special method names" | |
966 | href="specialnames.html"><img src='../icons/next.png' | |
967 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
968 | <td align="center" width="100%">Python Reference Manual</td> | |
969 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
970 | href="contents.html"><img src='../icons/contents.png' | |
971 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
972 | <td class='online-navigation'><img src='../icons/blank.png' | |
973 | border='0' height='32' alt='' width='32' /></td> | |
974 | <td class='online-navigation'><a rel="index" title="Index" | |
975 | href="genindex.html"><img src='../icons/index.png' | |
976 | border='0' height='32' alt='Index' width='32' /></A></td> | |
977 | </tr></table> | |
978 | <div class='online-navigation'> | |
979 | <b class="navlabel">Previous:</b> | |
980 | <a class="sectref" rel="prev" href="objects.html">3.1 Objects, values and</A> | |
981 | <b class="navlabel">Up:</b> | |
982 | <a class="sectref" rel="parent" href="datamodel.html">3. Data model</A> | |
983 | <b class="navlabel">Next:</b> | |
984 | <a class="sectref" rel="next" href="specialnames.html">3.3 Special method names</A> | |
985 | </div> | |
986 | </div> | |
987 | <hr /> | |
988 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
989 | </DIV> | |
990 | <!--End of Navigation Panel--> | |
991 | <ADDRESS> | |
992 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
993 | </ADDRESS> | |
994 | </BODY> | |
995 | </HTML> |