/Doc/reference/datamodel.rst
ReStructuredText | 2439 lines | 1896 code | 543 blank | 0 comment | 0 complexity | 1a4a26c427249dcc208fc5f9df27b2b2 MD5 | raw file
1 2.. _datamodel: 3 4********** 5Data model 6********** 7 8 9.. _objects: 10 11Objects, values and types 12========================= 13 14.. index:: 15 single: object 16 single: data 17 18:dfn:`Objects` are Python's abstraction for data. All data in a Python program 19is represented by objects or by relations between objects. (In a sense, and in 20conformance to Von Neumann's model of a "stored program computer," code is also 21represented by objects.) 22 23.. index:: 24 builtin: id 25 builtin: type 26 single: identity of an object 27 single: value of an object 28 single: type of an object 29 single: mutable object 30 single: immutable object 31 32Every object has an identity, a type and a value. An object's *identity* never 33changes once it has been created; you may think of it as the object's address in 34memory. The ':keyword:`is`' operator compares the identity of two objects; the 35:func:`id` function returns an integer representing its identity (currently 36implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_ 37An object's type determines the operations that the object supports (e.g., "does 38it have a length?") and also defines the possible values for objects of that 39type. The :func:`type` function returns an object's type (which is an object 40itself). The *value* of some objects can change. Objects whose value can 41change are said to be *mutable*; objects whose value is unchangeable once they 42are created are called *immutable*. (The value of an immutable container object 43that contains a reference to a mutable object can change when the latter's value 44is changed; however the container is still considered immutable, because the 45collection of objects it contains cannot be changed. So, immutability is not 46strictly the same as having an unchangeable value, it is more subtle.) An 47object's mutability is determined by its type; for instance, numbers, strings 48and tuples are immutable, while dictionaries and lists are mutable. 49 50.. index:: 51 single: garbage collection 52 single: reference counting 53 single: unreachable object 54 55Objects are never explicitly destroyed; however, when they become unreachable 56they may be garbage-collected. An implementation is allowed to postpone garbage 57collection or omit it altogether --- it is a matter of implementation quality 58how garbage collection is implemented, as long as no objects are collected that 59are still reachable. (Implementation note: CPython currently uses a 60reference-counting scheme with (optional) delayed detection of cyclically linked 61garbage, which collects most objects as soon as they become unreachable, but is 62not guaranteed to collect garbage containing circular references. See the 63documentation of the :mod:`gc` module for information on controlling the 64collection of cyclic garbage. Other implementations act differently and CPython 65may change.) 66 67Note that the use of the implementation's tracing or debugging facilities may 68keep objects alive that would normally be collectable. Also note that catching 69an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep 70objects alive. 71 72Some objects contain references to "external" resources such as open files or 73windows. It is understood that these resources are freed when the object is 74garbage-collected, but since garbage collection is not guaranteed to happen, 75such objects also provide an explicit way to release the external resource, 76usually a :meth:`close` method. Programs are strongly recommended to explicitly 77close such objects. The ':keyword:`try`...\ :keyword:`finally`' statement 78provides a convenient way to do this. 79 80.. index:: single: container 81 82Some objects contain references to other objects; these are called *containers*. 83Examples of containers are tuples, lists and dictionaries. The references are 84part of a container's value. In most cases, when we talk about the value of a 85container, we imply the values, not the identities of the contained objects; 86however, when we talk about the mutability of a container, only the identities 87of the immediately contained objects are implied. So, if an immutable container 88(like a tuple) contains a reference to a mutable object, its value changes if 89that mutable object is changed. 90 91Types affect almost all aspects of object behavior. Even the importance of 92object identity is affected in some sense: for immutable types, operations that 93compute new values may actually return a reference to any existing object with 94the same type and value, while for mutable objects this is not allowed. E.g., 95after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object 96with the value one, depending on the implementation, but after ``c = []; d = 97[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly 98created empty lists. (Note that ``c = d = []`` assigns the same object to both 99``c`` and ``d``.) 100 101 102.. _types: 103 104The standard type hierarchy 105=========================== 106 107.. index:: 108 single: type 109 pair: data; type 110 pair: type; hierarchy 111 pair: extension; module 112 pair: C; language 113 114Below is a list of the types that are built into Python. Extension modules 115(written in C, Java, or other languages, depending on the implementation) can 116define additional types. Future versions of Python may add types to the type 117hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.). 118 119.. index:: 120 single: attribute 121 pair: special; attribute 122 triple: generic; special; attribute 123 124Some of the type descriptions below contain a paragraph listing 'special 125attributes.' These are attributes that provide access to the implementation and 126are not intended for general use. Their definition may change in the future. 127 128None 129 .. index:: object: None 130 131 This type has a single value. There is a single object with this value. This 132 object is accessed through the built-in name ``None``. It is used to signify the 133 absence of a value in many situations, e.g., it is returned from functions that 134 don't explicitly return anything. Its truth value is false. 135 136NotImplemented 137 .. index:: object: NotImplemented 138 139 This type has a single value. There is a single object with this value. This 140 object is accessed through the built-in name ``NotImplemented``. Numeric methods 141 and rich comparison methods may return this value if they do not implement the 142 operation for the operands provided. (The interpreter will then try the 143 reflected operation, or some other fallback, depending on the operator.) Its 144 truth value is true. 145 146Ellipsis 147 .. index:: object: Ellipsis 148 149 This type has a single value. There is a single object with this value. This 150 object is accessed through the built-in name ``Ellipsis``. It is used to 151 indicate the presence of the ``...`` syntax in a slice. Its truth value is 152 true. 153 154:class:`numbers.Number` 155 .. index:: object: numeric 156 157 These are created by numeric literals and returned as results by arithmetic 158 operators and arithmetic built-in functions. Numeric objects are immutable; 159 once created their value never changes. Python numbers are of course strongly 160 related to mathematical numbers, but subject to the limitations of numerical 161 representation in computers. 162 163 Python distinguishes between integers, floating point numbers, and complex 164 numbers: 165 166 :class:`numbers.Integral` 167 .. index:: object: integer 168 169 These represent elements from the mathematical set of integers (positive and 170 negative). 171 172 There are three types of integers: 173 174 Plain integers 175 .. index:: 176 object: plain integer 177 single: OverflowError (built-in exception) 178 179 These represent numbers in the range -2147483648 through 2147483647. 180 (The range may be larger on machines with a larger natural word size, 181 but not smaller.) When the result of an operation would fall outside 182 this range, the result is normally returned as a long integer (in some 183 cases, the exception :exc:`OverflowError` is raised instead). For the 184 purpose of shift and mask operations, integers are assumed to have a 185 binary, 2's complement notation using 32 or more bits, and hiding no 186 bits from the user (i.e., all 4294967296 different bit patterns 187 correspond to different values). 188 189 Long integers 190 .. index:: object: long integer 191 192 These represent numbers in an unlimited range, subject to available 193 (virtual) memory only. For the purpose of shift and mask operations, a 194 binary representation is assumed, and negative numbers are represented 195 in a variant of 2's complement which gives the illusion of an infinite 196 string of sign bits extending to the left. 197 198 Booleans 199 .. index:: 200 object: Boolean 201 single: False 202 single: True 203 204 These represent the truth values False and True. The two objects 205 representing the values False and True are the only Boolean objects. 206 The Boolean type is a subtype of plain integers, and Boolean values 207 behave like the values 0 and 1, respectively, in almost all contexts, 208 the exception being that when converted to a string, the strings 209 ``"False"`` or ``"True"`` are returned, respectively. 210 211 .. index:: pair: integer; representation 212 213 The rules for integer representation are intended to give the most 214 meaningful interpretation of shift and mask operations involving negative 215 integers and the least surprises when switching between the plain and long 216 integer domains. Any operation, if it yields a result in the plain 217 integer domain, will yield the same result in the long integer domain or 218 when using mixed operands. The switch between domains is transparent to 219 the programmer. 220 221 :class:`numbers.Real` (:class:`float`) 222 .. index:: 223 object: floating point 224 pair: floating point; number 225 pair: C; language 226 pair: Java; language 227 228 These represent machine-level double precision floating point numbers. You are 229 at the mercy of the underlying machine architecture (and C or Java 230 implementation) for the accepted range and handling of overflow. Python does not 231 support single-precision floating point numbers; the savings in processor and 232 memory usage that are usually the reason for using these is dwarfed by the 233 overhead of using objects in Python, so there is no reason to complicate the 234 language with two kinds of floating point numbers. 235 236 :class:`numbers.Complex` 237 .. index:: 238 object: complex 239 pair: complex; number 240 241 These represent complex numbers as a pair of machine-level double precision 242 floating point numbers. The same caveats apply as for floating point numbers. 243 The real and imaginary parts of a complex number ``z`` can be retrieved through 244 the read-only attributes ``z.real`` and ``z.imag``. 245 246Sequences 247 .. index:: 248 builtin: len 249 object: sequence 250 single: index operation 251 single: item selection 252 single: subscription 253 254 These represent finite ordered sets indexed by non-negative numbers. The 255 built-in function :func:`len` returns the number of items of a sequence. When 256 the length of a sequence is *n*, the index set contains the numbers 0, 1, 257 ..., *n*-1. Item *i* of sequence *a* is selected by ``a[i]``. 258 259 .. index:: single: slicing 260 261 Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such 262 that *i* ``<=`` *k* ``<`` *j*. When used as an expression, a slice is a 263 sequence of the same type. This implies that the index set is renumbered so 264 that it starts at 0. 265 266 .. index:: single: extended slicing 267 268 Some sequences also support "extended slicing" with a third "step" parameter: 269 ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n* 270 ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*. 271 272 Sequences are distinguished according to their mutability: 273 274 Immutable sequences 275 .. index:: 276 object: immutable sequence 277 object: immutable 278 279 An object of an immutable sequence type cannot change once it is created. (If 280 the object contains references to other objects, these other objects may be 281 mutable and may be changed; however, the collection of objects directly 282 referenced by an immutable object cannot change.) 283 284 The following types are immutable sequences: 285 286 Strings 287 .. index:: 288 builtin: chr 289 builtin: ord 290 object: string 291 single: character 292 single: byte 293 single: ASCII@ASCII 294 295 The items of a string are characters. There is no separate character type; a 296 character is represented by a string of one item. Characters represent (at 297 least) 8-bit bytes. The built-in functions :func:`chr` and :func:`ord` convert 298 between characters and nonnegative integers representing the byte values. Bytes 299 with the values 0-127 usually represent the corresponding ASCII values, but the 300 interpretation of values is up to the program. The string data type is also 301 used to represent arrays of bytes, e.g., to hold data read from a file. 302 303 .. index:: 304 single: ASCII@ASCII 305 single: EBCDIC 306 single: character set 307 pair: string; comparison 308 builtin: chr 309 builtin: ord 310 311 (On systems whose native character set is not ASCII, strings may use EBCDIC in 312 their internal representation, provided the functions :func:`chr` and 313 :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison 314 preserves the ASCII order. Or perhaps someone can propose a better rule?) 315 316 Unicode 317 .. index:: 318 builtin: unichr 319 builtin: ord 320 builtin: unicode 321 object: unicode 322 single: character 323 single: integer 324 single: Unicode 325 326 The items of a Unicode object are Unicode code units. A Unicode code unit is 327 represented by a Unicode object of one item and can hold either a 16-bit or 328 32-bit value representing a Unicode ordinal (the maximum value for the ordinal 329 is given in ``sys.maxunicode``, and depends on how Python is configured at 330 compile time). Surrogate pairs may be present in the Unicode object, and will 331 be reported as two separate items. The built-in functions :func:`unichr` and 332 :func:`ord` convert between code units and nonnegative integers representing the 333 Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to 334 other encodings are possible through the Unicode method :meth:`encode` and the 335 built-in function :func:`unicode`. 336 337 Tuples 338 .. index:: 339 object: tuple 340 pair: singleton; tuple 341 pair: empty; tuple 342 343 The items of a tuple are arbitrary Python objects. Tuples of two or more items 344 are formed by comma-separated lists of expressions. A tuple of one item (a 345 'singleton') can be formed by affixing a comma to an expression (an expression 346 by itself does not create a tuple, since parentheses must be usable for grouping 347 of expressions). An empty tuple can be formed by an empty pair of parentheses. 348 349 Mutable sequences 350 .. index:: 351 object: mutable sequence 352 object: mutable 353 pair: assignment; statement 354 single: delete 355 statement: del 356 single: subscription 357 single: slicing 358 359 Mutable sequences can be changed after they are created. The subscription and 360 slicing notations can be used as the target of assignment and :keyword:`del` 361 (delete) statements. 362 363 There is currently a single intrinsic mutable sequence type: 364 365 Lists 366 .. index:: object: list 367 368 The items of a list are arbitrary Python objects. Lists are formed by placing a 369 comma-separated list of expressions in square brackets. (Note that there are no 370 special cases needed to form lists of length 0 or 1.) 371 372 .. index:: module: array 373 374 The extension module :mod:`array` provides an additional example of a mutable 375 sequence type. 376 377Set types 378 .. index:: 379 builtin: len 380 object: set type 381 382 These represent unordered, finite sets of unique, immutable objects. As such, 383 they cannot be indexed by any subscript. However, they can be iterated over, and 384 the built-in function :func:`len` returns the number of items in a set. Common 385 uses for sets are fast membership testing, removing duplicates from a sequence, 386 and computing mathematical operations such as intersection, union, difference, 387 and symmetric difference. 388 389 For set elements, the same immutability rules apply as for dictionary keys. Note 390 that numeric types obey the normal rules for numeric comparison: if two numbers 391 compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a 392 set. 393 394 There are currently two intrinsic set types: 395 396 Sets 397 .. index:: object: set 398 399 These represent a mutable set. They are created by the built-in :func:`set` 400 constructor and can be modified afterwards by several methods, such as 401 :meth:`add`. 402 403 Frozen sets 404 .. index:: object: frozenset 405 406 These represent an immutable set. They are created by the built-in 407 :func:`frozenset` constructor. As a frozenset is immutable and 408 :term:`hashable`, it can be used again as an element of another set, or as 409 a dictionary key. 410 411Mappings 412 .. index:: 413 builtin: len 414 single: subscription 415 object: mapping 416 417 These represent finite sets of objects indexed by arbitrary index sets. The 418 subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping 419 ``a``; this can be used in expressions and as the target of assignments or 420 :keyword:`del` statements. The built-in function :func:`len` returns the number 421 of items in a mapping. 422 423 There is currently a single intrinsic mapping type: 424 425 Dictionaries 426 .. index:: object: dictionary 427 428 These represent finite sets of objects indexed by nearly arbitrary values. The 429 only types of values not acceptable as keys are values containing lists or 430 dictionaries or other mutable types that are compared by value rather than by 431 object identity, the reason being that the efficient implementation of 432 dictionaries requires a key's hash value to remain constant. Numeric types used 433 for keys obey the normal rules for numeric comparison: if two numbers compare 434 equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index 435 the same dictionary entry. 436 437 Dictionaries are mutable; they can be created by the ``{...}`` notation (see 438 section :ref:`dict`). 439 440 .. index:: 441 module: dbm 442 module: gdbm 443 module: bsddb 444 445 The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide 446 additional examples of mapping types. 447 448Callable types 449 .. index:: 450 object: callable 451 pair: function; call 452 single: invocation 453 pair: function; argument 454 455 These are the types to which the function call operation (see section 456 :ref:`calls`) can be applied: 457 458 User-defined functions 459 .. index:: 460 pair: user-defined; function 461 object: function 462 object: user-defined function 463 464 A user-defined function object is created by a function definition (see 465 section :ref:`function`). It should be called with an argument list 466 containing the same number of items as the function's formal parameter 467 list. 468 469 Special attributes: 470 471 +-----------------------+-------------------------------+-----------+ 472 | Attribute | Meaning | | 473 +=======================+===============================+===========+ 474 | :attr:`func_doc` | The function's documentation | Writable | 475 | | string, or ``None`` if | | 476 | | unavailable | | 477 +-----------------------+-------------------------------+-----------+ 478 | :attr:`__doc__` | Another way of spelling | Writable | 479 | | :attr:`func_doc` | | 480 +-----------------------+-------------------------------+-----------+ 481 | :attr:`func_name` | The function's name | Writable | 482 +-----------------------+-------------------------------+-----------+ 483 | :attr:`__name__` | Another way of spelling | Writable | 484 | | :attr:`func_name` | | 485 +-----------------------+-------------------------------+-----------+ 486 | :attr:`__module__` | The name of the module the | Writable | 487 | | function was defined in, or | | 488 | | ``None`` if unavailable. | | 489 +-----------------------+-------------------------------+-----------+ 490 | :attr:`func_defaults` | A tuple containing default | Writable | 491 | | argument values for those | | 492 | | arguments that have defaults, | | 493 | | or ``None`` if no arguments | | 494 | | have a default value | | 495 +-----------------------+-------------------------------+-----------+ 496 | :attr:`func_code` | The code object representing | Writable | 497 | | the compiled function body. | | 498 +-----------------------+-------------------------------+-----------+ 499 | :attr:`func_globals` | A reference to the dictionary | Read-only | 500 | | that holds the function's | | 501 | | global variables --- the | | 502 | | global namespace of the | | 503 | | module in which the function | | 504 | | was defined. | | 505 +-----------------------+-------------------------------+-----------+ 506 | :attr:`func_dict` | The namespace supporting | Writable | 507 | | arbitrary function | | 508 | | attributes. | | 509 +-----------------------+-------------------------------+-----------+ 510 | :attr:`func_closure` | ``None`` or a tuple of cells | Read-only | 511 | | that contain bindings for the | | 512 | | function's free variables. | | 513 +-----------------------+-------------------------------+-----------+ 514 515 Most of the attributes labelled "Writable" check the type of the assigned value. 516 517 .. versionchanged:: 2.4 518 ``func_name`` is now writable. 519 520 Function objects also support getting and setting arbitrary attributes, which 521 can be used, for example, to attach metadata to functions. Regular attribute 522 dot-notation is used to get and set such attributes. *Note that the current 523 implementation only supports function attributes on user-defined functions. 524 Function attributes on built-in functions may be supported in the future.* 525 526 Additional information about a function's definition can be retrieved from its 527 code object; see the description of internal types below. 528 529 .. index:: 530 single: func_doc (function attribute) 531 single: __doc__ (function attribute) 532 single: __name__ (function attribute) 533 single: __module__ (function attribute) 534 single: __dict__ (function attribute) 535 single: func_defaults (function attribute) 536 single: func_closure (function attribute) 537 single: func_code (function attribute) 538 single: func_globals (function attribute) 539 single: func_dict (function attribute) 540 pair: global; namespace 541 542 User-defined methods 543 .. index:: 544 object: method 545 object: user-defined method 546 pair: user-defined; method 547 548 A user-defined method object combines a class, a class instance (or ``None``) 549 and any callable object (normally a user-defined function). 550 551 Special read-only attributes: :attr:`im_self` is the class instance object, 552 :attr:`im_func` is the function object; :attr:`im_class` is the class of 553 :attr:`im_self` for bound methods or the class that asked for the method for 554 unbound methods; :attr:`__doc__` is the method's documentation (same as 555 ``im_func.__doc__``); :attr:`__name__` is the method name (same as 556 ``im_func.__name__``); :attr:`__module__` is the name of the module the method 557 was defined in, or ``None`` if unavailable. 558 559 .. versionchanged:: 2.2 560 :attr:`im_self` used to refer to the class that defined the method. 561 562 .. versionchanged:: 2.6 563 For 3.0 forward-compatibility, :attr:`im_func` is also available as 564 :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`. 565 566 .. index:: 567 single: __doc__ (method attribute) 568 single: __name__ (method attribute) 569 single: __module__ (method attribute) 570 single: im_func (method attribute) 571 single: im_self (method attribute) 572 573 Methods also support accessing (but not setting) the arbitrary function 574 attributes on the underlying function object. 575 576 User-defined method objects may be created when getting an attribute of a class 577 (perhaps via an instance of that class), if that attribute is a user-defined 578 function object, an unbound user-defined method object, or a class method 579 object. When the attribute is a user-defined method object, a new method object 580 is only created if the class from which it is being retrieved is the same as, or 581 a derived class of, the class stored in the original method object; otherwise, 582 the original method object is used as it is. 583 584 .. index:: 585 single: im_class (method attribute) 586 single: im_func (method attribute) 587 single: im_self (method attribute) 588 589 When a user-defined method object is created by retrieving a user-defined 590 function object from a class, its :attr:`im_self` attribute is ``None`` 591 and the method object is said to be unbound. When one is created by 592 retrieving a user-defined function object from a class via one of its 593 instances, its :attr:`im_self` attribute is the instance, and the method 594 object is said to be bound. In either case, the new method's 595 :attr:`im_class` attribute is the class from which the retrieval takes 596 place, and its :attr:`im_func` attribute is the original function object. 597 598 .. index:: single: im_func (method attribute) 599 600 When a user-defined method object is created by retrieving another method object 601 from a class or instance, the behaviour is the same as for a function object, 602 except that the :attr:`im_func` attribute of the new instance is not the 603 original method object but its :attr:`im_func` attribute. 604 605 .. index:: 606 single: im_class (method attribute) 607 single: im_func (method attribute) 608 single: im_self (method attribute) 609 610 When a user-defined method object is created by retrieving a class method object 611 from a class or instance, its :attr:`im_self` attribute is the class itself (the 612 same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is 613 the function object underlying the class method. 614 615 When an unbound user-defined method object is called, the underlying function 616 (:attr:`im_func`) is called, with the restriction that the first argument must 617 be an instance of the proper class (:attr:`im_class`) or of a derived class 618 thereof. 619 620 When a bound user-defined method object is called, the underlying function 621 (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in 622 front of the argument list. For instance, when :class:`C` is a class which 623 contains a definition for a function :meth:`f`, and ``x`` is an instance of 624 :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``. 625 626 When a user-defined method object is derived from a class method object, the 627 "class instance" stored in :attr:`im_self` will actually be the class itself, so 628 that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)`` 629 where ``f`` is the underlying function. 630 631 Note that the transformation from function object to (unbound or bound) method 632 object happens each time the attribute is retrieved from the class or instance. 633 In some cases, a fruitful optimization is to assign the attribute to a local 634 variable and call that local variable. Also notice that this transformation only 635 happens for user-defined functions; other callable objects (and all non-callable 636 objects) are retrieved without transformation. It is also important to note 637 that user-defined functions which are attributes of a class instance are not 638 converted to bound methods; this *only* happens when the function is an 639 attribute of the class. 640 641 Generator functions 642 .. index:: 643 single: generator; function 644 single: generator; iterator 645 646 A function or method which uses the :keyword:`yield` statement (see section 647 :ref:`yield`) is called a :dfn:`generator 648 function`. Such a function, when called, always returns an iterator object 649 which can be used to execute the body of the function: calling the iterator's 650 :meth:`next` method will cause the function to execute until it provides a value 651 using the :keyword:`yield` statement. When the function executes a 652 :keyword:`return` statement or falls off the end, a :exc:`StopIteration` 653 exception is raised and the iterator will have reached the end of the set of 654 values to be returned. 655 656 Built-in functions 657 .. index:: 658 object: built-in function 659 object: function 660 pair: C; language 661 662 A built-in function object is a wrapper around a C function. Examples of 663 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a 664 standard built-in module). The number and type of the arguments are 665 determined by the C function. Special read-only attributes: 666 :attr:`__doc__` is the function's documentation string, or ``None`` if 667 unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is 668 set to ``None`` (but see the next item); :attr:`__module__` is the name of 669 the module the function was defined in or ``None`` if unavailable. 670 671 Built-in methods 672 .. index:: 673 object: built-in method 674 object: method 675 pair: built-in; method 676 677 This is really a different disguise of a built-in function, this time containing 678 an object passed to the C function as an implicit extra argument. An example of 679 a built-in method is ``alist.append()``, assuming *alist* is a list object. In 680 this case, the special read-only attribute :attr:`__self__` is set to the object 681 denoted by *list*. 682 683 Class Types 684 Class types, or "new-style classes," are callable. These objects normally act 685 as factories for new instances of themselves, but variations are possible for 686 class types that override :meth:`__new__`. The arguments of the call are passed 687 to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize 688 the new instance. 689 690 Classic Classes 691 .. index:: 692 single: __init__() (object method) 693 object: class 694 object: class instance 695 object: instance 696 pair: class object; call 697 698 Class objects are described below. When a class object is called, a new class 699 instance (also described below) is created and returned. This implies a call to 700 the class's :meth:`__init__` method if it has one. Any arguments are passed on 701 to the :meth:`__init__` method. If there is no :meth:`__init__` method, the 702 class must be called without arguments. 703 704 Class instances 705 Class instances are described below. Class instances are callable only when the 706 class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for 707 ``x.__call__(arguments)``. 708 709Modules 710 .. index:: 711 statement: import 712 object: module 713 714 Modules are imported by the :keyword:`import` statement (see section 715 :ref:`import`). A module object has a 716 namespace implemented by a dictionary object (this is the dictionary referenced 717 by the func_globals attribute of functions defined in the module). Attribute 718 references are translated to lookups in this dictionary, e.g., ``m.x`` is 719 equivalent to ``m.__dict__["x"]``. A module object does not contain the code 720 object used to initialize the module (since it isn't needed once the 721 initialization is done). 722 723 Attribute assignment updates the module's namespace dictionary, e.g., ``m.x = 724 1`` is equivalent to ``m.__dict__["x"] = 1``. 725 726 .. index:: single: __dict__ (module attribute) 727 728 Special read-only attribute: :attr:`__dict__` is the module's namespace as a 729 dictionary object. 730 731 .. index:: 732 single: __name__ (module attribute) 733 single: __doc__ (module attribute) 734 single: __file__ (module attribute) 735 pair: module; namespace 736 737 Predefined (writable) attributes: :attr:`__name__` is the module's name; 738 :attr:`__doc__` is the module's documentation string, or ``None`` if 739 unavailable; :attr:`__file__` is the pathname of the file from which the module 740 was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not 741 present for C modules that are statically linked into the interpreter; for 742 extension modules loaded dynamically from a shared library, it is the pathname 743 of the shared library file. 744 745Classes 746 Both class types (new-style classes) and class objects (old-style/classic 747 classes) are typically created by class definitions (see section 748 :ref:`class`). A class has a namespace implemented by a dictionary object. 749 Class attribute references are translated to lookups in this dictionary, e.g., 750 ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes 751 in particular there are a number of hooks which allow for other means of 752 locating attributes). When the attribute name is not found there, the 753 attribute search continues in the base classes. For old-style classes, the 754 search is depth-first, left-to-right in the order of occurrence in the base 755 class list. New-style classes use the more complex C3 method resolution 756 order which behaves correctly even in the presence of 'diamond' 757 inheritance structures where there are multiple inheritance paths 758 leading back to a common ancestor. Additional details on the C3 MRO used by 759 new-style classes can be found in the documentation accompanying the 760 2.3 release at http://www.python.org/download/releases/2.3/mro/. 761 762 .. XXX: Could we add that MRO doc as an appendix to the language ref? 763 764 .. index:: 765 object: class 766 object: class instance 767 object: instance 768 pair: class object; call 769 single: container 770 object: dictionary 771 pair: class; attribute 772 773 When a class attribute reference (for class :class:`C`, say) would yield a 774 user-defined function object or an unbound user-defined method object whose 775 associated class is either :class:`C` or one of its base classes, it is 776 transformed into an unbound user-defined method object whose :attr:`im_class` 777 attribute is :class:`C`. When it would yield a class method object, it is 778 transformed into a bound user-defined method object whose :attr:`im_class` 779 and :attr:`im_self` attributes are both :class:`C`. When it would yield a 780 static method object, it is transformed into the object wrapped by the static 781 method object. See section :ref:`descriptors` for another way in which 782 attributes retrieved from a class may differ from those actually contained in 783 its :attr:`__dict__` (note that only new-style classes support descriptors). 784 785 .. index:: triple: class; attribute; assignment 786 787 Class attribute assignments update the class's dictionary, never the dictionary 788 of a base class. 789 790 .. index:: pair: class object; call 791 792 A class object can be called (see above) to yield a class instance (see below). 793 794 .. index:: 795 single: __name__ (class attribute) 796 single: __module__ (class attribute) 797 single: __dict__ (class attribute) 798 single: __bases__ (class attribute) 799 single: __doc__ (class attribute) 800 801 Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is 802 the module name in which the class was defined; :attr:`__dict__` is the 803 dictionary containing the class's namespace; :attr:`__bases__` is a tuple 804 (possibly empty or a singleton) containing the base classes, in the order of 805 their occurrence in the base class list; :attr:`__doc__` is the class's 806 documentation string, or None if undefined. 807 808Class instances 809 .. index:: 810 object: class instance 811 object: instance 812 pair: class; instance 813 pair: class instance; attribute 814 815 A class instance is created by calling a class object (see above). A class 816 instance has a namespace implemented as a dictionary which is the first place in 817 which attribute references are searched. When an attribute is not found there, 818 and the instance's class has an attribute by that name, the search continues 819 with the class attributes. If a class attribute is found that is a user-defined 820 function object or an unbound user-defined method object whose associated class 821 is the class (call it :class:`C`) of the instance for which the attribute 822 reference was initiated or one of its bases, it is transformed into a bound 823 user-defined method object whose :attr:`im_class` attribute is :class:`C` and 824 whose :attr:`im_self` attribute is the instance. Static method and class method 825 objects are also transformed, as if they had been retrieved from class 826 :class:`C`; see above under "Classes". See section :ref:`descriptors` for 827 another way in which attributes of a class retrieved via its instances may 828 differ from the objects actually stored in the class's :attr:`__dict__`. If no 829 class attribute is found, and the object's class has a :meth:`__getattr__` 830 method, that is called to satisfy the lookup. 831 832 .. index:: triple: class instance; attribute; assignment 833 834 Attribute assignments and deletions update the instance's dictionary, never a 835 class's dictionary. If the class has a :meth:`__setattr__` or 836 :meth:`__delattr__` method, this is called instead of updating the instance 837 dictionary directly. 838 839 .. index:: 840 object: numeric 841 object: sequence 842 object: mapping 843 844 Class instances can pretend to be numbers, sequences, or mappings if they have 845 methods with certain special names. See section :ref:`specialnames`. 846 847 .. index:: 848 single: __dict__ (instance attribute) 849 single: __class__ (instance attribute) 850 851 Special attributes: :attr:`__dict__` is the attribute dictionary; 852 :attr:`__class__` is the instance's class. 853 854Files 855 .. index:: 856 object: file 857 builtin: open 858 single: popen() (in module os) 859 single: makefile() (socket method) 860 single: sys.stdin 861 single: sys.stdout 862 single: sys.stderr 863 single: stdio 864 single: stdin (in module sys) 865 single: stdout (in module sys) 866 single: stderr (in module sys) 867 868 A file object represents an open file. File objects are created by the 869 :func:`open` built-in function, and also by :func:`os.popen`, 870 :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and 871 perhaps by other functions or methods provided by extension modules). The 872 objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to 873 file objects corresponding to the interpreter's standard input, output and 874 error streams. See :ref:`bltin-file-objects` for complete documentation of 875 file objects. 876 877Internal types 878 .. index:: 879 single: internal type 880 single: types, internal 881 882 A few types used internally by the interpreter are exposed to the user. Their 883 definitions may change with future versions of the interpreter, but they are 884 mentioned here for completeness. 885 886 Code objects 887 .. index:: 888 single: bytecode 889 object: code 890 891 Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`. 892 The difference between a code object and a function object is that the function 893 object contains an explicit reference to the function's globals (the module in 894 which it was defined), while a code object contains no context; also the default 895 argument values are stored in the function object, not in the code object 896 (because they represent values calculated at run-time). Unlike function 897 objects, code objects are nearly immutable and contain no references (directly or 898 indirectly) to mutable objects. 899 900 Special read-only attributes: :attr:`co_name` gives the function name; 901 :attr:`co_argcount` is the number of positional arguments (including arguments 902 with default values); :attr:`co_nlocals` is the number of local variables used 903 by the function (including arguments); :attr:`co_varnames` is a tuple containing 904 the names of the local variables (starting with the argument names); 905 :attr:`co_cellvars` is a tuple containing the names of local variables that are 906 referenced by nested functions; :attr:`co_freevars` is a tuple containing the 907 names of free variables; :attr:`co_code` is a string representing the sequence 908 of bytecode instructions; :attr:`co_consts` is a tuple containing the literals 909 used by the bytecode; :attr:`co_names` is a tuple containing the names used by 910 the bytecode; :attr:`co_filename` is the filename from which the code was 911 compiled; :attr:`co_firstlineno` is the first line number of the function; 912 :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to line 913 numbers (for details see the source code of the interpreter); 914 :attr:`co_stacksize` is the required stack size (including local variables); 915 :attr:`co_flags` is an integer encoding a number of flags for the interpreter. 916 :attr:`co_llvm` refers to an llvm::Function wrapper that can pretty-print the 917 LLVM assembly that implements this code object. 918 919 Writable attributes: :attr:`co_use_jit` is ``True`` if LLVM will be used to 920 run this function, or ``False`` if the normal CPython interpreter will be used. 921 :attr:`co_optimization` is an integer from -1 to 2 recording how optimized 922 :attr:`co_llvm` is. -1 is totally unoptimized, and 0 is the default 923 optimization that happens before a function is JITted. You cannot lower the 924 optimization level of an already-optimized function. 925 926 .. index:: 927 single: co_argcount (code object attribute) 928 single: co_code (code object attribute) 929 single: co_consts (code object attribute) 930 single: co_filename (code object attribute) 931 single: co_firstlineno (code object attribute) 932 single: co_flags (code object attribute) 933 single: co_lnotab (code object attribute) 934 single: co_name (code object attribute) 935 single: co_names (code object attribute) 936 single: co_nlocals (code object attribute) 937 single: co_stacksize (code object attribute) 938 single: co_varnames (code object attribute) 939 single: co_cellvars (code object attribute) 940 single: co_freevars (code object attribute) 941 single: co_use_jit (code object attribute) 942 single: co_optimization (code object attribute) 943 single: co_llvm (code object attribute) 944 945 .. index:: object: generator 946 947 The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if 948 the function uses the ``*arguments`` syntax to accept an arbitrary number of 949 positional arguments; bit ``0x08`` is set if the function uses the 950 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set 951 if the function is a generator. 952 953 Future feature declarations (``from __future__ import division``) also use bits 954 in :attr:`co_flags` to indicate whether a code object was compiled with a 955 particular feature enabled: bit ``0x2000`` is set if the function was compiled 956 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier 957 versions of Python. 958 959 Other bits in :attr:`co_flags` are reserved for internal use. 960 961 .. index:: single: documentation string 962 963 If a code object represents a function, the first item in :attr:`co_consts` is 964 the documentation string of the function, or ``None`` if undefined. 965 966 Frame objects 967 .. index:: object: frame 968 969 Frame objects represent execution frames. They may occur in traceback objects 970 (see below). 971 972 .. index:: 973 single: f_back (frame attribute) 974 single: f_code (frame attribute) 975 single: f_globals (frame attribute) 976 single: f_locals (frame attribute) 977 single: f_lasti (frame attribute) 978 single: f_builtins (frame attribute) 979 single: f_restricted (frame attribute) 980 981 Special read-only attributes: :attr:`f_back` is to the previous stack frame 982 (towards the caller), or ``None`` if this is the bottom stack frame; 983 :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals` 984 is the dictionary used to look up local variables; :attr:`f_globals` is used for 985 global variables; :attr:`f_builtins` is used for built-in (intrinsic) names; 986 :attr:`f_restricted` is a flag indicating whether the function is executing in 987 restricted execution mode; :attr:`f_lasti` gives the precise instruction (this 988 is an index into the bytecode string of the code object). 989 990 .. index:: 991 single: f_trace (frame attribute) 992 single: f_exc_type (frame attribute) 993 single: f_exc_value (frame attribute) 994 single: f_exc_traceback (frame attribute) 995 single: f_lineno (frame attribute) 996 997 Special writable attributes: :attr:`f_trace`, if not ``None``, is a function 998 called at the start of each source code line (this is used by the debugger); 999 :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the 1000 last exception raised in the parent frame provided another exception was ever 1001 raised in the current frame (in all other cases they are None); :attr:`f_lineno` 1002 is the current line number of the frame --- writing to this from within a trace 1003 function jumps to the given line (only for the bottom-most frame). A debugger 1004 can implement a Jump command (aka Set Next Statement) by writing to f_lineno. 1005 1006 Traceback objects 1007 .. index:: 1008 object: traceback 1009 pair: stack; trace 1010 pair: exception; handler 1011 pair: execution; stack 1012 single: exc_info (in module sys) 1013 single: exc_traceback (in module sys) 1014 single: last_traceback (in module sys) 1015 single: sys.exc_info 1016 single: sys.exc_traceback 1017 single: sys.last_traceback 1018 1019 Traceback objects represent a stack trace of an exception. A traceback object 1020 is created when an exception occurs. When the search for an exception handler 1021 unwinds the execution stack, at each unwound level a traceback object is 1022 inserted in front of the current traceback. When an exception handler is 1023 entered, the stack trace is made available to the program. (See section 1024 :ref:`try`.) It is accessible as ``sys.exc_traceback``, 1025 and also as the third item of the tuple returned by ``sys.exc_info()``. The 1026 latter is the preferred interface, since it works correctly when the program is 1027 using multiple threads. When the program contains no suitable handler, the stack 1028 trace is written (nicely formatted) to the standard error stream; if the 1029 interpreter is interactive, it is also made available to the user as 1030 ``sys.last_traceback``. 1031 1032 .. index:: 1033 single: tb_next (traceback attribute) 1034 single: tb_frame (traceback attribute) 1035 single: tb_lineno (traceback attribute) 1036 single: tb_lasti (traceback attribute) 1037 statement: try 1038 1039 Special read-only attributes: :attr:`tb_next` is the next level in the stack 1040 trace (towards the frame where the exception occurred), or ``None`` if there is 1041 no next level; :attr:`tb_frame` points to the execution frame of the current 1042 level; :attr:`tb_lineno` gives the line number where the exception occurred; 1043 :attr:`tb_lasti` indicates the precise instruction. The line number and last 1044 instruction in the traceback may differ from the line number of its frame object 1045 if the exception occurred in a :keyword:`try` statement with no matching except 1046 clause or with a finally clause. 1047 1048 Slice objects 1049 .. index:: builtin: slice 1050 1051 Slice objects are used to represent slices when *extended slice syntax* is used. 1052 This is a slice using two colons, or multiple slices or ellipses separated by 1053 commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``. They are 1054 also created by the built-in :func:`slice` function. 1055 1056 .. index:: 1057 single: start (slice object attribute) 1058 single: stop (slice object attribute) 1059 single: step (slice object attribute) 1060 1061 Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is 1062 the upper bound; :attr:`step` is the step value; each is ``None`` if omitted. 1063 These attributes can have any type. 1064 1065 Slice objects support one method: 1066 1067 1068 .. method:: slice.indices(self, length) 1069 1070 This method takes a single integer argument *length* and computes information 1071 about the extended slice that the slice object would describe if applied to a 1072 sequence of *length* items. It returns a tuple of three integers; respectively 1073 these are the *start* and *stop* indices and the *step* or stride length of the 1074 slice. Missing or out-of-bounds indices are handled in a manner consistent with 1075 regular slices. 1076 1077 .. versionadded:: 2.3 1078 1079 Static method objects 1080 Static method objects provide a way of defeating the transformation of function 1081 objects to method objects described above. A static method object is a wrapper 1082 around any other object, usually a user-defined method object. When a static 1083 method object is retrieved from a class or a class instance, the object actually 1084 returned is the wrapped object, which is not subject to any further 1085 transformation. Static method objects are not themselves callable, although the 1086 objects they wrap usually are. Static method objects are created by the built-in 1087 :func:`staticmethod` constructor. 1088 1089 Class method objects 1090 A class method object, like a static method object, is a wrapper around another 1091 object that alters the way in which that object is retrieved from classes and 1092 class instances. The behaviour of class method objects upon such retrieval is 1093 described above, under "User-defined methods". Class method objects are created 1094 by the built-in :func:`classmethod` constructor. 1095 1096 1097.. _newstyle: 1098 1099New-style and classic classes 1100============================= 1101 1102Classes and instances come in two flavors: old-style (or classic) and new-style. 1103 1104Up to Python 2.1, old-style classes were the only flavour available to the user. 1105The concept of (old-style) class is unrelated to the concept of type: if *x* is 1106an instance of an old-style class, then ``x.__class__`` designates the class of 1107*x*, but ``type(x)`` is always ``<type 'instance'>``. This reflects the fact 1108that all old-style instances, independently of their class, are implemented with 1109a single built-in type, called ``instance``. 1110 1111New-style classes were introduced in Python 2.2 to unify classes and types. A 1112new-style class is neither more nor less than a user-defined type. If *x* is an 1113instance of a new-style class, then ``type(x)`` is typically the same as 1114``x.__class__`` (although this is not guaranteed - a new-style class instance is 1115permitted to override the value returned for ``x.__class__``). 1116 1117The major motivation for introducing new-style classes is to provide a unified 1118object model with a full meta-model. It also has a number of practical 1119benefits, like the ability to subclass most built-in types, or the introduction 1120of "descriptors", which enable computed properties. 1121 1122For compatibility reasons, classes are still old-style by default. New-style 1123classes are created by specifying another new-style class (i.e. a type) as a 1124parent class, or the "top-level type" :class:`object` if no other parent is 1125needed. The behaviour of new-style classes differs from that of old-style 1126classes in a number of important details in addition to what :func:`type` 1127returns. Some of these changes are fundamental to the new object model, like 1128the way special methods are invoked. Others are "fixes" that could not be 1129implemented before for compatibility concerns, like the method resolution order 1130in case of multiple inheritance. 1131 1132While this manual aims to provide comprehensive coverage of Python's class 1133mechanics, it may still be lacking in some areas when it comes to its coverage 1134of new-style classes. Please see http://www.python.org/doc/newstyle/ for 1135sources of additional information. 1136 1137.. index:: 1138 single: class; new-style 1139 single: class; classic 1140 single: class; old-style 1141 1142Old-style classes are removed in Python 3.0, leaving only the semantics of 1143new-style classes. 1144 1145 1146.. _specialnames: 1147 1148Special method names 1149==================== 1150 1151.. index:: 1152 pair: operator; overloading 1153 single: __getitem__() (mapping object method) 1154 1155A class can implement certain operations that are invoked by special syntax 1156(such as arithmetic operations or subscripting and slicing) by defining methods 1157with special names. This is Python's approach to :dfn:`operator overloading`, 1158allowing classes to define their own behavior with respect to language 1159operators. For instance, if a class defines a method named :meth:`__getitem__`, 1160and ``x`` is an instance of this class, then ``x[i]`` is roughly equivalent 1161to ``x.__getitem__(i)`` for old-style classes and ``type(x).__getitem__(x, i)`` 1162for new-style classes. Except where mentioned, attempts to execute an 1163operation raise an exception when no appropriate method is defined (typically 1164:exc:`AttributeError` or :exc:`TypeError`). 1165 1166When implementing a class that emulates any built-in type, it is important that 1167the emulation only be implemented to the degree that it makes sense for the 1168object being modelled. For example, some sequences may work well with retrieval 1169of individual elements, but extracting a slice may not make sense. (One example 1170of this is the :class:`NodeList` interface in the W3C's Document Object Model.) 1171 1172 1173.. _customization: 1174 1175Basic customization 1176------------------- 1177 1178.. method:: object.__new__(cls[, ...]) 1179 1180 .. index:: pair: subclassing; immutable types 1181 1182 Called to create a new instance of class *cls*. :meth:`__new__` is a static 1183 method (special-cased so you need not declare it as such) that takes the class 1184 of which an instance was requested as its first argument. The remaining 1185 arguments are those passed to the object constructor expression (the call to the 1186 class). The return value of :meth:`__new__` should be the new object instance 1187 (usually an instance of *cls*). 1188 1189 Typical implementations create a new instance of the class by invoking the 1190 superclass's :meth:`__new__` method using ``super(currentclass, 1191 cls).__new__(cls[, ...])`` with appropriate arguments and then modifying the 1192 newly-created instance as necessary before returning it. 1193 1194 If :meth:`__new__` returns an instance of *cls*, then the new instance's 1195 :meth:`__init__` method will be invoked like ``__init__(self[, ...])``, where 1196 *self* is the new instance and the remaining arguments are the same as were 1197 passed to :meth:`__new__`. 1198 1199 If :meth:`__new__` does not return an instance of *cls*, then the new instance's 1200 :meth:`__init__` method will not be invoked. 1201 1202 :meth:`__new__` is intended mainly to allow subclasses of immutable types (like 1203 int, str, or tuple) to customize instance creation. It is also commonly 1204 overridden in custom metaclasses in order to customize class creation. 1205 1206 1207.. method:: object.__init__(self[, ...]) 1208 1209 .. index:: pair: class; constructor 1210 1211 Called when the instance is created. The arguments are those passed to the 1212 class constructor expression. If a base class has an :meth:`__init__` method, 1213 the derived class's :meth:`__init__` method, if any, must explicitly call it to 1214 ensure proper initialization of the base class part of the instance; for 1215 example: ``BaseClass.__init__(self, [args...])``. As a special constraint on 1216 constructors, no value may be returned; doing so will cause a :exc:`TypeError` 1217 to be raised at runtime. 1218 1219 1220.. method:: object.__del__(self) 1221 1222 .. index:: 1223 single: destructor 1224 statement: del 1225 1226 Called when the instance is about to be destroyed. This is also called a 1227 destructor. If a base class has a :meth:`__del__` method, the derived class's 1228 :meth:`__del__` method, if any, must explicitly call it to ensure proper 1229 deletion of the base class part of the instance. Note that it is possible 1230 (though not recommended!) for the :meth:`__del__` method to postpone destruction 1231 of the instance by creating a new reference to it. It may then be called at a 1232 later time when this new reference is deleted. It is not guaranteed that 1233 :meth:`__del__` methods are called for objects that still exist when the 1234 interpreter exits. 1235 1236 .. note:: 1237 1238 ``del x`` doesn't directly call ``x.__del__()`` --- the former decrements 1239 the reference count for ``x`` by one, and the latter is only called when 1240 ``x``'s reference count reaches zero. Some common situations that may 1241 prevent the reference count of an object from going to zero include: 1242 circular references between objects (e.g., a doubly-linked list or a tree 1243 data structure with parent and child pointers); a reference to the object 1244 on the stack frame of a function that caught an exception (the traceback 1245 stored in ``sys.exc_traceback`` keeps the stack frame alive); or a 1246 reference to the object on the stack frame that raised an unhandled 1247 exception in interactive mode (the traceback stored in 1248 ``sys.last_traceback`` keeps the stack frame alive). The first situation 1249 can only be remedied by explicitly breaking the cycles; the latter two 1250 situations can be resolved by storing ``None`` in ``sys.exc_traceback`` or 1251 ``sys.last_traceback``. Circular references which are garbage are 1252 detected when the option cycle detector is enabled (it's on by default), 1253 but can only be cleaned up if there are no Python-level :meth:`__del__` 1254 methods involved. Refer to the documentation for the :mod:`gc` module for 1255 more information about how :meth:`__del__` methods are handled by the 1256 cycle detector, particularly the description of the ``garbage`` value. 1257 1258 .. warning:: 1259 1260 Due to the precarious circumstances under which :meth:`__del__` methods are 1261 invoked, exceptions that occur during their execution are ignored, and a warning 1262 is printed to ``sys.stderr`` instead. Also, when :meth:`__del__` is invoked in 1263 response to a module being deleted (e.g., when execution of the program is 1264 done), other globals referenced by the :meth:`__del__` method may already have 1265 been deleted or in the process of being torn down (e.g. the import 1266 machinery shutting down). For this reason, :meth:`__del__` methods 1267 should do the absolute 1268 minimum needed to maintain external invariants. Starting with version 1.5, 1269 Python guarantees that globals whose name begins with a single underscore are 1270 deleted from their module before other globals are deleted; if no other 1271 references to such globals exist, this may help in assuring that imported 1272 modules are still available at the time when the :meth:`__del__` method is 1273 called. 1274 1275 1276.. method:: object.__repr__(self) 1277 1278 .. index:: builtin: repr 1279 1280 Called by the :func:`repr` built-in function and by string conversions (reverse 1281 quotes) to compute the "official" string representation of an object. If at all 1282 possible, this should look like a valid Python expression that could be used to 1283 recreate an object with the same value (given an appropriate environment). If 1284 this is not possible, a string of the form ``<...some useful description...>`` 1285 should be returned. The return value must be a string object. If a class 1286 defines :meth:`__repr__` but not :meth:`__str__`, then :meth:`__repr__` is also 1287 used when an "informal" string representation of instances of that class is 1288 required. 1289 1290 .. index:: 1291 pair: string; conversion 1292 pair: reverse; quotes 1293 pair: backward; quotes 1294 single: back-quotes 1295 1296 This is typically used for debugging, so it is important that the representation 1297 is information-rich and unambiguous. 1298 1299 1300.. method:: object.__str__(self) 1301 1302 .. index:: 1303 builtin: str 1304 statement: print 1305 1306 Called by the :func:`str` built-in function and by the :keyword:`print` 1307 statement to compute the "informal" string representation of an object. This 1308 differs from :meth:`__repr__` in that it does not have to be a valid Python 1309 expression: a more convenient or concise representation may be used instead. 1310 The return value must be a string object. 1311 1312 1313.. method:: object.__lt__(self, other) 1314 object.__le__(self, other) 1315 object.__eq__(self, other) 1316 object.__ne__(self, other) 1317 object.__gt__(self, other) 1318 object.__ge__(self, other) 1319 1320 .. versionadded:: 2.1 1321 1322 .. index:: 1323 single: comparisons 1324 1325 These are the so-called "rich comparison" methods, and are called for comparison 1326 operators in preference to :meth:`__cmp__` below. The correspondence between 1327 operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``, 1328 ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` and 1329 ``x<>y`` call ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls 1330 ``x.__ge__(y)``. 1331 1332 A rich comparison method may return the singleton ``NotImplemented`` if it does 1333 not implement the operation for a given pair of arguments. By convention, 1334 ``False`` and ``True`` are returned for a successful comparison. However, these 1335 methods can return any value, so if the comparison operator is used in a Boolean 1336 context (e.g., in the condition of an ``if`` statement), Python will call 1337 :func:`bool` on the value to determine if the result is true or false. 1338 1339 There are no implied relationships among the comparison operators. The truth 1340 of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when 1341 defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the 1342 operators will behave as expected. See the paragraph on :meth:`__hash__` for 1343 some important notes on creating :term:`hashable` objects which support 1344 custom comparison operations and are usable as dictionary keys. 1345 1346 There are no swapped-argument versions of these methods (to be used when the 1347 left argument does not support the operation but the right argument does); 1348 rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection, 1349 :meth:`__le__` and :meth:`__ge__` are each other's reflection, and 1350 :meth:`__eq__` and :meth:`__ne__` are their own reflection. 1351 1352 Arguments to rich comparison methods are never coerced. 1353 1354 1355.. method:: object.__cmp__(self, other) 1356 1357 .. index:: 1358 builtin: cmp 1359 single: comparisons 1360 1361 Called by comparison operations if rich comparison (see above) is not 1362 defined. Should return a negative integer if ``self < other``, zero if 1363 ``self == other``, a positive integer if ``self > other``. If no 1364 :meth:`__cmp__`, :meth:`__eq__` or :meth:`__ne__` operation is defined, class 1365 instances are compared by object identity ("address"). See also the 1366 description of :meth:`__hash__` for some important notes on creating 1367 :term:`hashable` objects which support custom comparison operations and are 1368 usable as dictionary keys. (Note: the restriction that exceptions are not 1369 propagated by :meth:`__cmp__` has been removed since Python 1.5.) 1370 1371 1372.. method:: object.__rcmp__(self, other) 1373 1374 .. versionchanged:: 2.1 1375 No longer supported. 1376 1377 1378.. method:: object.__hash__(self) 1379 1380 .. index:: 1381 object: dictionary 1382 builtin: hash 1383 1384 Called by built-in function :func:`hash` and for operations on members of 1385 hashed collections including :class:`set`, :class:`frozenset`, and 1386 :class:`dict`. :meth:`__hash__` should return an integer. The only required 1387 property is that objects which compare equal have the same hash value; it is 1388 advised to somehow mix together (e.g. using exclusive or) the hash values for 1389 the components of the object that also play a part in comparison of objects. 1390 1391 If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it 1392 should not define a :meth:`__hash__` operation either; if it defines 1393 :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances 1394 will not be usable in hashed collections. If a class defines mutable objects 1395 and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not 1396 implement :meth:`__hash__`, since hashable collection implementations require 1397 that a object's hash value is immutable (if the object's hash value changes, 1398 it will be in the wrong hash bucket). 1399 1400 User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods 1401 by default; with them, all objects compare unequal (except with themselves) 1402 and ``x.__hash__()`` returns ``id(x)``. 1403 1404 Classes which inherit a :meth:`__hash__` method from a parent class but 1405 change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash 1406 value returned is no longer appropriate (e.g. by switching to a value-based 1407 concept of equality instead of the default identity based equality) can 1408 explicitly flag themselves as being unhashable by setting ``__hash__ = None`` 1409 in the class definition. Doing so means that not only will instances of the 1410 class raise an appropriate :exc:`TypeError` when a program attempts to 1411 retrieve their hash value, but they will also be correctly identified as 1412 unhashable when checking ``isinstance(obj, collections.Hashable)`` (unlike 1413 classes which define their own :meth:`__hash__` to explicitly raise 1414 :exc:`TypeError`). 1415 1416 .. versionchanged:: 2.5 1417 :meth:`__hash__` may now also return a long integer object; the 32-bit 1418 integer is then derived from the hash of that object. 1419 1420 .. versionchanged:: 2.6 1421 :attr:`__hash__` may now be set to :const:`None` to explicitly flag 1422 instances of a class as unhashable. 1423 1424 1425.. method:: object.__nonzero__(self) 1426 1427 .. index:: single: __len__() (mapping object method) 1428 1429 Called to implement truth value testing and the built-in operation ``bool()``; 1430 should return ``False`` or ``True``, or their integer equivalents ``0`` or 1431 ``1``. When this method is not defined, :meth:`__len__` is called, if it is 1432 defined, and the object is considered true if its result is nonzero. 1433 If a class defines neither :meth:`__len__` nor :meth:`__nonzero__`, all its 1434 instances are considered true. 1435 1436 1437.. method:: object.__unicode__(self) 1438 1439 .. index:: builtin: unicode 1440 1441 Called to implement :func:`unicode` builtin; should return a Unicode object. 1442 When this method is not defined, string conversion is attempted, and the result 1443 of string conversion is converted to Unicode using the system default encoding. 1444 1445 1446.. _attribute-access: 1447 1448Customizing attribute access 1449---------------------------- 1450 1451The following methods can be defined to customize the meaning of attribute 1452access (use of, assignment to, or deletion of ``x.name``) for class instances. 1453 1454 1455.. method:: object.__getattr__(self, name) 1456 1457 Called when an attribute lookup has not found the attribute in the usual places 1458 (i.e. it is not an instance attribute nor is it found in the class tree for 1459 ``self``). ``name`` is the attribute name. This method should return the 1460 (computed) attribute value or raise an :exc:`AttributeError` exception. 1461 1462 .. index:: single: __setattr__() (object method) 1463 1464 Note that if the attribute is found through the normal mechanism, 1465 :meth:`__getattr__` is not called. (This is an intentional asymmetry between 1466 :meth:`__getattr__` and :meth:`__setattr__`.) This is done both for efficiency 1467 reasons and because otherwise :meth:`__getattr__` would have no way to access 1468 other attributes of the instance. Note that at least for instance variables, 1469 you can fake total control by not inserting any values in the instance attribute 1470 dictionary (but instead inserting them in another object). See the 1471 :meth:`__getattribute__` method below for a way to actually get total control in 1472 new-style classes. 1473 1474 1475.. method:: object.__setattr__(self, name, value) 1476 1477 Called when an attribute assignment is attempted. This is called instead of the 1478 normal mechanism (i.e. store the value in the instance dictionary). *name* is 1479 the attribute name, *value* is the value to be assigned to it. 1480 1481 .. index:: single: __dict__ (instance attribute) 1482 1483 If :meth:`__setattr__` wants to assign to an instance attribute, it should not 1484 simply execute ``self.name = value`` --- this would cause a recursive call to 1485 itself. Instead, it should insert the value in the dictionary of instance 1486 attributes, e.g., ``self.__dict__[name] = value``. For new-style classes, 1487 rather than accessing the instance dictionary, it should call the base class 1488 method with the same name, for example, ``object.__setattr__(self, name, 1489 value)``. 1490 1491 1492.. method:: object.__delattr__(self, name) 1493 1494 Like :meth:`__setattr__` but for attribute deletion instead of assignment. This 1495 should only be implemented if ``del obj.name`` is meaningful for the object. 1496 1497 1498.. _new-style-attribute-access: 1499 1500More attribute access for new-style classes 1501^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1502 1503The following methods only apply to new-style classes. 1504 1505 1506.. method:: object.__getattribute__(self, name) 1507 1508 Called unconditionally to implement attribute accesses for instances of the 1509 class. If the class also defines :meth:`__getattr__`, the latter will not be 1510 called unless :meth:`__getattribute__` either calls it explicitly or raises an 1511 :exc:`AttributeError`. This method should return the (computed) attribute value 1512 or raise an :exc:`AttributeError` exception. In order to avoid infinite 1513 recursion in this method, its implementation should always call the base class 1514 method with the same name to access any attributes it needs, for example, 1515 ``object.__getattribute__(self, name)``. 1516 1517 .. note:: 1518 1519 This method may still be bypassed when looking up special methods as the 1520 result of implicit invocation via language syntax or builtin functions. 1521 See :ref:`new-style-special-lookup`. 1522 1523 1524.. _descriptors: 1525 1526Implementing Descriptors 1527^^^^^^^^^^^^^^^^^^^^^^^^ 1528 1529The following methods only apply when an instance of the class containing the 1530method (a so-called *descriptor* class) appears in the class dictionary of 1531another new-style class, known as the *owner* class. In the examples below, "the 1532attribute" refers to the attribute whose name is the key of the property in the 1533owner class' ``__dict__``. Descriptors can only be implemented as new-style 1534classes themselves. 1535 1536 1537.. method:: object.__get__(self, instance, owner) 1538 1539 Called to get the attribute of the owner class (class attribute access) or of an 1540 instance of that class (instance attribute access). *owner* is always the owner 1541 class, while *instance* is the instance that the attribute was accessed through, 1542 or ``None`` when the attribute is accessed through the *owner*. This method 1543 should return the (computed) attribute value or raise an :exc:`AttributeError` 1544 exception. 1545 1546 1547.. method:: object.__set__(self, instance, value) 1548 1549 Called to set the attribute on an instance *instance* of the owner class to a 1550 new value, *value*. 1551 1552 1553.. method:: object.__delete__(self, instance) 1554 1555 Called to delete the attribute on an instance *instance* of the owner class. 1556 1557 1558.. _descriptor-invocation: 1559 1560Invoking Descriptors 1561^^^^^^^^^^^^^^^^^^^^ 1562 1563In general, a descriptor is an object attribute with "binding behavior", one 1564whose attribute access has been overridden by methods in the descriptor 1565protocol: :meth:`__get__`, :meth:`__set__`, and :meth:`__delete__`. If any of 1566those methods are defined for an object, it is said to be a descriptor. 1567 1568The default behavior for attribute access is to get, set, or delete the 1569attribute from an object's dictionary. For instance, ``a.x`` has a lookup chain 1570starting with ``a.__dict__['x']``, then ``type(a).__dict__['x']``, and 1571continuing through the base classes of ``type(a)`` excluding metaclasses. 1572 1573However, if the looked-up value is an object defining one of the descriptor 1574methods, then Python may override the default behavior and invoke the descriptor 1575method instead. Where this occurs in the precedence chain depends on which 1576descriptor methods were defined and how they were called. Note that descriptors 1577are only invoked for new style objects or classes (ones that subclass 1578:class:`object()` or :class:`type()`). 1579 1580The starting point for descriptor invocation is a binding, ``a.x``. How the 1581arguments are assembled depends on ``a``: 1582 1583Direct Call 1584 The simplest and least common call is when user code directly invokes a 1585 descriptor method: ``x.__get__(a)``. 1586 1587Instance Binding 1588 If binding to a new-style object instance, ``a.x`` is transformed into the call: 1589 ``type(a).__dict__['x'].__get__(a, type(a))``. 1590 1591Class Binding 1592 If binding to a new-style class, ``A.x`` is transformed into the call: 1593 ``A.__dict__['x'].__get__(None, A)``. 1594 1595Super Binding 1596 If ``a`` is an instance of :class:`super`, then the binding ``super(B, 1597 obj).m()`` searches ``obj.__class__.__mro__`` for the base class ``A`` 1598 immediately preceding ``B`` and then invokes the descriptor with the call: 1599 ``A.__dict__['m'].__get__(obj, A)``. 1600 1601For instance bindings, the precedence of descriptor invocation depends on the 1602which descriptor methods are defined. Normally, data descriptors define both 1603:meth:`__get__` and :meth:`__set__`, while non-data descriptors have just the 1604:meth:`__get__` method. Data descriptors always override a redefinition in an 1605instance dictionary. In contrast, non-data descriptors can be overridden by 1606instances. [#]_ 1607 1608Python methods (including :func:`staticmethod` and :func:`classmethod`) are 1609implemented as non-data descriptors. Accordingly, instances can redefine and 1610override methods. This allows individual instances to acquire behaviors that 1611differ from other instances of the same class. 1612 1613The :func:`property` function is implemented as a data descriptor. Accordingly, 1614instances cannot override the behavior of a property. 1615 1616 1617.. _slots: 1618 1619__slots__ 1620^^^^^^^^^ 1621 1622By default, instances of both old and new-style classes have a dictionary for 1623attribute storage. This wastes space for objects having very few instance 1624variables. The space consumption can become acute when creating large numbers 1625of instances. 1626 1627The default can be overridden by defining *__slots__* in a new-style class 1628definition. The *__slots__* declaration takes a sequence of instance variables 1629and reserves just enough space in each instance to hold a value for each 1630variable. Space is saved because *__dict__* is not created for each instance. 1631 1632 1633.. data:: __slots__ 1634 1635 This class variable can be assigned a string, iterable, or sequence of strings 1636 with variable names used by instances. If defined in a new-style class, 1637 *__slots__* reserves space for the declared variables and prevents the automatic 1638 creation of *__dict__* and *__weakref__* for each instance. 1639 1640 .. versionadded:: 2.2 1641 1642Notes on using *__slots__* 1643 1644* When inheriting from a class without *__slots__*, the *__dict__* attribute of 1645 that class will always be accessible, so a *__slots__* definition in the 1646 subclass is meaningless. 1647 1648* Without a *__dict__* variable, instances cannot be assigned new variables not 1649 listed in the *__slots__* definition. Attempts to assign to an unlisted 1650 variable name raises :exc:`AttributeError`. If dynamic assignment of new 1651 variables is desired, then add ``'__dict__'`` to the sequence of strings in the 1652 *__slots__* declaration. 1653 1654 .. versionchanged:: 2.3 1655 Previously, adding ``'__dict__'`` to the *__slots__* declaration would not 1656 enable the assignment of new attributes not specifically listed in the sequence 1657 of instance variable names. 1658 1659* Without a *__weakref__* variable for each instance, classes defining 1660 *__slots__* do not support weak references to its instances. If weak reference 1661 support is needed, then add ``'__weakref__'`` to the sequence of strings in the 1662 *__slots__* declaration. 1663 1664 .. versionchanged:: 2.3 1665 Previously, adding ``'__weakref__'`` to the *__slots__* declaration would not 1666 enable support for weak references. 1667 1668* *__slots__* are implemented at the class level by creating descriptors 1669 (:ref:`descriptors`) for each variable name. As a result, class attributes 1670 cannot be used to set default values for instance variables defined by 1671 *__slots__*; otherwise, the class attribute would overwrite the descriptor 1672 assignment. 1673 1674* If a class defines a slot also defined in a base class, the instance variable 1675 defined by the base class slot is inaccessible (except by retrieving its 1676 descriptor directly from the base class). This renders the meaning of the 1677 program undefined. In the future, a check may be added to prevent this. 1678 1679* The action of a *__slots__* declaration is limited to the class where it is 1680 defined. As a result, subclasses will have a *__dict__* unless they also define 1681 *__slots__*. 1682 1683* Nonempty *__slots__* does not work for classes derived from "variable-length" 1684 built-in types such as :class:`long`, :class:`str` and :class:`tuple`. 1685 1686* Any non-string iterable may be assigned to *__slots__*. Mappings may also be 1687 used; however, in the future, special meaning may be assigned to the values 1688 corresponding to each key. 1689 1690* *__class__* assignment works only if both classes have the same *__slots__*. 1691 1692 .. versionchanged:: 2.6 1693 Previously, *__class__* assignment raised an error if either new or old class 1694 had *__slots__*. 1695 1696 1697.. _metaclasses: 1698 1699Customizing class creation 1700-------------------------- 1701 1702By default, new-style classes are constructed using :func:`type`. A class 1703definition is read into a separate namespace and the value of class name is 1704bound to the result of ``type(name, bases, dict)``. 1705 1706When the class definition is read, if *__metaclass__* is defined then the 1707callable assigned to it will be called instead of :func:`type`. This allows 1708classes or functions to be written which monitor or alter the class creation 1709process: 1710 1711* Modifying the class dictionary prior to the class being created. 1712 1713* Returning an instance of another class -- essentially performing the role of a 1714 factory function. 1715 1716These steps will have to be performed in the metaclass's :meth:`__new__` method 1717-- :meth:`type.__new__` can then be called from this method to create a class 1718with different properties. This example adds a new element to the class 1719dictionary before creating the class:: 1720 1721 class metacls(type): 1722 def __new__(mcs, name, bases, dict): 1723 dict['foo'] = 'metacls was here' 1724 return type.__new__(mcs, name, bases, dict) 1725 1726You can of course also override other class methods (or add new methods); for 1727example defining a custom :meth:`__call__` method in the metaclass allows custom 1728behavior when the class is called, e.g. not always creating a new instance. 1729 1730 1731.. data:: __metaclass__ 1732 1733 This variable can be any callable accepting arguments for ``name``, ``bases``, 1734 and ``dict``. Upon class creation, the callable is used instead of the built-in 1735 :func:`type`. 1736 1737 .. versionadded:: 2.2 1738 1739The appropriate metaclass is determined by the following precedence rules: 1740 1741* If ``dict['__metaclass__']`` exists, it is used. 1742 1743* Otherwise, if there is at least one base class, its metaclass is used (this 1744 looks for a *__class__* attribute first and if not found, uses its type). 1745 1746* Otherwise, if a global variable named __metaclass__ exists, it is used. 1747 1748* Otherwise, the old-style, classic metaclass (types.ClassType) is used. 1749 1750The potential uses for metaclasses are boundless. Some ideas that have been 1751explored including logging, interface checking, automatic delegation, automatic 1752property creation, proxies, frameworks, and automatic resource 1753locking/synchronization. 1754 1755 1756.. _callable-types: 1757 1758Emulating callable objects 1759-------------------------- 1760 1761 1762.. method:: object.__call__(self[, args...]) 1763 1764 .. index:: pair: call; instance 1765 1766 Called when the instance is "called" as a function; if this method is defined, 1767 ``x(arg1, arg2, ...)`` is a shorthand for ``x.__call__(arg1, arg2, ...)``. 1768 1769 1770.. _sequence-types: 1771 1772Emulating container types 1773------------------------- 1774 1775The following methods can be defined to implement container objects. Containers 1776usually are sequences (such as lists or tuples) or mappings (like dictionaries), 1777but can represent other containers as well. The first set of methods is used 1778either to emulate a sequence or to emulate a mapping; the difference is that for 1779a sequence, the allowable keys should be the integers *k* for which ``0 <= k < 1780N`` where *N* is the length of the sequence, or slice objects, which define a 1781range of items. (For backwards compatibility, the method :meth:`__getslice__` 1782(see below) can also be defined to handle simple, but not extended slices.) It 1783is also recommended that mappings provide the methods :meth:`keys`, 1784:meth:`values`, :meth:`items`, :meth:`has_key`, :meth:`get`, :meth:`clear`, 1785:meth:`setdefault`, :meth:`iterkeys`, :meth:`itervalues`, :meth:`iteritems`, 1786:meth:`pop`, :meth:`popitem`, :meth:`copy`, and :meth:`update` behaving similar 1787to those for Python's standard dictionary objects. The :mod:`UserDict` module 1788provides a :class:`DictMixin` class to help create those methods from a base set 1789of :meth:`__getitem__`, :meth:`__setitem__`, :meth:`__delitem__`, and 1790:meth:`keys`. Mutable sequences should provide methods :meth:`append`, 1791:meth:`count`, :meth:`index`, :meth:`extend`, :meth:`insert`, :meth:`pop`, 1792:meth:`remove`, :meth:`reverse` and :meth:`sort`, like Python standard list 1793objects. Finally, sequence types should implement addition (meaning 1794concatenation) and multiplication (meaning repetition) by defining the methods 1795:meth:`__add__`, :meth:`__radd__`, :meth:`__iadd__`, :meth:`__mul__`, 1796:meth:`__rmul__` and :meth:`__imul__` described below; they should not define 1797:meth:`__coerce__` or other numerical operators. It is recommended that both 1798mappings and sequences implement the :meth:`__contains__` method to allow 1799efficient use of the ``in`` operator; for mappings, ``in`` should be equivalent 1800of :meth:`has_key`; for sequences, it should search through the values. It is 1801further recommended that both mappings and sequences implement the 1802:meth:`__iter__` method to allow efficient iteration through the container; for 1803mappings, :meth:`__iter__` should be the same as :meth:`iterkeys`; for 1804sequences, it should iterate through the values. 1805 1806 1807.. method:: object.__len__(self) 1808 1809 .. index:: 1810 builtin: len 1811 single: __nonzero__() (object method) 1812 1813 Called to implement the built-in function :func:`len`. Should return the length 1814 of the object, an integer ``>=`` 0. Also, an object that doesn't define a 1815 :meth:`__nonzero__` method and whose :meth:`__len__` method returns zero is 1816 considered to be false in a Boolean context. 1817 1818 1819.. method:: object.__getitem__(self, key) 1820 1821 .. index:: object: slice 1822 1823 Called to implement evaluation of ``self[key]``. For sequence types, the 1824 accepted keys should be integers and slice objects. Note that the special 1825 interpretation of negative indexes (if the class wishes to emulate a sequence 1826 type) is up to the :meth:`__getitem__` method. If *key* is of an inappropriate 1827 type, :exc:`TypeError` may be raised; if of a value outside the set of indexes 1828 for the sequence (after any special interpretation of negative values), 1829 :exc:`IndexError` should be raised. For mapping types, if *key* is missing (not 1830 in the container), :exc:`KeyError` should be raised. 1831 1832 .. note:: 1833 1834 :keyword:`for` loops expect that an :exc:`IndexError` will be raised for illegal 1835 indexes to allow proper detection of the end of the sequence. 1836 1837 1838.. method:: object.__setitem__(self, key, value) 1839 1840 Called to implement assignment to ``self[key]``. Same note as for 1841 :meth:`__getitem__`. This should only be implemented for mappings if the 1842 objects support changes to the values for keys, or if new keys can be added, or 1843 for sequences if elements can be replaced. The same exceptions should be raised 1844 for improper *key* values as for the :meth:`__getitem__` method. 1845 1846 1847.. method:: object.__delitem__(self, key) 1848 1849 Called to implement deletion of ``self[key]``. Same note as for 1850 :meth:`__getitem__`. This should only be implemented for mappings if the 1851 objects support removal of keys, or for sequences if elements can be removed 1852 from the sequence. The same exceptions should be raised for improper *key* 1853 values as for the :meth:`__getitem__` method. 1854 1855 1856.. method:: object.__iter__(self) 1857 1858 This method is called when an iterator is required for a container. This method 1859 should return a new iterator object that can iterate over all the objects in the 1860 container. For mappings, it should iterate over the keys of the container, and 1861 should also be made available as the method :meth:`iterkeys`. 1862 1863 Iterator objects also need to implement this method; they are required to return 1864 themselves. For more information on iterator objects, see :ref:`typeiter`. 1865 1866 1867.. method:: object.__reversed__(self) 1868 1869 Called (if present) by the :func:`reversed` builtin to implement 1870 reverse iteration. It should return a new iterator object that iterates 1871 over all the objects in the container in reverse order. 1872 1873 If the :meth:`__reversed__` method is not provided, the :func:`reversed` 1874 builtin will fall back to using the sequence protocol (:meth:`__len__` and 1875 :meth:`__getitem__`). Objects that support the sequence protocol should 1876 only provide :meth:`__reversed__` if they can provide an implementation 1877 that is more efficient than the one provided by :func:`reversed`. 1878 1879 .. versionadded:: 2.6 1880 1881 1882The membership test operators (:keyword:`in` and :keyword:`not in`) are normally 1883implemented as an iteration through a sequence. However, container objects can 1884supply the following special method with a more efficient implementation, which 1885also does not require the object be a sequence. 1886 1887 1888.. method:: object.__contains__(self, item) 1889 1890 Called to implement membership test operators. Should return true if *item* is 1891 in *self*, false otherwise. For mapping objects, this should consider the keys 1892 of the mapping rather than the values or the key-item pairs. 1893 1894 1895.. _sequence-methods: 1896 1897Additional methods for emulation of sequence types 1898-------------------------------------------------- 1899 1900The following optional methods can be defined to further emulate sequence 1901objects. Immutable sequences methods should at most only define 1902:meth:`__getslice__`; mutable sequences might define all three methods. 1903 1904 1905.. method:: object.__getslice__(self, i, j) 1906 1907 .. deprecated:: 2.0 1908 Support slice objects as parameters to the :meth:`__getitem__` method. 1909 (However, built-in types in CPython currently still implement 1910 :meth:`__getslice__`. Therefore, you have to override it in derived 1911 classes when implementing slicing.) 1912 1913 Called to implement evaluation of ``self[i:j]``. The returned object should be 1914 of the same type as *self*. Note that missing *i* or *j* in the slice 1915 expression are replaced by zero or ``sys.maxint``, respectively. If negative 1916 indexes are used in the slice, the length of the sequence is added to that 1917 index. If the instance does not implement the :meth:`__len__` method, an 1918 :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this 1919 way are not still negative. Indexes which are greater than the length of the 1920 sequence are not modified. If no :meth:`__getslice__` is found, a slice object 1921 is created instead, and passed to :meth:`__getitem__` instead. 1922 1923 1924.. method:: object.__setslice__(self, i, j, sequence) 1925 1926 Called to implement assignment to ``self[i:j]``. Same notes for *i* and *j* as 1927 for :meth:`__getslice__`. 1928 1929 This method is deprecated. If no :meth:`__setslice__` is found, or for extended 1930 slicing of the form ``self[i:j:k]``, a slice object is created, and passed to 1931 :meth:`__setitem__`, instead of :meth:`__setslice__` being called. 1932 1933 1934.. method:: object.__delslice__(self, i, j) 1935 1936 Called to implement deletion of ``self[i:j]``. Same notes for *i* and *j* as for 1937 :meth:`__getslice__`. This method is deprecated. If no :meth:`__delslice__` is 1938 found, or for extended slicing of the form ``self[i:j:k]``, a slice object is 1939 created, and passed to :meth:`__delitem__`, instead of :meth:`__delslice__` 1940 being called. 1941 1942Notice that these methods are only invoked when a single slice with a single 1943colon is used, and the slice method is available. For slice operations 1944involving extended slice notation, or in absence of the slice methods, 1945:meth:`__getitem__`, :meth:`__setitem__` or :meth:`__delitem__` is called with a 1946slice object as argument. 1947 1948The following example demonstrate how to make your program or module compatible 1949with earlier versions of Python (assuming that methods :meth:`__getitem__`, 1950:meth:`__setitem__` and :meth:`__delitem__` support slice objects as 1951arguments):: 1952 1953 class MyClass: 1954 ... 1955 def __getitem__(self, index): 1956 ... 1957 def __setitem__(self, index, value): 1958 ... 1959 def __delitem__(self, index): 1960 ... 1961 1962 if sys.version_info < (2, 0): 1963 # They won't be defined if version is at least 2.0 final 1964 1965 def __getslice__(self, i, j): 1966 return self[max(0, i):max(0, j):] 1967 def __setslice__(self, i, j, seq): 1968 self[max(0, i):max(0, j):] = seq 1969 def __delslice__(self, i, j): 1970 del self[max(0, i):max(0, j):] 1971 ... 1972 1973Note the calls to :func:`max`; these are necessary because of the handling of 1974negative indices before the :meth:`__\*slice__` methods are called. When 1975negative indexes are used, the :meth:`__\*item__` methods receive them as 1976provided, but the :meth:`__\*slice__` methods get a "cooked" form of the index 1977values. For each negative index value, the length of the sequence is added to 1978the index before calling the method (which may still result in a negative 1979index); this is the customary handling of negative indexes by the built-in 1980sequence types, and the :meth:`__\*item__` methods are expected to do this as 1981well. However, since they should already be doing that, negative indexes cannot 1982be passed in; they must be constrained to the bounds of the sequence before 1983being passed to the :meth:`__\*item__` methods. Calling ``max(0, i)`` 1984conveniently returns the proper value. 1985 1986 1987.. _numeric-types: 1988 1989Emulating numeric types 1990----------------------- 1991 1992The following methods can be defined to emulate numeric objects. Methods 1993corresponding to operations that are not supported by the particular kind of 1994number implemented (e.g., bitwise operations for non-integral numbers) should be 1995left undefined. 1996 1997 1998.. method:: object.__add__(self, other) 1999 object.__sub__(self, other) 2000 object.__mul__(self, other) 2001 object.__floordiv__(self, other) 2002 object.__mod__(self, other) 2003 object.__divmod__(self, other) 2004 object.__pow__(self, other[, modulo]) 2005 object.__lshift__(self, other) 2006 object.__rshift__(self, other) 2007 object.__and__(self, other) 2008 object.__xor__(self, other) 2009 object.__or__(self, other) 2010 2011 .. index:: 2012 builtin: divmod 2013 builtin: pow 2014 builtin: pow 2015 2016 These methods are called to implement the binary arithmetic operations (``+``, 2017 ``-``, ``*``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, 2018 ``>>``, ``&``, ``^``, ``|``). For instance, to evaluate the expression 2019 ``x + y``, where *x* is an instance of a class that has an :meth:`__add__` 2020 method, ``x.__add__(y)`` is called. The :meth:`__divmod__` method should be the 2021 equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be 2022 related to :meth:`__truediv__` (described below). Note that :meth:`__pow__` 2023 should be defined to accept an optional third argument if the ternary version of 2024 the built-in :func:`pow` function is to be supported. 2025 2026 If one of those methods does not support the operation with the supplied 2027 arguments, it should return ``NotImplemented``. 2028 2029 2030.. method:: object.__div__(self, other) 2031 object.__truediv__(self, other) 2032 2033 The division operator (``/``) is implemented by these methods. The 2034 :meth:`__truediv__` method is used when ``__future__.division`` is in effect, 2035 otherwise :meth:`__div__` is used. If only one of these two methods is defined, 2036 the object will not support division in the alternate context; :exc:`TypeError` 2037 will be raised instead. 2038 2039 2040.. method:: object.__radd__(self, other) 2041 object.__rsub__(self, other) 2042 object.__rmul__(self, other) 2043 object.__rdiv__(self, other) 2044 object.__rtruediv__(self, other) 2045 object.__rfloordiv__(self, other) 2046 object.__rmod__(self, other) 2047 object.__rdivmod__(self, other) 2048 object.__rpow__(self, other) 2049 object.__rlshift__(self, other) 2050 object.__rrshift__(self, other) 2051 object.__rand__(self, other) 2052 object.__rxor__(self, other) 2053 object.__ror__(self, other) 2054 2055 .. index:: 2056 builtin: divmod 2057 builtin: pow 2058 2059 These methods are called to implement the binary arithmetic operations (``+``, 2060 ``-``, ``*``, ``/``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``, ``>>``, 2061 ``&``, ``^``, ``|``) with reflected (swapped) operands. These functions are 2062 only called if the left operand does not support the corresponding operation and 2063 the operands are of different types. [#]_ For instance, to evaluate the 2064 expression ``x - y``, where *y* is an instance of a class that has an 2065 :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if ``x.__sub__(y)`` returns 2066 *NotImplemented*. 2067 2068 .. index:: builtin: pow 2069 2070 Note that ternary :func:`pow` will not try calling :meth:`__rpow__` (the 2071 coercion rules would become too complicated). 2072 2073 .. note:: 2074 2075 If the right operand's type is a subclass of the left operand's type and that 2076 subclass provides the reflected method for the operation, this method will be 2077 called before the left operand's non-reflected method. This behavior allows 2078 subclasses to override their ancestors' operations. 2079 2080 2081.. method:: object.__iadd__(self, other) 2082 object.__isub__(self, other) 2083 object.__imul__(self, other) 2084 object.__idiv__(self, other) 2085 object.__itruediv__(self, other) 2086 object.__ifloordiv__(self, other) 2087 object.__imod__(self, other) 2088 object.__ipow__(self, other[, modulo]) 2089 object.__ilshift__(self, other) 2090 object.__irshift__(self, other) 2091 object.__iand__(self, other) 2092 object.__ixor__(self, other) 2093 object.__ior__(self, other) 2094 2095 These methods are called to implement the augmented arithmetic assignments 2096 (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``, 2097 ``&=``, ``^=``, ``|=``). These methods should attempt to do the operation 2098 in-place (modifying *self*) and return the result (which could be, but does 2099 not have to be, *self*). If a specific method is not defined, the augmented 2100 assignment falls back to the normal methods. For instance, to execute the 2101 statement ``x += y``, where *x* is an instance of a class that has an 2102 :meth:`__iadd__` method, ``x.__iadd__(y)`` is called. If *x* is an instance 2103 of a class that does not define a :meth:`__iadd__` method, ``x.__add__(y)`` 2104 and ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``. 2105 2106 2107.. method:: object.__neg__(self) 2108 object.__pos__(self) 2109 object.__abs__(self) 2110 object.__invert__(self) 2111 2112 .. index:: builtin: abs 2113 2114 Called to implement the unary arithmetic operations (``-``, ``+``, :func:`abs` 2115 and ``~``). 2116 2117 2118.. method:: object.__complex__(self) 2119 object.__int__(self) 2120 object.__long__(self) 2121 object.__float__(self) 2122 2123 .. index:: 2124 builtin: complex 2125 builtin: int 2126 builtin: long 2127 builtin: float 2128 2129 Called to implement the built-in functions :func:`complex`, :func:`int`, 2130 :func:`long`, and :func:`float`. Should return a value of the appropriate type. 2131 2132 2133.. method:: object.__oct__(self) 2134 object.__hex__(self) 2135 2136 .. index:: 2137 builtin: oct 2138 builtin: hex 2139 2140 Called to implement the built-in functions :func:`oct` and :func:`hex`. Should 2141 return a string value. 2142 2143 2144.. method:: object.__index__(self) 2145 2146 Called to implement :func:`operator.index`. Also called whenever Python needs 2147 an integer object (such as in slicing). Must return an integer (int or long). 2148 2149 .. versionadded:: 2.5 2150 2151 2152.. method:: object.__coerce__(self, other) 2153 2154 Called to implement "mixed-mode" numeric arithmetic. Should either return a 2155 2-tuple containing *self* and *other* converted to a common numeric type, or 2156 ``None`` if conversion is impossible. When the common type would be the type of 2157 ``other``, it is sufficient to return ``None``, since the interpreter will also 2158 ask the other object to attempt a coercion (but sometimes, if the implementation 2159 of the other type cannot be changed, it is useful to do the conversion to the 2160 other type here). A return value of ``NotImplemented`` is equivalent to 2161 returning ``None``. 2162 2163 2164.. _coercion-rules: 2165 2166Coercion rules 2167-------------- 2168 2169This section used to document the rules for coercion. As the language has 2170evolved, the coercion rules have become hard to document precisely; documenting 2171what one version of one particular implementation does is undesirable. Instead, 2172here are some informal guidelines regarding coercion. In Python 3.0, coercion 2173will not be supported. 2174 2175* 2176 2177 If the left operand of a % operator is a string or Unicode object, no coercion 2178 takes place and the string formatting operation is invoked instead. 2179 2180* 2181 2182 It is no longer recommended to define a coercion operation. Mixed-mode 2183 operations on types that don't define coercion pass the original arguments to 2184 the operation. 2185 2186* 2187 2188 New-style classes (those derived from :class:`object`) never invoke the 2189 :meth:`__coerce__` method in response to a binary operator; the only time 2190 :meth:`__coerce__` is invoked is when the built-in function :func:`coerce` is 2191 called. 2192 2193* 2194 2195 For most intents and purposes, an operator that returns ``NotImplemented`` is 2196 treated the same as one that is not implemented at all. 2197 2198* 2199 2200 Below, :meth:`__op__` and :meth:`__rop__` are used to signify the generic method 2201 names corresponding to an operator; :meth:`__iop__` is used for the 2202 corresponding in-place operator. For example, for the operator '``+``', 2203 :meth:`__add__` and :meth:`__radd__` are used for the left and right variant of 2204 the binary operator, and :meth:`__iadd__` for the in-place variant. 2205 2206* 2207 2208 For objects *x* and *y*, first ``x.__op__(y)`` is tried. If this is not 2209 implemented or returns ``NotImplemented``, ``y.__rop__(x)`` is tried. If this 2210 is also not implemented or returns ``NotImplemented``, a :exc:`TypeError` 2211 exception is raised. But see the following exception: 2212 2213* 2214 2215 Exception to the previous item: if the left operand is an instance of a built-in 2216 type or a new-style class, and the right operand is an instance of a proper 2217 subclass of that type or class and overrides the base's :meth:`__rop__` method, 2218 the right operand's :meth:`__rop__` method is tried *before* the left operand's 2219 :meth:`__op__` method. 2220 2221 This is done so that a subclass can completely override binary operators. 2222 Otherwise, the left operand's :meth:`__op__` method would always accept the 2223 right operand: when an instance of a given class is expected, an instance of a 2224 subclass of that class is always acceptable. 2225 2226* 2227 2228 When either operand type defines a coercion, this coercion is called before that 2229 type's :meth:`__op__` or :meth:`__rop__` method is called, but no sooner. If 2230 the coercion returns an object of a different type for the operand whose 2231 coercion is invoked, part of the process is redone using the new object. 2232 2233* 2234 2235 When an in-place operator (like '``+=``') is used, if the left operand 2236 implements :meth:`__iop__`, it is invoked without any coercion. When the 2237 operation falls back to :meth:`__op__` and/or :meth:`__rop__`, the normal 2238 coercion rules apply. 2239 2240* 2241 2242 In ``x + y``, if *x* is a sequence that implements sequence concatenation, 2243 sequence concatenation is invoked. 2244 2245* 2246 2247 In ``x * y``, if one operator is a sequence that implements sequence 2248 repetition, and the other is an integer (:class:`int` or :class:`long`), 2249 sequence repetition is invoked. 2250 2251* 2252 2253 Rich comparisons (implemented by methods :meth:`__eq__` and so on) never use 2254 coercion. Three-way comparison (implemented by :meth:`__cmp__`) does use 2255 coercion under the same conditions as other binary operations use it. 2256 2257* 2258 2259 In the current implementation, the built-in numeric types :class:`int`, 2260 :class:`long` and :class:`float` do not use coercion; the type :class:`complex` 2261 however does use coercion for binary operators and rich comparisons, despite 2262 the above rules. The difference can become apparent when subclassing these 2263 types. Over time, the type :class:`complex` may be fixed to avoid coercion. 2264 All these types implement a :meth:`__coerce__` method, for use by the built-in 2265 :func:`coerce` function. 2266 2267 2268.. _context-managers: 2269 2270With Statement Context Managers 2271------------------------------- 2272 2273.. versionadded:: 2.5 2274 2275A :dfn:`context manager` is an object that defines the runtime context to be 2276established when executing a :keyword:`with` statement. The context manager 2277handles the entry into, and the exit from, the desired runtime context for the 2278execution of the block of code. Context managers are normally invoked using the 2279:keyword:`with` statement (described in section :ref:`with`), but can also be 2280used by directly invoking their methods. 2281 2282.. index:: 2283 statement: with 2284 single: context manager 2285 2286Typical uses of context managers include saving and restoring various kinds of 2287global state, locking and unlocking resources, closing opened files, etc. 2288 2289For more information on context managers, see :ref:`typecontextmanager`. 2290 2291 2292.. method:: object.__enter__(self) 2293 2294 Enter the runtime context related to this object. The :keyword:`with` statement 2295 will bind this method's return value to the target(s) specified in the 2296 :keyword:`as` clause of the statement, if any. 2297 2298 2299.. method:: object.__exit__(self, exc_type, exc_value, traceback) 2300 2301 Exit the runtime context related to this object. The parameters describe the 2302 exception that caused the context to be exited. If the context was exited 2303 without an exception, all three arguments will be :const:`None`. 2304 2305 If an exception is supplied, and the method wishes to suppress the exception 2306 (i.e., prevent it from being propagated), it should return a true value. 2307 Otherwise, the exception will be processed normally upon exit from this method. 2308 2309 Note that :meth:`__exit__` methods should not reraise the passed-in exception; 2310 this is the caller's responsibility. 2311 2312 2313.. seealso:: 2314 2315 :pep:`0343` - The "with" statement 2316 The specification, background, and examples for the Python :keyword:`with` 2317 statement. 2318 2319 2320.. _old-style-special-lookup: 2321 2322Special method lookup for old-style classes 2323------------------------------------------- 2324 2325For old-style classes, special methods are always looked up in exactly the 2326same way as any other method or attribute. This is the case regardless of 2327whether the method is being looked up explicitly as in ``x.__getitem__(i)`` 2328or implicitly as in ``x[i]``. 2329 2330This behaviour means that special methods may exhibit different behaviour 2331for different instances of a single old-style class if the appropriate 2332special attributes are set differently:: 2333 2334 >>> class C: 2335 ... pass 2336 ... 2337 >>> c1 = C() 2338 >>> c2 = C() 2339 >>> c1.__len__ = lambda: 5 2340 >>> c2.__len__ = lambda: 9 2341 >>> len(c1) 2342 5 2343 >>> len(c2) 2344 9 2345 2346 2347.. _new-style-special-lookup: 2348 2349Special method lookup for new-style classes 2350------------------------------------------- 2351 2352For new-style classes, implicit invocations of special methods are only guaranteed 2353to work correctly if defined on an object's type, not in the object's instance 2354dictionary. That behaviour is the reason why the following code raises an 2355exception (unlike the equivalent example with old-style classes):: 2356 2357 >>> class C(object): 2358 ... pass 2359 ... 2360 >>> c = C() 2361 >>> c.__len__ = lambda: 5 2362 >>> len(c) 2363 Traceback (most recent call last): 2364 File "<stdin>", line 1, in <module> 2365 TypeError: object of type 'C' has no len() 2366 2367The rationale behind this behaviour lies with a number of special methods such 2368as :meth:`__hash__` and :meth:`__repr__` that are implemented by all objects, 2369including type objects. If the implicit lookup of these methods used the 2370conventional lookup process, they would fail when invoked on the type object 2371itself:: 2372 2373 >>> 1 .__hash__() == hash(1) 2374 True 2375 >>> int.__hash__() == hash(int) 2376 Traceback (most recent call last): 2377 File "<stdin>", line 1, in <module> 2378 TypeError: descriptor '__hash__' of 'int' object needs an argument 2379 2380Incorrectly attempting to invoke an unbound method of a class in this way is 2381sometimes referred to as 'metaclass confusion', and is avoided by bypassing 2382the instance when looking up special methods:: 2383 2384 >>> type(1).__hash__(1) == hash(1) 2385 True 2386 >>> type(int).__hash__(int) == hash(int) 2387 True 2388 2389In addition to bypassing any instance attributes in the interest of 2390correctness, implicit special method lookup generally also bypasses the 2391:meth:`__getattribute__` method even of the object's metaclass:: 2392 2393 >>> class Meta(type): 2394 ... def __getattribute__(*args): 2395 ... print "Metaclass getattribute invoked" 2396 ... return type.__getattribute__(*args) 2397 ... 2398 >>> class C(object): 2399 ... __metaclass__ = Meta 2400 ... def __len__(self): 2401 ... return 10 2402 ... def __getattribute__(*args): 2403 ... print "Class getattribute invoked" 2404 ... return object.__getattribute__(*args) 2405 ... 2406 >>> c = C() 2407 >>> c.__len__() # Explicit lookup via instance 2408 Class getattribute invoked 2409 10 2410 >>> type(c).__len__(c) # Explicit lookup via type 2411 Metaclass getattribute invoked 2412 10 2413 >>> len(c) # Implicit lookup 2414 10 2415 2416Bypassing the :meth:`__getattribute__` machinery in this fashion 2417provides significant scope for speed optimisations within the 2418interpreter, at the cost of some flexibility in the handling of 2419special methods (the special method *must* be set on the class 2420object itself in order to be consistently invoked by the interpreter). 2421 2422 2423.. rubric:: Footnotes 2424 2425.. [#] It *is* possible in some cases to change an object's type, under certain 2426 controlled conditions. It generally isn't a good idea though, since it can 2427 lead to some very strange behaviour if it is handled incorrectly. 2428 2429.. [#] A descriptor can define any combination of :meth:`__get__`, 2430 :meth:`__set__` and :meth:`__delete__`. If it does not define :meth:`__get__`, 2431 then accessing the attribute even on an instance will return the descriptor 2432 object itself. If the descriptor defines :meth:`__set__` and/or 2433 :meth:`__delete__`, it is a data descriptor; if it defines neither, it is a 2434 non-data descriptor. 2435 2436.. [#] For operands of the same type, it is assumed that if the non-reflected method 2437 (such as :meth:`__add__`) fails the operation is not supported, which is why the 2438 reflected method is not called. 2439