Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 1 | \chapter{Data model} |
| 2 | |
| 3 | \section{Objects, values and types} |
| 4 | |
| 5 | \dfn{Objects} are Python's abstraction for data. All data in a Python |
| 6 | program is represented by objects or by relations between objects. |
| 7 | (In a sense, and in conformance to Von Neumann's model of a |
| 8 | ``stored program computer'', code is also represented by objects.) |
| 9 | \index{object} |
| 10 | \index{data} |
| 11 | |
| 12 | Every object has an identity, a type and a value. An object's |
| 13 | \emph{identity} never changes once it has been created; you may think |
| 14 | of it as the object's address in memory. An object's \dfn{type} is |
| 15 | also unchangeable. It determines the operations that an object |
| 16 | supports (e.g.\ ``does it have a length?'') and also defines the |
| 17 | possible values for objects of that type. The \emph{value} of some |
| 18 | objects can change. Objects whose value can change are said to be |
| 19 | \emph{mutable}; objects whose value is unchangeable once they are |
| 20 | created are called \emph{immutable}. The type determines an object's |
| 21 | (im)mutability. |
| 22 | \index{identity of an object} |
| 23 | \index{value of an object} |
| 24 | \index{type of an object} |
| 25 | \index{mutable object} |
| 26 | \index{immutable object} |
| 27 | |
| 28 | Objects are never explicitly destroyed; however, when they become |
| 29 | unreachable they may be garbage-collected. An implementation is |
| 30 | allowed to delay garbage collection or omit it altogether --- it is a |
| 31 | matter of implementation quality how garbage collection is |
| 32 | implemented, as long as no objects are collected that are still |
| 33 | reachable. (Implementation note: the current implementation uses a |
| 34 | reference-counting scheme which collects most objects as soon as they |
| 35 | become unreachable, but never collects garbage containing circular |
| 36 | references.) |
| 37 | \index{garbage collection} |
| 38 | \index{reference counting} |
| 39 | \index{unreachable object} |
| 40 | |
| 41 | Note that the use of the implementation's tracing or debugging |
| 42 | facilities may keep objects alive that would normally be collectable. |
| 43 | |
| 44 | Some objects contain references to ``external'' resources such as open |
| 45 | files or windows. It is understood that these resources are freed |
| 46 | when the object is garbage-collected, but since garbage collection is |
| 47 | not guaranteed to happen, such objects also provide an explicit way to |
| 48 | release the external resource, usually a \method{close()} method. |
| 49 | Programs are strongly recommended to always explicitly close such |
| 50 | objects. |
| 51 | |
| 52 | Some objects contain references to other objects; these are called |
| 53 | \emph{containers}. Examples of containers are tuples, lists and |
| 54 | dictionaries. The references are part of a container's value. In |
| 55 | most cases, when we talk about the value of a container, we imply the |
| 56 | values, not the identities of the contained objects; however, when we |
| 57 | talk about the (im)mutability of a container, only the identities of |
| 58 | the immediately contained objects are implied. (So, if an immutable |
| 59 | container contains a reference to a mutable object, its value changes |
| 60 | if that mutable object is changed.) |
| 61 | \index{container} |
| 62 | |
| 63 | Types affect almost all aspects of objects' lives. Even the meaning |
| 64 | of object identity is affected in some sense: for immutable types, |
| 65 | operations that compute new values may actually return a reference to |
| 66 | any existing object with the same type and value, while for mutable |
| 67 | objects this is not allowed. E.g. after |
| 68 | |
| 69 | \begin{verbatim} |
| 70 | a = 1; b = 1; c = []; d = [] |
| 71 | \end{verbatim} |
| 72 | |
| 73 | \code{a} and \code{b} may or may not refer to the same object with the |
| 74 | value one, depending on the implementation, but \code{c} and \code{d} |
| 75 | are guaranteed to refer to two different, unique, newly created empty |
| 76 | lists. |
| 77 | |
| 78 | \section{The standard type hierarchy} \label{types} |
| 79 | |
| 80 | Below is a list of the types that are built into Python. Extension |
| 81 | modules written in C can define additional types. Future versions of |
| 82 | Python may add types to the type hierarchy (e.g.\ rational or complex |
| 83 | numbers, efficiently stored arrays of integers, etc.). |
| 84 | \index{type} |
| 85 | \indexii{data}{type} |
| 86 | \indexii{type}{hierarchy} |
| 87 | \indexii{extension}{module} |
| 88 | \indexii{C}{language} |
| 89 | |
| 90 | Some of the type descriptions below contain a paragraph listing |
| 91 | `special attributes'. These are attributes that provide access to the |
| 92 | implementation and are not intended for general use. Their definition |
| 93 | may change in the future. There are also some `generic' special |
| 94 | attributes, not listed with the individual objects: \member{__methods__} |
| 95 | is a list of the method names of a built-in object, if it has any; |
| 96 | \member{__members__} is a list of the data attribute names of a built-in |
| 97 | object, if it has any. |
| 98 | \index{attribute} |
| 99 | \indexii{special}{attribute} |
| 100 | \indexiii{generic}{special}{attribute} |
| 101 | \ttindex{__methods__} |
| 102 | \ttindex{__members__} |
| 103 | |
| 104 | \begin{description} |
| 105 | |
| 106 | \item[None] |
| 107 | This type has a single value. There is a single object with this value. |
| 108 | This object is accessed through the built-in name \code{None}. |
| 109 | It is returned from functions that don't explicitly return an object. |
| 110 | \ttindex{None} |
| 111 | \obindex{None@{\tt None}} |
| 112 | |
| 113 | \item[Numbers] |
| 114 | These are created by numeric literals and returned as results by |
| 115 | arithmetic operators and arithmetic built-in functions. Numeric |
| 116 | objects are immutable; once created their value never changes. Python |
| 117 | numbers are of course strongly related to mathematical numbers, but |
| 118 | subject to the limitations of numerical representation in computers. |
| 119 | \obindex{number} |
| 120 | \obindex{numeric} |
| 121 | |
| 122 | Python distinguishes between integers and floating point numbers: |
| 123 | |
| 124 | \begin{description} |
| 125 | \item[Integers] |
| 126 | These represent elements from the mathematical set of whole numbers. |
| 127 | \obindex{integer} |
| 128 | |
| 129 | There are two types of integers: |
| 130 | |
| 131 | \begin{description} |
| 132 | |
| 133 | \item[Plain integers] |
| 134 | These represent numbers in the range -2147483648 through 2147483647. |
| 135 | (The range may be larger on machines with a larger natural word |
| 136 | size, but not smaller.) |
| 137 | When the result of an operation falls outside this range, the |
| 138 | exception \exception{OverflowError} is raised. |
| 139 | For the purpose of shift and mask operations, integers are assumed to |
| 140 | have a binary, 2's complement notation using 32 or more bits, and |
| 141 | hiding no bits from the user (i.e., all 4294967296 different bit |
| 142 | patterns correspond to different values). |
| 143 | \obindex{plain integer} |
| 144 | \withsubitem{(built-in exception)}{\ttindex{OverflowError}} |
| 145 | |
| 146 | \item[Long integers] |
| 147 | These represent numbers in an unlimited range, subject to available |
| 148 | (virtual) memory only. For the purpose of shift and mask operations, |
| 149 | a binary representation is assumed, and negative numbers are |
| 150 | represented in a variant of 2's complement which gives the illusion of |
| 151 | an infinite string of sign bits extending to the left. |
| 152 | \obindex{long integer} |
| 153 | |
| 154 | \end{description} % Integers |
| 155 | |
| 156 | The rules for integer representation are intended to give the most |
| 157 | meaningful interpretation of shift and mask operations involving |
| 158 | negative integers and the least surprises when switching between the |
| 159 | plain and long integer domains. For any operation except left shift, |
| 160 | if it yields a result in the plain integer domain without causing |
| 161 | overflow, it will yield the same result in the long integer domain or |
| 162 | when using mixed operands. |
| 163 | \indexii{integer}{representation} |
| 164 | |
| 165 | \item[Floating point numbers] |
| 166 | These represent machine-level double precision floating point numbers. |
| 167 | You are at the mercy of the underlying machine architecture and |
| 168 | C implementation for the accepted range and handling of overflow. |
| 169 | \obindex{floating point} |
| 170 | \indexii{floating point}{number} |
| 171 | \indexii{C}{language} |
| 172 | |
| 173 | \end{description} % Numbers |
| 174 | |
| 175 | \item[Sequences] |
| 176 | These represent finite ordered sets indexed by natural numbers. |
| 177 | The built-in function \function{len()}\bifuncindex{len} returns the |
| 178 | number of elements of a sequence. When this number is \var{n}, the |
| 179 | index set contains the numbers 0, 1, \ldots, \var{n}-1. Element |
| 180 | \var{i} of sequence \var{a} is selected by \code{\var{a}[\var{i}]}. |
| 181 | \obindex{seqence} |
| 182 | \index{index operation} |
| 183 | \index{item selection} |
| 184 | \index{subscription} |
| 185 | |
| 186 | Sequences also support slicing: \code{\var{a}[\var{i}:\var{j}]} |
| 187 | selects all elements with index \var{k} such that \var{i} \code{<=} |
| 188 | \var{k} \code{<} \var{j}. When used as an expression, a slice is a |
| 189 | sequence of the same type --- this implies that the index set is |
| 190 | renumbered so that it starts at 0 again. |
| 191 | \index{slicing} |
| 192 | |
| 193 | Sequences are distinguished according to their mutability: |
| 194 | |
| 195 | \begin{description} |
| 196 | % |
| 197 | \item[Immutable sequences] |
| 198 | An object of an immutable sequence type cannot change once it is |
| 199 | created. (If the object contains references to other objects, |
| 200 | these other objects may be mutable and may be changed; however |
| 201 | the collection of objects directly referenced by an immutable object |
| 202 | cannot change.) |
| 203 | \obindex{immutable sequence} |
| 204 | \obindex{immutable} |
| 205 | |
| 206 | The following types are immutable sequences: |
| 207 | |
| 208 | \begin{description} |
| 209 | |
| 210 | \item[Strings] |
| 211 | The elements of a string are characters. There is no separate |
| 212 | character type; a character is represented by a string of one element. |
| 213 | Characters represent (at least) 8-bit bytes. The built-in |
| 214 | functions \function{chr()}\bifuncindex{chr} and |
| 215 | \function{ord()}\bifuncindex{ord} convert between characters and |
| 216 | nonnegative integers representing the byte values. Bytes with the |
| 217 | values 0-127 represent the corresponding \ASCII{} values. The string |
| 218 | data type is also used to represent arrays of bytes, e.g.\ to hold data |
| 219 | read from a file. |
| 220 | \obindex{string} |
| 221 | \index{character} |
| 222 | \index{byte} |
Fred Drake | 5c07d9b | 1998-05-14 19:37:06 +0000 | [diff] [blame] | 223 | \index{ASCII@\ASCII{}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 224 | |
| 225 | (On systems whose native character set is not \ASCII{}, strings may use |
| 226 | EBCDIC in their internal representation, provided the functions |
| 227 | \function{chr()} and \function{ord()} implement a mapping between \ASCII{} and |
| 228 | EBCDIC, and string comparison preserves the \ASCII{} order. |
| 229 | Or perhaps someone can propose a better rule?) |
Fred Drake | 5c07d9b | 1998-05-14 19:37:06 +0000 | [diff] [blame] | 230 | \index{ASCII@\ASCII{}} |
Fred Drake | f666917 | 1998-05-06 19:52:49 +0000 | [diff] [blame] | 231 | \index{EBCDIC} |
| 232 | \index{character set} |
| 233 | \indexii{string}{comparison} |
| 234 | \bifuncindex{chr} |
| 235 | \bifuncindex{ord} |
| 236 | |
| 237 | \item[Tuples] |
| 238 | The elements of a tuple are arbitrary Python objects. |
| 239 | Tuples of two or more elements are formed by comma-separated lists |
| 240 | of expressions. A tuple of one element (a `singleton') can be formed |
| 241 | by affixing a comma to an expression (an expression by itself does |
| 242 | not create a tuple, since parentheses must be usable for grouping of |
| 243 | expressions). An empty tuple can be formed by enclosing `nothing' in |
| 244 | parentheses. |
| 245 | \obindex{tuple} |
| 246 | \indexii{singleton}{tuple} |
| 247 | \indexii{empty}{tuple} |
| 248 | |
| 249 | \end{description} % Immutable sequences |
| 250 | |
| 251 | \item[Mutable sequences] |
| 252 | Mutable sequences can be changed after they are created. The |
| 253 | subscription and slicing notations can be used as the target of |
| 254 | assignment and \keyword{del} (delete) statements. |
| 255 | \obindex{mutable sequece} |
| 256 | \obindex{mutable} |
| 257 | \indexii{assignment}{statement} |
| 258 | \index{delete} |
| 259 | \stindex{del} |
| 260 | \index{subscription} |
| 261 | \index{slicing} |
| 262 | |
| 263 | There is currently a single mutable sequence type: |
| 264 | |
| 265 | \begin{description} |
| 266 | |
| 267 | \item[Lists] |
| 268 | The elements of a list are arbitrary Python objects. Lists are formed |
| 269 | by placing a comma-separated list of expressions in square brackets. |
| 270 | (Note that there are no special cases needed to form lists of length 0 |
| 271 | or 1.) |
| 272 | \obindex{list} |
| 273 | |
| 274 | \end{description} % Mutable sequences |
| 275 | |
| 276 | \end{description} % Sequences |
| 277 | |
| 278 | \item[Mapping types] |
| 279 | These represent finite sets of objects indexed by arbitrary index sets. |
| 280 | The subscript notation \code{a[k]} selects the element indexed |
| 281 | by \code{k} from the mapping \code{a}; this can be used in |
| 282 | expressions and as the target of assignments or \keyword{del} statements. |
| 283 | The built-in function \function{len()} returns the number of elements |
| 284 | in a mapping. |
| 285 | \bifuncindex{len} |
| 286 | \index{subscription} |
| 287 | \obindex{mapping} |
| 288 | |
| 289 | There is currently a single mapping type: |
| 290 | |
| 291 | \begin{description} |
| 292 | |
| 293 | \item[Dictionaries] |
| 294 | These represent finite sets of objects indexed by almost arbitrary |
| 295 | values. The only types of values not acceptable as keys are values |
| 296 | containing lists or dictionaries or other mutable types that are |
| 297 | compared by value rather than by object identity --- the reason being |
| 298 | that the implementation requires that a key's hash value be constant. |
| 299 | Numeric types used for keys obey the normal rules for numeric |
| 300 | comparison: if two numbers compare equal (e.g.\ \code{1} and |
| 301 | \code{1.0}) then they can be used interchangeably to index the same |
| 302 | dictionary entry. |
| 303 | |
| 304 | Dictionaries are mutable; they are created by the \code{...} |
| 305 | notation (see section \ref{dict}). |
| 306 | \obindex{dictionary} |
| 307 | \obindex{mutable} |
| 308 | |
| 309 | \end{description} % Mapping types |
| 310 | |
| 311 | \item[Callable types] |
| 312 | These are the types to which the function call (invocation) operation, |
| 313 | written as \code{function(argument, argument, ...)}, can be applied: |
| 314 | \indexii{function}{call} |
| 315 | \index{invocation} |
| 316 | \indexii{function}{argument} |
| 317 | \obindex{callable} |
| 318 | |
| 319 | \begin{description} |
| 320 | |
| 321 | \item[User-defined functions] |
| 322 | A user-defined function object is created by a function definition |
| 323 | (see section \ref{function}). It should be called with an argument |
| 324 | list containing the same number of items as the function's formal |
| 325 | parameter list. |
| 326 | \indexii{user-defined}{function} |
| 327 | \obindex{function} |
| 328 | \obindex{user-defined function} |
| 329 | |
| 330 | Special read-only attributes: \member{func_code} is the code object |
| 331 | representing the compiled function body, and \member{func_globals} is (a |
| 332 | reference to) the dictionary that holds the function's global |
| 333 | variables --- it implements the global name space of the module in |
| 334 | which the function was defined. |
| 335 | \ttindex{func_code} |
| 336 | \ttindex{func_globals} |
| 337 | \indexii{global}{name space} |
| 338 | |
| 339 | \item[User-defined methods] |
| 340 | A user-defined method (a.k.a. \dfn{object closure}) is a pair of a |
| 341 | class instance object and a user-defined function. It should be |
| 342 | called with an argument list containing one item less than the number |
| 343 | of items in the function's formal parameter list. When called, the |
| 344 | class instance becomes the first argument, and the call arguments are |
| 345 | shifted one to the right. |
| 346 | \obindex{method} |
| 347 | \obindex{user-defined method} |
| 348 | \indexii{user-defined}{method} |
| 349 | \index{object closure} |
| 350 | |
| 351 | Special read-only attributes: \member{im_self} is the class instance |
| 352 | object, \member{im_func} is the function object. |
| 353 | \ttindex{im_func} |
| 354 | \ttindex{im_self} |
| 355 | |
| 356 | \item[Built-in functions] |
| 357 | A built-in function object is a wrapper around a C function. Examples |
| 358 | of built-in functions are \function{len()} and \function{math.sin()}. There |
| 359 | are no special attributes. The number and type of the arguments are |
| 360 | determined by the C function. |
| 361 | \obindex{built-in function} |
| 362 | \obindex{function} |
| 363 | \indexii{C}{language} |
| 364 | |
| 365 | \item[Built-in methods] |
| 366 | This is really a different disguise of a built-in function, this time |
| 367 | containing an object passed to the \C{} function as an implicit extra |
| 368 | argument. An example of a built-in method is \code{\var{list}.append()} if |
| 369 | \var{list} is a list object. |
| 370 | \obindex{built-in method} |
| 371 | \obindex{method} |
| 372 | \indexii{built-in}{method} |
| 373 | |
| 374 | \item[Classes] |
| 375 | Class objects are described below. When a class object is called as a |
| 376 | function, a new class instance (also described below) is created and |
| 377 | returned. This implies a call to the class's \method{__init__()} method |
| 378 | if it has one. Any arguments are passed on to the \method{__init__()} |
| 379 | method --- if there is no \method{__init__()} method, the class must be called |
| 380 | without arguments. |
| 381 | \ttindex{__init__} |
| 382 | \obindex{class} |
| 383 | \obindex{class instance} |
| 384 | \obindex{instance} |
| 385 | \indexii{class object}{call} |
| 386 | |
| 387 | \end{description} |
| 388 | |
| 389 | \item[Modules] |
| 390 | Modules are imported by the \keyword{import} statement (see section |
| 391 | \ref{import}). A module object is a container for a module's name |
| 392 | space, which is a dictionary (the same dictionary as referenced by the |
| 393 | \member{func_globals} attribute of functions defined in the module). |
| 394 | Module attribute references are translated to lookups in this |
| 395 | dictionary. A module object does not contain the code object used to |
| 396 | initialize the module (since it isn't needed once the initialization |
| 397 | is done). |
| 398 | \stindex{import} |
| 399 | \obindex{module} |
| 400 | |
| 401 | Attribute assignment update the module's name space dictionary. |
| 402 | |
| 403 | Special read-only attribute: \member{__dict__} yields the module's name |
| 404 | space as a dictionary object. Predefined attributes: \member{__name__} |
| 405 | yields the module's name as a string object; \member{__doc__} yields the |
| 406 | module's documentation string as a string object, or |
| 407 | \code{None} if no documentation string was found. |
| 408 | \ttindex{__dict__} |
| 409 | \ttindex{__name__} |
| 410 | \ttindex{__doc__} |
| 411 | \indexii{module}{name space} |
| 412 | |
| 413 | \item[Classes] |
| 414 | Class objects are created by class definitions (see section |
| 415 | \ref{class}). A class is a container for a dictionary containing the |
| 416 | class's name space. Class attribute references are translated to |
| 417 | lookups in this dictionary. When an attribute name is not found |
| 418 | there, the attribute search continues in the base classes. The search |
| 419 | is depth-first, left-to-right in the order of their occurrence in the |
| 420 | base class list. |
| 421 | \obindex{class} |
| 422 | \obindex{class instance} |
| 423 | \obindex{instance} |
| 424 | \indexii{class object}{call} |
| 425 | \index{container} |
| 426 | \obindex{dictionary} |
| 427 | \indexii{class}{attribute} |
| 428 | |
| 429 | Class attribute assignments update the class's dictionary, never the |
| 430 | dictionary of a base class. |
| 431 | \indexiii{class}{attribute}{assignment} |
| 432 | |
| 433 | A class can be called as a function to yield a class instance (see |
| 434 | above). |
| 435 | \indexii{class object}{call} |
| 436 | |
| 437 | Special read-only attributes: \member{__dict__} yields the dictionary |
| 438 | containing the class's name space; \member{__bases__} yields a tuple |
| 439 | (possibly empty or a singleton) containing the base classes, in the |
| 440 | order of their occurrence in the base class list. |
| 441 | \ttindex{__dict__} |
| 442 | \ttindex{__bases__} |
| 443 | |
| 444 | \item[Class instances] |
| 445 | A class instance is created by calling a class object as a |
| 446 | function. A class instance has a dictionary in which |
| 447 | attribute references are searched. When an attribute is not found |
| 448 | there, and the instance's class has an attribute by that name, and |
| 449 | that class attribute is a user-defined function (and in no other |
| 450 | cases), the instance attribute reference yields a user-defined method |
| 451 | object (see above) constructed from the instance and the function. |
| 452 | \obindex{class instance} |
| 453 | \obindex{instance} |
| 454 | \indexii{class}{instance} |
| 455 | \indexii{class instance}{attribute} |
| 456 | |
| 457 | Attribute assignments update the instance's dictionary. |
| 458 | \indexiii{class instance}{attribute}{assignment} |
| 459 | |
| 460 | Class instances can pretend to be numbers, sequences, or mappings if |
| 461 | they have methods with certain special names. These are described in |
| 462 | section \ref{specialnames}. |
| 463 | \obindex{number} |
| 464 | \obindex{sequence} |
| 465 | \obindex{mapping} |
| 466 | |
| 467 | Special read-only attributes: \member{__dict__} yields the attribute |
| 468 | dictionary; \member{__class__} yields the instance's class. |
| 469 | \ttindex{__dict__} |
| 470 | \ttindex{__class__} |
| 471 | |
| 472 | \item[Files] |
| 473 | A file object represents an open file. (It is a wrapper around a \C{} |
| 474 | \code{stdio} file pointer.) File objects are created by the |
| 475 | \function{open()} built-in function, and also by \function{posix.popen()} and |
| 476 | the \method{makefile()} method of socket objects. \code{sys.stdin}, |
| 477 | \code{sys.stdout} and \code{sys.stderr} are file objects corresponding |
| 478 | to the interpreter's standard input, output and error streams. |
| 479 | See the \emph{Python Library Reference} for methods of file objects |
| 480 | and other details. |
| 481 | \obindex{file} |
| 482 | \indexii{C}{language} |
| 483 | \index{stdio} |
| 484 | \bifuncindex{open} |
| 485 | \bifuncindex{popen} |
| 486 | \bifuncindex{makefile} |
| 487 | \ttindex{stdin} |
| 488 | \ttindex{stdout} |
| 489 | \ttindex{stderr} |
| 490 | \ttindex{sys.stdin} |
| 491 | \ttindex{sys.stdout} |
| 492 | \ttindex{sys.stderr} |
| 493 | |
| 494 | \item[Internal types] |
| 495 | A few types used internally by the interpreter are exposed to the user. |
| 496 | Their definition may change with future versions of the interpreter, |
| 497 | but they are mentioned here for completeness. |
| 498 | \index{internal type} |
| 499 | \index{types, internal} |
| 500 | |
| 501 | \begin{description} |
| 502 | |
| 503 | \item[Code objects] |
| 504 | Code objects represent ``pseudo-compiled'' executable Python code. |
| 505 | The difference between a code |
| 506 | object and a function object is that the function object contains an |
| 507 | explicit reference to the function's context (the module in which it |
| 508 | was defined) while a code object contains no context. |
| 509 | \obindex{code} |
| 510 | |
| 511 | Special read-only attributes: \member{co_code} is a string representing |
| 512 | the sequence of instructions; \member{co_consts} is a list of literals |
| 513 | used by the code; \member{co_names} is a list of names (strings) used by |
| 514 | the code; \member{co_filename} is the filename from which the code was |
| 515 | compiled. (To find out the line numbers, you would have to decode the |
| 516 | instructions; the standard library module |
| 517 | \module{dis}\refstmodindex{dis} contains an example of how to do |
| 518 | this.) |
| 519 | \ttindex{co_code} |
| 520 | \ttindex{co_consts} |
| 521 | \ttindex{co_names} |
| 522 | \ttindex{co_filename} |
| 523 | |
| 524 | \item[Frame objects] |
| 525 | Frame objects represent execution frames. They may occur in traceback |
| 526 | objects (see below). |
| 527 | \obindex{frame} |
| 528 | |
| 529 | Special read-only attributes: \member{f_back} is to the previous |
| 530 | stack frame (towards the caller), or \code{None} if this is the bottom |
| 531 | stack frame; \member{f_code} is the code object being executed in this |
| 532 | frame; \member{f_globals} is the dictionary used to look up global |
| 533 | variables; \member{f_locals} is used for local variables; |
| 534 | \member{f_lineno} gives the line number and \member{f_lasti} gives the |
| 535 | precise instruction (this is an index into the instruction string of |
| 536 | the code object). |
| 537 | \ttindex{f_back} |
| 538 | \ttindex{f_code} |
| 539 | \ttindex{f_globals} |
| 540 | \ttindex{f_locals} |
| 541 | \ttindex{f_lineno} |
| 542 | \ttindex{f_lasti} |
| 543 | |
| 544 | \item[Traceback objects] \label{traceback} |
| 545 | Traceback objects represent a stack trace of an exception. A |
| 546 | traceback object is created when an exception occurs. When the search |
| 547 | for an exception handler unwinds the execution stack, at each unwound |
| 548 | level a traceback object is inserted in front of the current |
| 549 | traceback. When an exception handler is entered |
| 550 | (see also section \ref{try}), the stack trace is |
| 551 | made available to the program as \code{sys.exc_traceback}. When the |
| 552 | program contains no suitable handler, the stack trace is written |
| 553 | (nicely formatted) to the standard error stream; if the interpreter is |
| 554 | interactive, it is also made available to the user as |
| 555 | \code{sys.last_traceback}. |
| 556 | \obindex{traceback} |
| 557 | \indexii{stack}{trace} |
| 558 | \indexii{exception}{handler} |
| 559 | \indexii{execution}{stack} |
| 560 | \ttindex{exc_traceback} |
| 561 | \ttindex{last_traceback} |
| 562 | \ttindex{sys.exc_traceback} |
| 563 | \ttindex{sys.last_traceback} |
| 564 | |
| 565 | Special read-only attributes: \member{tb_next} is the next level in the |
| 566 | stack trace (towards the frame where the exception occurred), or |
| 567 | \code{None} if there is no next level; \member{tb_frame} points to the |
| 568 | execution frame of the current level; \member{tb_lineno} gives the line |
| 569 | number where the exception occurred; \member{tb_lasti} indicates the |
| 570 | precise instruction. The line number and last instruction in the |
| 571 | traceback may differ from the line number of its frame object if the |
| 572 | exception occurred in a \keyword{try} statement with no matching |
| 573 | except clause or with a finally clause. |
| 574 | \ttindex{tb_next} |
| 575 | \ttindex{tb_frame} |
| 576 | \ttindex{tb_lineno} |
| 577 | \ttindex{tb_lasti} |
| 578 | \stindex{try} |
| 579 | |
| 580 | \end{description} % Internal types |
| 581 | |
| 582 | \end{description} % Types |
| 583 | |
| 584 | |
| 585 | \section{Special method names} \label{specialnames} |
| 586 | |
| 587 | A class can implement certain operations that are invoked by special |
| 588 | syntax (such as subscription or arithmetic operations) by defining |
| 589 | methods with special names. For instance, if a class defines a |
| 590 | method named \method{__getitem__()}, and \code{x} is an instance of this |
| 591 | class, then \code{x[i]} is equivalent to \code{x.__getitem__(i)}. |
| 592 | (The reverse is not true --- if \code{x} is a list object, |
| 593 | \code{x.__getitem__(i)} is not equivalent to \code{x[i]}.) |
| 594 | \ttindex{__getitem__} |
| 595 | |
| 596 | Except for \method{__repr__()}, \method{__str__()} and \method{__cmp__()}, |
| 597 | attempts to execute an |
| 598 | operation raise an exception when no appropriate method is defined. |
| 599 | For \method{__repr__()}, the default is to return a string describing the |
| 600 | object's class and address. |
| 601 | For \method{__cmp__()}, the default is to compare instances based on their |
| 602 | address. |
| 603 | For \method{__str__()}, the default is to use \method{__repr__()}. |
| 604 | \ttindex{__repr__} |
| 605 | \ttindex{__str__} |
| 606 | \ttindex{__cmp__} |
| 607 | |
| 608 | |
| 609 | \subsection{Special methods for any type} |
| 610 | |
| 611 | \begin{description} |
| 612 | |
| 613 | \item[{\tt __init__(self, args...)}] |
| 614 | Called when the instance is created. The arguments are those passed |
| 615 | to the class constructor expression. If a base class has an |
| 616 | \code{__init__} method the derived class's \code{__init__} method must |
| 617 | explicitly call it to ensure proper initialization of the base class |
| 618 | part of the instance. |
| 619 | \ttindex{__init__} |
| 620 | \indexii{class}{constructor} |
| 621 | |
| 622 | |
| 623 | \item[{\tt __del__(self)}] |
| 624 | Called when the instance is about to be destroyed. If a base class |
| 625 | has a \method{__del__()} method the derived class's \method{__del__()} method |
| 626 | must explicitly call it to ensure proper deletion of the base class |
| 627 | part of the instance. Note that it is possible for the \method{__del__()} |
| 628 | method to postpone destruction of the instance by creating a new |
| 629 | reference to it. It may then be called at a later time when this new |
| 630 | reference is deleted. It is not guaranteed that |
| 631 | \method{__del__()} methods are called for objects that still exist when |
| 632 | the interpreter exits. |
| 633 | If an exception occurs in a \method{__del__()} method, it is ignored, and |
| 634 | a warning is printed on stderr. |
| 635 | \ttindex{__del__} |
| 636 | \stindex{del} |
| 637 | |
| 638 | Note that \code{del x} doesn't directly call \code{x.__del__()} --- the |
| 639 | former decrements the reference count for \code{x} by one, but |
| 640 | \code{x.__del__()} is only called when its reference count reaches zero. |
| 641 | |
| 642 | \strong{Warning:} due to the precarious circumstances under which |
| 643 | \code{__del__()} methods are executed, exceptions that occur during |
| 644 | their execution are \emph{ignored}. |
| 645 | |
| 646 | \item[{\tt __repr__(self)}] |
| 647 | Called by the \function{repr()} built-in function and by string conversions |
| 648 | (reverse or backward quotes) to compute the string representation of an object. |
| 649 | \ttindex{__repr__} |
| 650 | \bifuncindex{repr} |
| 651 | \indexii{string}{conversion} |
| 652 | \indexii{reverse}{quotes} |
| 653 | \indexii{backward}{quotes} |
| 654 | \index{back-quotes} |
| 655 | |
| 656 | \item[{\tt __str__(self)}] |
| 657 | Called by the \function{str()} built-in function and by the \keyword{print} |
| 658 | statement compute the string representation of an object. |
| 659 | \ttindex{__str__} |
| 660 | \bifuncindex{str} |
| 661 | \stindex{print} |
| 662 | |
| 663 | \item[{\tt __cmp__(self, other)}] |
| 664 | Called by all comparison operations. Should return \code{-1} if |
| 665 | \code{self < other}, \code{0} if \code{self == other}, \code{+1} if |
| 666 | \code{self > other}. If no \method{__cmp__()} operation is defined, class |
| 667 | instances are compared by object identity (``address''). |
| 668 | (Implementation note: due to limitations in the interpreter, |
| 669 | exceptions raised by comparisons are ignored, and the objects will be |
| 670 | considered equal in this case.) |
| 671 | \ttindex{__cmp__} |
| 672 | \bifuncindex{cmp} |
| 673 | \index{comparisons} |
| 674 | |
| 675 | \item[{\tt __hash__(self)}] |
| 676 | Called for the key object for dictionary operations, |
| 677 | and by the built-in function |
| 678 | \function{hash()}\bifuncindex{hash}. Should return a 32-bit integer |
| 679 | usable as a hash value |
| 680 | for dictionary operations. The only required property is that objects |
| 681 | which compare equal have the same hash value; it is advised to somehow |
| 682 | mix together (e.g.\ using exclusive or) the hash values for the |
| 683 | components of the object that also play a part in comparison of |
| 684 | objects. If a class does not define a \method{__cmp__()} method it should |
| 685 | not define a \method{__hash__()} operation either; if it defines |
| 686 | \method{__cmp__()} but not \method{__hash__()} its instances will not be |
| 687 | usable as dictionary keys. If a class defines mutable objects and |
| 688 | implements a \method{__cmp__()} method it should not implement |
| 689 | \method{__hash__()}, since the dictionary implementation assumes that a |
| 690 | key's hash value is a constant. |
| 691 | \obindex{dictionary} |
| 692 | \ttindex{__cmp__} |
| 693 | \ttindex{__hash__} |
| 694 | |
| 695 | \item[{\tt __call__(self, *args)}] |
| 696 | Called when the instance is ``called'' as a function. |
| 697 | \ttindex{__call__} |
| 698 | \indexii{call}{instance} |
| 699 | |
| 700 | \end{description} |
| 701 | |
| 702 | |
| 703 | \subsection{Special methods for attribute access} |
| 704 | |
| 705 | The following methods can be used to change the meaning of attribute |
| 706 | access for class instances. |
| 707 | |
| 708 | \begin{description} |
| 709 | |
| 710 | \item[{\tt __getattr__(self, name)}] |
| 711 | Called when an attribute lookup has not found the attribute in the |
| 712 | usual places (i.e. it is not an instance attribute nor is it found in |
| 713 | the class tree for \code{self}). \code{name} is the attribute name. |
| 714 | \ttindex{__getattr__} |
| 715 | |
| 716 | Note that if the attribute is found through the normal mechanism, |
| 717 | \code{__getattr__} is not called. (This is an asymmetry between |
| 718 | \code{__getattr__} and \code{__setattr__}.) |
| 719 | This is done both for efficiency reasons and because otherwise |
| 720 | \code{__getattr__} would have no way to access other attributes of the |
| 721 | instance. |
| 722 | Note that at least for instance variables, \code{__getattr__} can fake |
| 723 | total control by simply not inserting any values in the instance |
| 724 | attribute dictionary. |
| 725 | \ttindex{__setattr__} |
| 726 | |
| 727 | \item[{\tt __setattr__(self, name, value)}] |
| 728 | Called when an attribute assignment is attempted. This is called |
| 729 | instead of the normal mechanism (i.e. store the value as an instance |
| 730 | attribute). \code{name} is the attribute name, \code{value} is the |
| 731 | value to be assigned to it. |
| 732 | \ttindex{__setattr__} |
| 733 | |
| 734 | If \code{__setattr__} wants to assign to an instance attribute, it |
| 735 | should not simply execute \code{self.\var{name} = value} --- this would |
| 736 | cause a recursive call. Instead, it should insert the value in the |
| 737 | dictionary of instance attributes, e.g.\ \code{self.__dict__[name] = |
| 738 | value}. |
| 739 | \ttindex{__dict__} |
| 740 | |
| 741 | \item[{\tt __delattr__(self, name)}] |
| 742 | Like \code{__setattr__} but for attribute deletion instead of |
| 743 | assignment. |
| 744 | \ttindex{__delattr__} |
| 745 | |
| 746 | \end{description} |
| 747 | |
| 748 | |
| 749 | \subsection{Special methods for sequence and mapping types} |
| 750 | |
| 751 | \begin{description} |
| 752 | |
| 753 | \item[{\tt __len__(self)}] |
| 754 | Called to implement the built-in function \function{len()}. Should return |
| 755 | the length of the object, an integer \code{>=} 0. Also, an object |
| 756 | whose \method{__len__()} method returns 0 is considered to be false in a |
| 757 | Boolean context. |
| 758 | \ttindex{__len__} |
| 759 | |
| 760 | \item[{\tt __getitem__(self, key)}] |
| 761 | Called to implement evaluation of \code{self[key]}. Note that the |
| 762 | special interpretation of negative keys (if the class wishes to |
| 763 | emulate a sequence type) is up to the \method{__getitem__()} method. |
| 764 | \ttindex{__getitem__} |
| 765 | |
| 766 | \item[{\tt __setitem__(self, key, value)}] |
| 767 | Called to implement assignment to \code{self[key]}. Same note as for |
| 768 | \method{__getitem__()}. |
| 769 | \ttindex{__setitem__} |
| 770 | |
| 771 | \item[{\tt __delitem__(self, key)}] |
| 772 | Called to implement deletion of \code{self[key]}. Same note as for |
| 773 | \method{__getitem__()}. |
| 774 | \ttindex{__delitem__} |
| 775 | |
| 776 | \end{description} |
| 777 | |
| 778 | |
| 779 | \subsection{Special methods for sequence types} |
| 780 | |
| 781 | \begin{description} |
| 782 | |
| 783 | \item[{\tt __getslice__(self, i, j)}] |
| 784 | Called to implement evaluation of \code{self[i:j]}. Note that missing |
| 785 | \code{i} or \code{j} are replaced by 0 or \code{len(self)}, |
| 786 | respectively, and \code{len(self)} has been added (once) to originally |
| 787 | negative \code{i} or \code{j} by the time this function is called |
| 788 | (unlike for \method{__getitem__()}). |
| 789 | \ttindex{__getslice__} |
| 790 | |
| 791 | \item[{\tt __setslice__(self, i, j, sequence)}] |
| 792 | Called to implement assignment to \code{self[i:j]}. Same notes as for |
| 793 | \method{__getslice__()}. |
| 794 | \ttindex{__setslice__} |
| 795 | |
| 796 | \item[{\tt __delslice__(self, i, j)}] |
| 797 | Called to implement deletion of \code{self[i:j]}. Same notes as for |
| 798 | \method{__getslice__()}. |
| 799 | \ttindex{__delslice__} |
| 800 | |
| 801 | \end{description} |
| 802 | |
| 803 | |
| 804 | \subsection{Special methods for numeric types} |
| 805 | |
| 806 | \begin{description} |
| 807 | |
| 808 | \item[{\tt __add__(self, other)}]\itemjoin |
| 809 | \item[{\tt __sub__(self, other)}]\itemjoin |
| 810 | \item[{\tt __mul__(self, other)}]\itemjoin |
| 811 | \item[{\tt __div__(self, other)}]\itemjoin |
| 812 | \item[{\tt __mod__(self, other)}]\itemjoin |
| 813 | \item[{\tt __divmod__(self, other)}]\itemjoin |
| 814 | \item[{\tt __pow__(self, other)}]\itemjoin |
| 815 | \item[{\tt __lshift__(self, other)}]\itemjoin |
| 816 | \item[{\tt __rshift__(self, other)}]\itemjoin |
| 817 | \item[{\tt __and__(self, other)}]\itemjoin |
| 818 | \item[{\tt __xor__(self, other)}]\itemjoin |
| 819 | \item[{\tt __or__(self, other)}]\itembreak |
| 820 | Called to implement the binary arithmetic operations (\code{+}, |
| 821 | \code{-}, \code{*}, \code{/}, \code{\%}, \function{divmod()}, \function{pow()}, |
| 822 | \code{<<}, \code{>>}, \code{\&}, \code{\^}, \code{|}). |
| 823 | \ttindex{__or__} |
| 824 | \ttindex{__xor__} |
| 825 | \ttindex{__and__} |
| 826 | \ttindex{__rshift__} |
| 827 | \ttindex{__lshift__} |
| 828 | \ttindex{__pow__} |
| 829 | \ttindex{__divmod__} |
| 830 | \ttindex{__mod__} |
| 831 | \ttindex{__div__} |
| 832 | \ttindex{__mul__} |
| 833 | \ttindex{__sub__} |
| 834 | \ttindex{__add__} |
| 835 | |
| 836 | \item[{\tt __neg__(self)}]\itemjoin |
| 837 | \item[{\tt __pos__(self)}]\itemjoin |
| 838 | \item[{\tt __abs__(self)}]\itemjoin |
| 839 | \item[{\tt __invert__(self)}]\itembreak |
| 840 | Called to implement the unary arithmetic operations (\code{-}, \code{+}, |
| 841 | \function{abs()} and \code{~}). |
| 842 | \ttindex{__invert__} |
| 843 | \ttindex{__abs__} |
| 844 | \ttindex{__pos__} |
| 845 | \ttindex{__neg__} |
| 846 | |
| 847 | \item[{\tt __nonzero__(self)}] |
| 848 | Called to implement boolean testing; should return 0 or 1. An |
| 849 | alternative name for this method is \method{__len__()}. |
| 850 | \ttindex{__nonzero__} |
| 851 | |
| 852 | \item[{\tt __coerce__(self, other)}] |
| 853 | Called to implement ``mixed-mode'' numeric arithmetic. Should either |
| 854 | return a tuple containing self and other converted to a common numeric |
| 855 | type, or None if no way of conversion is known. When the common type |
| 856 | would be the type of other, it is sufficient to return None, since the |
| 857 | interpreter will also ask the other object to attempt a coercion (but |
| 858 | sometimes, if the implementation of the other type cannot be changed, |
| 859 | it is useful to do the conversion to the other type here). |
| 860 | \ttindex{__coerce__} |
| 861 | |
| 862 | Note that this method is not called to coerce the arguments to \code{+} |
| 863 | and \code{*}, because these are also used to implement sequence |
| 864 | concatenation and repetition, respectively. Also note that, for the |
| 865 | same reason, in \code{\var{n} * \var{x}}, where \var{n} is a built-in |
| 866 | number and \var{x} is an instance, a call to |
| 867 | \code{\var{x}.__mul__(\var{n})} is made.% |
| 868 | \footnote{The interpreter should really distinguish between |
| 869 | user-defined classes implementing sequences, mappings or numbers, but |
| 870 | currently it doesn't --- hence this strange exception.} |
| 871 | \ttindex{__mul__} |
| 872 | |
| 873 | \item[{\tt __int__(self)}]\itemjoin |
| 874 | \item[{\tt __long__(self)}]\itemjoin |
| 875 | \item[{\tt __float__(self)}]\itembreak |
| 876 | Called to implement the built-in functions \function{int()}, \function{long()} |
| 877 | and \function{float()}. Should return a value of the appropriate type. |
| 878 | \ttindex{__float__} |
| 879 | \ttindex{__long__} |
| 880 | \ttindex{__int__} |
| 881 | |
| 882 | \item[{\tt __oct__(self)}]\itemjoin |
| 883 | \item[{\tt __hex__(self)}]\itembreak |
| 884 | Called to implement the built-in functions \function{oct()} and |
| 885 | \function{hex()}. Should return a string value. |
| 886 | \ttindex{__hex__} |
| 887 | \ttindex{__oct__} |
| 888 | |
| 889 | \end{description} |