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