| 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> |