/Doc/reference/datamodel.rst

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