1 

     2 .. _datamodel:

     3 

     4 **********

     5 Data model

     6 **********

     7 

     8 

     9 .. _objects:

    10 

    11 Objects, 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

    19 is represented by objects or by relations between objects. (In a sense, and in

    20 conformance to Von Neumann's model of a "stored program computer," code is also

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

    32 Every object has an identity, a type and a value.  An object's *identity* never

    33 changes once it has been created; you may think of it as the object's address in

    34 memory.  The ':keyword:`is`' operator compares the identity of two objects; the

    35 :func:`id` function returns an integer representing its identity (currently

    36 implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_

    37 An object's type determines the operations that the object supports (e.g., "does

    38 it have a length?") and also defines the possible values for objects of that

    39 type.  The :func:`type` function returns an object's type (which is an object

    40 itself).  The *value* of some objects can change.  Objects whose value can

    41 change are said to be *mutable*; objects whose value is unchangeable once they

    42 are created are called *immutable*. (The value of an immutable container object

    43 that contains a reference to a mutable object can change when the latter's value

    44 is changed; however the container is still considered immutable, because the

    45 collection of objects it contains cannot be changed.  So, immutability is not

    46 strictly the same as having an unchangeable value, it is more subtle.) An

    47 object's mutability is determined by its type; for instance, numbers, strings

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

    55 Objects are never explicitly destroyed; however, when they become unreachable

    56 they may be garbage-collected.  An implementation is allowed to postpone garbage

    57 collection or omit it altogether --- it is a matter of implementation quality

    58 how garbage collection is implemented, as long as no objects are collected that

    59 are still reachable.  (Implementation note: the current implementation uses a

    60 reference-counting scheme with (optional) delayed detection of cyclically linked

    61 garbage, which collects most objects as soon as they become unreachable, but is

    62 not guaranteed to collect garbage containing circular references.  See the

    63 documentation of the :mod:`gc` module for information on controlling the

    64 collection of cyclic garbage.)

    65 

    66 Note that the use of the implementation's tracing or debugging facilities may

    67 keep objects alive that would normally be collectable. Also note that catching

    68 an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep

    69 objects alive.

    70 

    71 Some objects contain references to "external" resources such as open files or

    72 windows.  It is understood that these resources are freed when the object is

    73 garbage-collected, but since garbage collection is not guaranteed to happen,

    74 such objects also provide an explicit way to release the external resource,

    75 usually a :meth:`close` method. Programs are strongly recommended to explicitly

    76 close such objects.  The ':keyword:`try`...\ :keyword:`finally`' statement

    77 provides a convenient way to do this.

    78 

    79 .. index:: single: container

    80 

    81 Some objects contain references to other objects; these are called *containers*.

    82 Examples of containers are tuples, lists and dictionaries.  The references are

    83 part of a container's value.  In most cases, when we talk about the value of a

    84 container, we imply the values, not the identities of the contained objects;

    85 however, when we talk about the mutability of a container, only the identities

    86 of the immediately contained objects are implied.  So, if an immutable container

    87 (like a tuple) contains a reference to a mutable object, its value changes if

    88 that mutable object is changed.

    89 

    90 Types affect almost all aspects of object behavior.  Even the importance of

    91 object identity is affected in some sense: for immutable types, operations that

    92 compute new values may actually return a reference to any existing object with

    93 the same type and value, while for mutable objects this is not allowed.  E.g.,

    94 after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object

    95 with the value one, depending on the implementation, but after ``c = []; d =

    96 []``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly

    97 created empty lists. (Note that ``c = d = []`` assigns the same object to both

    98 ``c`` and ``d``.)

    99 

   100 

   101 .. _types:

   102 

   103 The standard type hierarchy

   104 ===========================

   105 

   106 .. index::

   107    single: type

   108    pair: data; type

   109    pair: type; hierarchy

   110    pair: extension; module

   111    pair: C; language

   112 

   113 Below is a list of the types that are built into Python.  Extension modules

   114 (written in C, Java, or other languages, depending on the implementation) can

   115 define additional types.  Future versions of Python may add types to the type

   116 hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).

   117 

   118 .. index::

   119    single: attribute

   120    pair: special; attribute

   121    triple: generic; special; attribute

   122 

   123 Some of the type descriptions below contain a paragraph listing 'special

   124 attributes.'  These are attributes that provide access to the implementation and

   125 are not intended for general use.  Their definition may change in the future.

   126 

   127 None

   128    .. index:: object: None

   129 

   130    This type has a single value.  There is a single object with this value. This

   131    object is accessed through the built-in name ``None``. It is used to signify the

   132    absence of a value in many situations, e.g., it is returned from functions that

   133    don't explicitly return anything. Its truth value is false.

   134 

   135 NotImplemented

   136    .. index:: object: NotImplemented

   137 

   138    This type has a single value.  There is a single object with this value. This

   139    object is accessed through the built-in name ``NotImplemented``. Numeric methods

   140    and rich comparison methods may return this value if they do not implement the

   141    operation for the operands provided.  (The interpreter will then try the

   142    reflected operation, or some other fallback, depending on the operator.)  Its

   143    truth value is true.

   144 

   145 Ellipsis

   146    .. index:: object: Ellipsis

   147 

   148    This type has a single value.  There is a single object with this value. This

   149    object is accessed through the built-in name ``Ellipsis``. It is used to

   150    indicate the presence of the ``...`` syntax in a slice.  Its truth value is

   151    true.

   152 

   153 :class:`numbers.Number`

   154    .. index:: object: numeric

   155 

   156    These are created by numeric literals and returned as results by arithmetic

   157    operators and arithmetic built-in functions.  Numeric objects are immutable;

   158    once created their value never changes.  Python numbers are of course strongly

   159    related to mathematical numbers, but subject to the limitations of numerical

   160    representation in computers.

   161 

   162    Python distinguishes between integers, floating point numbers, and complex

   163    numbers:

   164 

   165    :class:`numbers.Integral`

   166       .. index:: object: integer

   167 

   168       These represent elements from the mathematical set of integers (positive and

   169       negative).

   170 

   171       There are three types of integers:

   172 

   173       Plain integers

   174          .. index::

   175             object: plain integer

   176             single: OverflowError (built-in exception)

   177 

   178          These represent numbers in the range -2147483648 through 2147483647.

   179          (The range may be larger on machines with a larger natural word size,

   180          but not smaller.)  When the result of an operation would fall outside

   181          this range, the result is normally returned as a long integer (in some

   182          cases, the exception :exc:`OverflowError` is raised instead).  For the

   183          purpose of shift and mask operations, integers are assumed to have a

   184          binary, 2's complement notation using 32 or more bits, and hiding no

   185          bits from the user (i.e., all 4294967296 different bit patterns

   186          correspond to different values).

   187 

   188       Long integers

   189          .. index:: object: long integer

   190 

   191          These represent numbers in an unlimited range, subject to available

   192          (virtual) memory only.  For the purpose of shift and mask operations, a

   193          binary representation is assumed, and negative numbers are represented

   194          in a variant of 2's complement which gives the illusion of an infinite

   195          string of sign bits extending to the left.

   196 

   197       Booleans

   198          .. index::

   199             object: Boolean

   200             single: False

   201             single: True

   202 

   203          These represent the truth values False and True.  The two objects

   204          representing the values False and True are the only Boolean objects.

   205          The Boolean type is a subtype of plain integers, and Boolean values

   206          behave like the values 0 and 1, respectively, in almost all contexts,

   207          the exception being that when converted to a string, the strings

   208          ``"False"`` or ``"True"`` are returned, respectively.

   209 

   210       .. index:: pair: integer; representation

   211 

   212       The rules for integer representation are intended to give the most

   213       meaningful interpretation of shift and mask operations involving negative

   214       integers and the least surprises when switching between the plain and long

   215       integer domains.  Any operation, if it yields a result in the plain

   216       integer domain, will yield the same result in the long integer domain or

   217       when using mixed operands.  The switch between domains is transparent to

   218       the programmer.

   219 

   220    :class:`numbers.Real` (:class:`float`)

   221       .. index::

   222          object: floating point

   223          pair: floating point; number

   224          pair: C; language

   225          pair: Java; language

   226 

   227       These represent machine-level double precision floating point numbers. You are

   228       at the mercy of the underlying machine architecture (and C or Java

   229       implementation) for the accepted range and handling of overflow. Python does not

   230       support single-precision floating point numbers; the savings in processor and

   231       memory usage that are usually the reason for using these is dwarfed by the

   232       overhead of using objects in Python, so there is no reason to complicate the

   233       language with two kinds of floating point numbers.

   234 

   235    :class:`numbers.Complex`

   236       .. index::

   237          object: complex

   238          pair: complex; number

   239 

   240       These represent complex numbers as a pair of machine-level double precision

   241       floating point numbers.  The same caveats apply as for floating point numbers.

   242       The real and imaginary parts of a complex number ``z`` can be retrieved through

   243       the read-only attributes ``z.real`` and ``z.imag``.

   244 

   245 Sequences

   246    .. index::

   247       builtin: len

   248       object: sequence

   249       single: index operation

   250       single: item selection

   251       single: subscription

   252 

   253    These represent finite ordered sets indexed by non-negative numbers. The

   254    built-in function :func:`len` returns the number of items of a sequence. When

   255    the length of a sequence is *n*, the index set contains the numbers 0, 1,

   256    ..., *n*-1.  Item *i* of sequence *a* is selected by ``a[i]``.

   257 

   258    .. index:: single: slicing

   259 

   260    Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such

   261    that *i* ``<=`` *k* ``<`` *j*.  When used as an expression, a slice is a

   262    sequence of the same type.  This implies that the index set is renumbered so

   263    that it starts at 0.

   264 

   265    .. index:: single: extended slicing

   266 

   267    Some sequences also support "extended slicing" with a third "step" parameter:

   268    ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*

   269    ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.

   270 

   271    Sequences are distinguished according to their mutability:

   272 

   273    Immutable sequences

   274       .. index::

   275          object: immutable sequence

   276          object: immutable

   277 

   278       An object of an immutable sequence type cannot change once it is created.  (If

   279       the object contains references to other objects, these other objects may be

   280       mutable and may be changed; however, the collection of objects directly

   281       referenced by an immutable object cannot change.)

   282 

   283       The following types are immutable sequences:

   284 

   285       Strings

   286          .. index::

   287             builtin: chr

   288             builtin: ord

   289             object: string

   290             single: character

   291             single: byte

   292             single: ASCII@ASCII

   293 

   294          The items of a string are characters.  There is no separate character type; a

   295          character is represented by a string of one item. Characters represent (at

   296          least) 8-bit bytes.  The built-in functions :func:`chr` and :func:`ord` convert

   297          between characters and nonnegative integers representing the byte values.  Bytes

   298          with the values 0-127 usually represent the corresponding ASCII values, but the

   299          interpretation of values is up to the program.  The string data type is also

   300          used to represent arrays of bytes, e.g., to hold data read from a file.

   301 

   302          .. index::

   303             single: ASCII@ASCII

   304             single: EBCDIC

   305             single: character set

   306             pair: string; comparison

   307             builtin: chr

   308             builtin: ord

   309 

   310          (On systems whose native character set is not ASCII, strings may use EBCDIC in

   311          their internal representation, provided the functions :func:`chr` and

   312          :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison

   313          preserves the ASCII order. Or perhaps someone can propose a better rule?)

   314 

   315       Unicode

   316          .. index::

   317             builtin: unichr

   318             builtin: ord

   319             builtin: unicode

   320             object: unicode

   321             single: character

   322             single: integer

   323             single: Unicode

   324 

   325          The items of a Unicode object are Unicode code units.  A Unicode code unit is

   326          represented by a Unicode object of one item and can hold either a 16-bit or

   327          32-bit value representing a Unicode ordinal (the maximum value for the ordinal

   328          is given in ``sys.maxunicode``, and depends on how Python is configured at

   329          compile time).  Surrogate pairs may be present in the Unicode object, and will

   330          be reported as two separate items.  The built-in functions :func:`unichr` and

   331          :func:`ord` convert between code units and nonnegative integers representing the

   332          Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to

   333          other encodings are possible through the Unicode method :meth:`encode` and the

   334          built-in function :func:`unicode`.

   335 

   336       Tuples

   337          .. index::

   338             object: tuple

   339             pair: singleton; tuple

   340             pair: empty; tuple

   341 

   342          The items of a tuple are arbitrary Python objects. Tuples of two or more items

   343          are formed by comma-separated lists of expressions.  A tuple of one item (a

   344          'singleton') can be formed by affixing a comma to an expression (an expression

   345          by itself does not create a tuple, since parentheses must be usable for grouping

   346          of expressions).  An empty tuple can be formed by an empty pair of parentheses.

   347 

   348    Mutable sequences

   349       .. index::

   350          object: mutable sequence

   351          object: mutable

   352          pair: assignment; statement

   353          single: delete

   354          statement: del

   355          single: subscription

   356          single: slicing

   357 

   358       Mutable sequences can be changed after they are created.  The subscription and

   359       slicing notations can be used as the target of assignment and :keyword:`del`

   360       (delete) statements.

   361 

   362       There is currently a single intrinsic mutable sequence type:

   363 

   364       Lists

   365          .. index:: object: list

   366 

   367          The items of a list are arbitrary Python objects.  Lists are formed by placing a

   368          comma-separated list of expressions in square brackets. (Note that there are no

   369          special cases needed to form lists of length 0 or 1.)

   370 

   371       .. index:: module: array

   372 

   373       The extension module :mod:`array` provides an additional example of a mutable

   374       sequence type.

   375 

   376 Set types

   377    .. index::

   378       builtin: len

   379       object: set type

   380 

   381    These represent unordered, finite sets of unique, immutable objects. As such,

   382    they cannot be indexed by any subscript. However, they can be iterated over, and

   383    the built-in function :func:`len` returns the number of items in a set. Common

   384    uses for sets are fast membership testing, removing duplicates from a sequence,

   385    and computing mathematical operations such as intersection, union, difference,

   386    and symmetric difference.

   387 

   388    For set elements, the same immutability rules apply as for dictionary keys. Note

   389    that numeric types obey the normal rules for numeric comparison: if two numbers

   390    compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a

   391    set.

   392 

   393    There are currently two intrinsic set types:

   394 

   395    Sets

   396       .. index:: object: set

   397 

   398       These represent a mutable set. They are created by the built-in :func:`set`

   399       constructor and can be modified afterwards by several methods, such as

   400       :meth:`add`.

   401 

   402    Frozen sets

   403       .. index:: object: frozenset

   404 

   405       These represent an immutable set.  They are created by the built-in

   406       :func:`frozenset` constructor.  As a frozenset is immutable and

   407       :term:`hashable`, it can be used again as an element of another set, or as

   408       a dictionary key.

   409 

   410 Mappings

   411    .. index::

   412       builtin: len

   413       single: subscription

   414       object: mapping

   415 

   416    These represent finite sets of objects indexed by arbitrary index sets. The

   417    subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping

   418    ``a``; this can be used in expressions and as the target of assignments or

   419    :keyword:`del` statements. The built-in function :func:`len` returns the number

   420    of items in a mapping.

   421 

   422    There is currently a single intrinsic mapping type:

   423 

   424    Dictionaries

   425       .. index:: object: dictionary

   426 

   427       These represent finite sets of objects indexed by nearly arbitrary values.  The

   428       only types of values not acceptable as keys are values containing lists or

   429       dictionaries or other mutable types that are compared by value rather than by

   430       object identity, the reason being that the efficient implementation of

   431       dictionaries requires a key's hash value to remain constant. Numeric types used

   432       for keys obey the normal rules for numeric comparison: if two numbers compare

   433       equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index

   434       the same dictionary entry.

   435 

   436       Dictionaries are mutable; they can be created by the ``{...}`` notation (see

   437       section :ref:`dict`).

   438 

   439       .. index::

   440          module: dbm

   441          module: gdbm

   442          module: bsddb

   443 

   444       The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide

   445       additional examples of mapping types.

   446 

   447 Callable types

   448    .. index::

   449       object: callable

   450       pair: function; call

   451       single: invocation

   452       pair: function; argument

   453 

   454    These are the types to which the function call operation (see section

   455    :ref:`calls`) can be applied:

   456 

   457    User-defined functions

   458       .. index::

   459          pair: user-defined; function

   460          object: function

   461          object: user-defined function

   462 

   463       A user-defined function object is created by a function definition (see

   464       section :ref:`function`).  It should be called with an argument list

   465       containing the same number of items as the function's formal parameter

   466       list.

   467 

   468       Special attributes:

   469 

   470       +-----------------------+-------------------------------+-----------+

   471       | Attribute             | Meaning                       |           |

   472       +=======================+===============================+===========+

   473       | :attr:`func_doc`      | The function's documentation  | Writable  |

   474       |                       | string, or ``None`` if        |           |

   475       |                       | unavailable                   |           |

   476       +-----------------------+-------------------------------+-----------+

   477       | :attr:`__doc__`       | Another way of spelling       | Writable  |

   478       |                       | :attr:`func_doc`              |           |

   479       +-----------------------+-------------------------------+-----------+

   480       | :attr:`func_name`     | The function's name           | Writable  |

   481       +-----------------------+-------------------------------+-----------+

   482       | :attr:`__name__`      | Another way of spelling       | Writable  |

   483       |                       | :attr:`func_name`             |           |

   484       +-----------------------+-------------------------------+-----------+

   485       | :attr:`__module__`    | The name of the module the    | Writable  |

   486       |                       | function was defined in, or   |           |

   487       |                       | ``None`` if unavailable.      |           |

   488       +-----------------------+-------------------------------+-----------+

   489       | :attr:`func_defaults` | A tuple containing default    | Writable  |

   490       |                       | argument values for those     |           |

   491       |                       | arguments that have defaults, |           |

   492       |                       | or ``None`` if no arguments   |           |

   493       |                       | have a default value          |           |

   494       +-----------------------+-------------------------------+-----------+

   495       | :attr:`func_code`     | The code object representing  | Writable  |

   496       |                       | the compiled function body.   |           |

   497       +-----------------------+-------------------------------+-----------+

   498       | :attr:`func_globals`  | A reference to the dictionary | Read-only |

   499       |                       | that holds the function's     |           |

   500       |                       | global variables --- the      |           |

   501       |                       | global namespace of the       |           |

   502       |                       | module in which the function  |           |

   503       |                       | was defined.                  |           |

   504       +-----------------------+-------------------------------+-----------+

   505       | :attr:`func_dict`     | The namespace supporting      | Writable  |

   506       |                       | arbitrary function            |           |

   507       |                       | attributes.                   |           |

   508       +-----------------------+-------------------------------+-----------+

   509       | :attr:`func_closure`  | ``None`` or a tuple of cells  | Read-only |

   510       |                       | that contain bindings for the |           |

   511       |                       | function's free variables.    |           |

   512       +-----------------------+-------------------------------+-----------+

   513 

   514       Most of the attributes labelled "Writable" check the type of the assigned value.

   515 

   516       .. versionchanged:: 2.4

   517          ``func_name`` is now writable.

   518 

   519       Function objects also support getting and setting arbitrary attributes, which

   520       can be used, for example, to attach metadata to functions.  Regular attribute

   521       dot-notation is used to get and set such attributes. *Note that the current

   522       implementation only supports function attributes on user-defined functions.

   523       Function attributes on built-in functions may be supported in the future.*

   524 

   525       Additional information about a function's definition can be retrieved from its

   526       code object; see the description of internal types below.

   527 

   528       .. index::

   529          single: func_doc (function attribute)

   530          single: __doc__ (function attribute)

   531          single: __name__ (function attribute)

   532          single: __module__ (function attribute)

   533          single: __dict__ (function attribute)

   534          single: func_defaults (function attribute)

   535          single: func_closure (function attribute)

   536          single: func_code (function attribute)

   537          single: func_globals (function attribute)

   538          single: func_dict (function attribute)

   539          pair: global; namespace

   540 

   541    User-defined methods

   542       .. index::

   543          object: method

   544          object: user-defined method

   545          pair: user-defined; method

   546 

   547       A user-defined method object combines a class, a class instance (or ``None``)

   548       and any callable object (normally a user-defined function).

   549 

   550       Special read-only attributes: :attr:`im_self` is the class instance object,

   551       :attr:`im_func` is the function object; :attr:`im_class` is the class of

   552       :attr:`im_self` for bound methods or the class that asked for the method for

   553       unbound methods; :attr:`__doc__` is the method's documentation (same as

   554       ``im_func.__doc__``); :attr:`__name__` is the method name (same as

   555       ``im_func.__name__``); :attr:`__module__` is the name of the module the method

   556       was defined in, or ``None`` if unavailable.

   557 

   558       .. versionchanged:: 2.2

   559          :attr:`im_self` used to refer to the class that defined the method.

   560 

   561       .. versionchanged:: 2.6

   562          For 3.0 forward-compatibility, :attr:`im_func` is also available as

   563          :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.

   564 

   565       .. index::

   566          single: __doc__ (method attribute)

   567          single: __name__ (method attribute)

   568          single: __module__ (method attribute)

   569          single: im_func (method attribute)

   570          single: im_self (method attribute)

   571 

   572       Methods also support accessing (but not setting) the arbitrary function

   573       attributes on the underlying function object.

   574 

   575       User-defined method objects may be created when getting an attribute of a class

   576       (perhaps via an instance of that class), if that attribute is a user-defined

   577       function object, an unbound user-defined method object, or a class method

   578       object. When the attribute is a user-defined method object, a new method object

   579       is only created if the class from which it is being retrieved is the same as, or

   580       a derived class of, the class stored in the original method object; otherwise,

   581       the original method object is used as it is.

   582 

   583       .. index::

   584          single: im_class (method attribute)

   585          single: im_func (method attribute)

   586          single: im_self (method attribute)

   587 

   588       When a user-defined method object is created by retrieving a user-defined

   589       function object from a class, its :attr:`im_self` attribute is ``None``

   590       and the method object is said to be unbound. When one is created by

   591       retrieving a user-defined function object from a class via one of its

   592       instances, its :attr:`im_self` attribute is the instance, and the method

   593       object is said to be bound. In either case, the new method's

   594       :attr:`im_class` attribute is the class from which the retrieval takes

   595       place, and its :attr:`im_func` attribute is the original function object.

   596 

   597       .. index:: single: im_func (method attribute)

   598 

   599       When a user-defined method object is created by retrieving another method object

   600       from a class or instance, the behaviour is the same as for a function object,

   601       except that the :attr:`im_func` attribute of the new instance is not the

   602       original method object but its :attr:`im_func` attribute.

   603 

   604       .. index::

   605          single: im_class (method attribute)

   606          single: im_func (method attribute)

   607          single: im_self (method attribute)

   608 

   609       When a user-defined method object is created by retrieving a class method object

   610       from a class or instance, its :attr:`im_self` attribute is the class itself (the

   611       same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is

   612       the function object underlying the class method.

   613 

   614       When an unbound user-defined method object is called, the underlying function

   615       (:attr:`im_func`) is called, with the restriction that the first argument must

   616       be an instance of the proper class (:attr:`im_class`) or of a derived class

   617       thereof.

   618 

   619       When a bound user-defined method object is called, the underlying function

   620       (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in

   621       front of the argument list.  For instance, when :class:`C` is a class which

   622       contains a definition for a function :meth:`f`, and ``x`` is an instance of

   623       :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``.

   624 

   625       When a user-defined method object is derived from a class method object, the

   626       "class instance" stored in :attr:`im_self` will actually be the class itself, so

   627       that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)``

   628       where ``f`` is the underlying function.

   629 

   630       Note that the transformation from function object to (unbound or bound) method

   631       object happens each time the attribute is retrieved from the class or instance.

   632       In some cases, a fruitful optimization is to assign the attribute to a local

   633       variable and call that local variable. Also notice that this transformation only

   634       happens for user-defined functions; other callable objects (and all non-callable

   635       objects) are retrieved without transformation.  It is also important to note

   636       that user-defined functions which are attributes of a class instance are not

   637       converted to bound methods; this *only* happens when the function is an

   638       attribute of the class.

   639 

   640    Generator functions

   641       .. index::

   642          single: generator; function

   643          single: generator; iterator

   644 

   645       A function or method which uses the :keyword:`yield` statement (see section

   646       :ref:`yield`) is called a :dfn:`generator

   647       function`.  Such a function, when called, always returns an iterator object

   648       which can be used to execute the body of the function:  calling the iterator's

   649       :meth:`next` method will cause the function to execute until it provides a value

   650       using the :keyword:`yield` statement.  When the function executes a

   651       :keyword:`return` statement or falls off the end, a :exc:`StopIteration`

   652       exception is raised and the iterator will have reached the end of the set of

   653       values to be returned.

   654 

   655    Built-in functions

   656       .. index::

   657          object: built-in function

   658          object: function

   659          pair: C; language

   660 

   661       A built-in function object is a wrapper around a C function.  Examples of

   662       built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a

   663       standard built-in module). The number and type of the arguments are

   664       determined by the C function. Special read-only attributes:

   665       :attr:`__doc__` is the function's documentation string, or ``None`` if

   666       unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is

   667       set to ``None`` (but see the next item); :attr:`__module__` is the name of

   668       the module the function was defined in or ``None`` if unavailable.

   669 

   670    Built-in methods

   671       .. index::

   672          object: built-in method

   673          object: method

   674          pair: built-in; method

   675 

   676       This is really a different disguise of a built-in function, this time containing

   677       an object passed to the C function as an implicit extra argument.  An example of

   678       a built-in method is ``alist.append()``, assuming *alist* is a list object. In

   679       this case, the special read-only attribute :attr:`__self__` is set to the object

   680       denoted by *list*.

   681 

   682    Class Types

   683       Class types, or "new-style classes," are callable.  These objects normally act

   684       as factories for new instances of themselves, but variations are possible for

   685       class types that override :meth:`__new__`.  The arguments of the call are passed

   686       to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize

   687       the new instance.

   688 

   689    Classic Classes

   690       .. index::

   691          single: __init__() (object method)

   692          object: class

   693          object: class instance

   694          object: instance

   695          pair: class object; call

   696 

   697       Class objects are described below.  When a class object is called, a new class

   698       instance (also described below) is created and returned.  This implies a call to

   699       the class's :meth:`__init__` method if it has one.  Any arguments are passed on

   700       to the :meth:`__init__` method.  If there is no :meth:`__init__` method, the

   701       class must be called without arguments.

   702 

   703    Class instances

   704       Class instances are described below.  Class instances are callable only when the

   705       class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for

   706       ``x.__call__(arguments)``.

   707 

   708 Modules

   709    .. index::

   710       statement: import

   711       object: module

   712 

   713    Modules are imported by the :keyword:`import` statement (see section

   714    :ref:`import`). A module object has a

   715    namespace implemented by a dictionary object (this is the dictionary referenced

   716    by the func_globals attribute of functions defined in the module).  Attribute

   717    references are translated to lookups in this dictionary, e.g., ``m.x`` is

   718    equivalent to ``m.__dict__["x"]``. A module object does not contain the code

   719    object used to initialize the module (since it isn't needed once the

   720    initialization is done).

   721 

   722    Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =

   723    1`` is equivalent to ``m.__dict__["x"] = 1``.

   724 

   725    .. index:: single: __dict__ (module attribute)

   726 

   727    Special read-only attribute: :attr:`__dict__` is the module's namespace as a

   728    dictionary object.

   729 

   730    .. index::

   731       single: __name__ (module attribute)

   732       single: __doc__ (module attribute)

   733       single: __file__ (module attribute)

   734       pair: module; namespace

   735 

   736    Predefined (writable) attributes: :attr:`__name__` is the module's name;

   737    :attr:`__doc__` is the module's documentation string, or ``None`` if

   738    unavailable; :attr:`__file__` is the pathname of the file from which the module

   739    was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not

   740    present for C modules that are statically linked into the interpreter; for

   741    extension modules loaded dynamically from a shared library, it is the pathname

   742    of the shared library file.

   743 

   744 Classes

   745    Both class types (new-style classes) and class objects (old-style/classic

   746    classes) are typically created by class definitions (see section

   747    :ref:`class`).  A class has a namespace implemented by a dictionary object.

   748    Class attribute references are translated to lookups in this dictionary, e.g.,

   749    ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes

   750    in particular there are a number of hooks which allow for other means of

   751    locating attributes). When the attribute name is not found there, the

   752    attribute search continues in the base classes.  For old-style classes, the

   753    search is depth-first, left-to-right in the order of occurrence in the base

   754    class list. New-style classes use the more complex C3 method resolution

   755    order which behaves correctly even in the presence of 'diamond'

   756    inheritance structures where there are multiple inheritance paths

   757    leading back to a common ancestor. Additional details on the C3 MRO used by

   758    new-style classes can be found in the documentation accompanying the

   759    2.3 release at http://www.python.org/download/releases/2.3/mro/.

   760 

   761    .. XXX: Could we add that MRO doc as an appendix to the language ref?

   762 

   763    .. index::

   764       object: class

   765       object: class instance

   766       object: instance

   767       pair: class object; call

   768       single: container

   769       object: dictionary

   770       pair: class; attribute

   771 

   772    When a class attribute reference (for class :class:`C`, say) would yield a

   773    user-defined function object or an unbound user-defined method object whose

   774    associated class is either :class:`C` or one of its base classes, it is

   775    transformed into an unbound user-defined method object whose :attr:`im_class`

   776    attribute is :class:`C`. When it would yield a class method object, it is

   777    transformed into a bound user-defined method object whose :attr:`im_class`

   778    and :attr:`im_self` attributes are both :class:`C`.  When it would yield a

   779    static method object, it is transformed into the object wrapped by the static

   780    method object. See section :ref:`descriptors` for another way in which

   781    attributes retrieved from a class may differ from those actually contained in

   782    its :attr:`__dict__` (note that only new-style classes support descriptors).

   783 

   784    .. index:: triple: class; attribute; assignment

   785 

   786    Class attribute assignments update the class's dictionary, never the dictionary

   787    of a base class.

   788 

   789    .. index:: pair: class object; call

   790 

   791    A class object can be called (see above) to yield a class instance (see below).

   792 

   793    .. index::

   794       single: __name__ (class attribute)

   795       single: __module__ (class attribute)

   796       single: __dict__ (class attribute)

   797       single: __bases__ (class attribute)

   798       single: __doc__ (class attribute)

   799 

   800    Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is

   801    the module name in which the class was defined; :attr:`__dict__` is the

   802    dictionary containing the class's namespace; :attr:`__bases__` is a tuple

   803    (possibly empty or a singleton) containing the base classes, in the order of

   804    their occurrence in the base class list; :attr:`__doc__` is the class's

   805    documentation string, or None if undefined.

   806 

   807 Class instances

   808    .. index::

   809       object: class instance

   810       object: instance

   811       pair: class; instance

   812       pair: class instance; attribute

   813 

   814    A class instance is created by calling a class object (see above). A class

   815    instance has a namespace implemented as a dictionary which is the first place in

   816    which attribute references are searched.  When an attribute is not found there,

   817    and the instance's class has an attribute by that name, the search continues

   818    with the class attributes.  If a class attribute is found that is a user-defined

   819    function object or an unbound user-defined method object whose associated class

   820    is the class (call it :class:`C`) of the instance for which the attribute

   821    reference was initiated or one of its bases, it is transformed into a bound

   822    user-defined method object whose :attr:`im_class` attribute is :class:`C` and

   823    whose :attr:`im_self` attribute is the instance. Static method and class method

   824    objects are also transformed, as if they had been retrieved from class

   825    :class:`C`; see above under "Classes". See section :ref:`descriptors` for

   826    another way in which attributes of a class retrieved via its instances may

   827    differ from the objects actually stored in the class's :attr:`__dict__`. If no

   828    class attribute is found, and the object's class has a :meth:`__getattr__`

   829    method, that is called to satisfy the lookup.

   830 

   831    .. index:: triple: class instance; attribute; assignment

   832 

   833    Attribute assignments and deletions update the instance's dictionary, never a

   834    class's dictionary.  If the class has a :meth:`__setattr__` or

   835    :meth:`__delattr__` method, this is called instead of updating the instance

   836    dictionary directly.

   837 

   838    .. index::

   839       object: numeric

   840       object: sequence

   841       object: mapping

   842 

   843    Class instances can pretend to be numbers, sequences, or mappings if they have

   844    methods with certain special names.  See section :ref:`specialnames`.

   845 

   846    .. index::

   847       single: __dict__ (instance attribute)

   848       single: __class__ (instance attribute)

   849 

   850    Special attributes: :attr:`__dict__` is the attribute dictionary;

   851    :attr:`__class__` is the instance's class.

   852 

   853 Files

   854    .. index::

   855       object: file

   856       builtin: open

   857       single: popen() (in module os)

   858       single: makefile() (socket method)

   859       single: sys.stdin

   860       single: sys.stdout

   861       single: sys.stderr

   862       single: stdio

   863       single: stdin (in module sys)

   864       single: stdout (in module sys)

   865       single: stderr (in module sys)

   866 

   867    A file object represents an open file.  File objects are created by the

   868    :func:`open` built-in function, and also by :func:`os.popen`,

   869    :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and

   870    perhaps by other functions or methods provided by extension modules).  The

   871    objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to

   872    file objects corresponding to the interpreter's standard input, output and

   873    error streams.  See :ref:`bltin-file-objects` for complete documentation of

   874    file objects.

   875 

   876 Internal types

   877    .. index::

   878       single: internal type

   879       single: types, internal

   880 

   881    A few types used internally by the interpreter are exposed to the user. Their

   882    definitions may change with future versions of the interpreter, but they are

   883    mentioned here for completeness.

   884 

   885    Code objects

   886       .. index::

   887          single: bytecode

   888          object: code

   889 

   890       Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.

   891       The difference between a code object and a function object is that the function

   892       object contains an explicit reference to the function's globals (the module in

   893       which it was defined), while a code object contains no context; also the default

   894       argument values are stored in the function object, not in the code object

   895       (because they represent values calculated at run-time).  Unlike function

   896       objects, code objects are immutable and contain no references (directly or

   897       indirectly) to mutable objects.

   898 

   899       Special read-only attributes: :attr:`co_name` gives the function name;

   900       :attr:`co_argcount` is the number of positional arguments (including arguments

   901       with default values); :attr:`co_nlocals` is the number of local variables used

   902       by the function (including arguments); :attr:`co_varnames` is a tuple containing

   903       the names of the local variables (starting with the argument names);

   904       :attr:`co_cellvars` is a tuple containing the names of local variables that are

   905       referenced by nested functions; :attr:`co_freevars` is a tuple containing the

   906       names of free variables; :attr:`co_code` is a string representing the sequence

   907       of bytecode instructions; :attr:`co_consts` is a tuple containing the literals

   908       used by the bytecode; :attr:`co_names` is a tuple containing the names used by

   909       the bytecode; :attr:`co_filename` is the filename from which the code was

   910       compiled; :attr:`co_firstlineno` is the first line number of the function;

   911       :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to

   912       line numbers (for details see the source code of the interpreter);

   913       :attr:`co_stacksize` is the required stack size (including local variables);

   914       :attr:`co_flags` is an integer encoding a number of flags for the interpreter.

   915 

   916       .. index::

   917          single: co_argcount (code object attribute)

   918          single: co_code (code object attribute)

   919          single: co_consts (code object attribute)

   920          single: co_filename (code object attribute)

   921          single: co_firstlineno (code object attribute)

   922          single: co_flags (code object attribute)

   923          single: co_lnotab (code object attribute)

   924          single: co_name (code object attribute)

   925          single: co_names (code object attribute)

   926          single: co_nlocals (code object attribute)

   927          single: co_stacksize (code object attribute)

   928          single: co_varnames (code object attribute)

   929          single: co_cellvars (code object attribute)

   930          single: co_freevars (code object attribute)

   931 

   932       .. index:: object: generator

   933 

   934       The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if

   935       the function uses the ``*arguments`` syntax to accept an arbitrary number of

   936       positional arguments; bit ``0x08`` is set if the function uses the

   937       ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set

   938       if the function is a generator.

   939 

   940       Future feature declarations (``from __future__ import division``) also use bits

   941       in :attr:`co_flags` to indicate whether a code object was compiled with a

   942       particular feature enabled: bit ``0x2000`` is set if the function was compiled

   943       with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier

   944       versions of Python.

   945 

   946       Other bits in :attr:`co_flags` are reserved for internal use.

   947 

   948       .. index:: single: documentation string

   949 

   950       If a code object represents a function, the first item in :attr:`co_consts` is

   951       the documentation string of the function, or ``None`` if undefined.

   952 

   953    Frame objects

   954       .. index:: object: frame

   955 

   956       Frame objects represent execution frames.  They may occur in traceback objects

   957       (see below).

   958 

   959       .. index::

   960          single: f_back (frame attribute)

   961          single: f_code (frame attribute)

   962          single: f_globals (frame attribute)

   963          single: f_locals (frame attribute)

   964          single: f_lasti (frame attribute)

   965          single: f_builtins (frame attribute)

   966          single: f_restricted (frame attribute)

   967 

   968       Special read-only attributes: :attr:`f_back` is to the previous stack frame

   969       (towards the caller), or ``None`` if this is the bottom stack frame;

   970       :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`

   971       is the dictionary used to look up local variables; :attr:`f_globals` is used for

   972       global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;

   973       :attr:`f_restricted` is a flag indicating whether the function is executing in

   974       restricted execution mode; :attr:`f_lasti` gives the precise instruction (this

   975       is an index into the bytecode string of the code object).

   976 

   977       .. index::

   978          single: f_trace (frame attribute)

   979          single: f_exc_type (frame attribute)

   980          single: f_exc_value (frame attribute)

   981          single: f_exc_traceback (frame attribute)

   982          single: f_lineno (frame attribute)

   983 

   984       Special writable attributes: :attr:`f_trace`, if not ``None``, is a function

   985       called at the start of each source code line (this is used by the debugger);

   986       :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the

   987       last exception raised in the parent frame provided another exception was ever

   988       raised in the current frame (in all other cases they are None); :attr:`f_lineno`

   989       is the current line number of the frame --- writing to this from within a trace

   990       function jumps to the given line (only for the bottom-most frame).  A debugger

   991       can implement a Jump command (aka Set Next Statement) by writing to f_lineno.

   992 

   993    Traceback objects

   994       .. index::

   995          object: traceback

   996          pair: stack; trace

   997          pair: exception; handler

   998          pair: execution; stack

   999          single: exc_info (in module sys)

  1000          single: exc_traceback (in module sys)

  1001          single: last_traceback (in module sys)

  1002          single: sys.exc_info

  1003          single: sys.exc_traceback

  1004          single: sys.last_traceback

  1005 

  1006       Traceback objects represent a stack trace of an exception.  A traceback object

  1007       is created when an exception occurs.  When the search for an exception handler

  1008       unwinds the execution stack, at each unwound level a traceback object is

  1009       inserted in front of the current traceback.  When an exception handler is

  1010       entered, the stack trace is made available to the program. (See section

  1011       :ref:`try`.) It is accessible as ``sys.exc_traceback``,

  1012       and also as the third item of the tuple returned by ``sys.exc_info()``.  The

  1013       latter is the preferred interface, since it works correctly when the program is

  1014       using multiple threads. When the program contains no suitable handler, the stack

  1015       trace is written (nicely formatted) to the standard error stream; if the

  1016       interpreter is interactive, it is also made available to the user as

  1017       ``sys.last_traceback``.

  1018 

  1019       .. index::

  1020          single: tb_next (traceback attribute)

  1021          single: tb_frame (traceback attribute)

  1022          single: tb_lineno (traceback attribute)

  1023          single: tb_lasti (traceback attribute)

  1024          statement: try

  1025 

  1026       Special read-only attributes: :attr:`tb_next` is the next level in the stack

  1027       trace (towards the frame where the exception occurred), or ``None`` if there is

  1028       no next level; :attr:`tb_frame` points to the execution frame of the current

  1029       level; :attr:`tb_lineno` gives the line number where the exception occurred;

  1030       :attr:`tb_lasti` indicates the precise instruction.  The line number and last

  1031       instruction in the traceback may differ from the line number of its frame object

  1032       if the exception occurred in a :keyword:`try` statement with no matching except

  1033       clause or with a finally clause.

  1034 

  1035    Slice objects

  1036       .. index:: builtin: slice

  1037 

  1038       Slice objects are used to represent slices when *extended slice syntax* is used.

  1039       This is a slice using two colons, or multiple slices or ellipses separated by

  1040       commas, e.g., ``a[i:j:step]``, ``a[i:j, k:l]``, or ``a[..., i:j]``.  They are

  1041       also created by the built-in :func:`slice` function.

  1042 

  1043       .. index::

  1044          single: start (slice object attribute)

  1045          single: stop (slice object attribute)

  1046          single: step (slice object attribute)

  1047 

  1048       Special read-only attributes: :attr:`start` is the lower bound; :attr:`stop` is

  1049       the upper bound; :attr:`step` is the step value; each is ``None`` if omitted.

  1050       These attributes can have any type.

  1051 

  1052       Slice objects support one method:

  1053 

  1054 

  1055       .. method:: slice.indices(self, length)

  1056 

  1057          This method takes a single integer argument *length* and computes information

  1058          about the extended slice that the slice object would describe if applied to a

  1059          sequence of *length* items.  It returns a tuple of three integers; respectively

  1060          these are the *start* and *stop* indices and the *step* or stride length of the

  1061          slice. Missing or out-of-bounds indices are handled in a manner consistent with

  1062          regular slices.

  1063 

  1064          .. versionadded:: 2.3

  1065 

  1066    Static method objects

  1067       Static method objects provide a way of defeating the transformation of function

  1068       objects to method objects described above. A static method object is a wrapper

  1069       around any other object, usually a user-defined method object. When a static

  1070       method object is retrieved from a class or a class instance, the object actually

  1071       returned is the wrapped object, which is not subject to any further

  1072       transformation. Static method objects are not themselves callable, although the

  1073       objects they wrap usually are. Static method objects are created by the built-in

  1074       :func:`staticmethod` constructor.

  1075 

  1076    Class method objects

  1077       A class method object, like a static method object, is a wrapper around another

  1078       object that alters the way in which that object is retrieved from classes and

  1079       class instances. The behaviour of class method objects upon such retrieval is

  1080       described above, under "User-defined methods". Class method objects are created

  1081       by the built-in :func:`classmethod` constructor.

  1082 

  1083 

  1084 .. _newstyle:

  1085 

  1086 New-style and classic classes

  1087 =============================

  1088 

  1089 Classes and instances come in two flavors: old-style (or classic) and new-style.

  1090 

  1091 Up to Python 2.1, old-style classes were the only flavour available to the user.

  1092 The concept of (old-style) class is unrelated to the concept of type: if *x* is

  1093 an instance of an old-style class, then ``x.__class__`` designates the class of

  1094 *x*, but ``type(x)`` is always ``<type 'instance'>``.  This reflects the fact

  1095 that all old-style instances, independently of their class, are implemented with

  1096 a single built-in type, called ``instance``.

  1097 

  1098 New-style classes were introduced in Python 2.2 to unify classes and types.  A

  1099 new-style class is neither more nor less than a user-defined type.  If *x* is an

  1100 instance of a new-style class, then ``type(x)`` is typically the same as

  1101 ``x.__class__`` (although this is not guaranteed - a new-style class instance is

  1102 permitted to override the value returned for ``x.__class__``).

  1103 

  1104 The major motivation for introducing new-style classes is to provide a unified

  1105 object model with a full meta-model.  It also has a number of practical

  1106 benefits, like the ability to subclass most built-in types, or the introduction

  1107 of "descriptors", which enable computed properties.

  1108 

  1109 For compatibility reasons, classes are still old-style by default.  New-style

  1110 classes are created by specifying another new-style class (i.e. a type) as a

  1111 parent class, or the "top-level type" :class:`object` if no other parent is

  1112 needed.  The behaviour of new-style classes differs from that of old-style

  1113 classes in a number of important details in addition to what :func:`type`

  1114 returns.  Some of these changes are fundamental to the new object model, like

  1115 the way special methods are invoked.  Others are "fixes" that could not be

  1116 implemented before for compatibility concerns, like the method resolution order

  1117 in case of multiple inheritance.

  1118 

  1119 While this manual aims to provide comprehensive coverage of Python's class

  1120 mechanics, it may still be lacking in some areas when it comes to its coverage

  1121 of new-style classes. Please see http://www.python.org/doc/newstyle/ for

  1122 sources of additional information.

  1123 

  1124 .. index::

  1125    single: class; new-style

  1126    single: class; classic

  1127    single: class; old-style

  1128 

  1129 Old-style classes are removed in Python 3.0, leaving only the semantics of

  1130 new-style classes.

  1131 

  1132 

  1133 .. _specialnames:

  1134 

  1135 Special method names