.. _datamodel:

**********
Data model
**********


.. _objects:

Objects, values and types
=========================

.. index::
   single: object
   single: data

:dfn:`Objects` are Python's abstraction for data.  All data in a Python program
is represented by objects or by relations between objects. (In a sense, and in
conformance to Von Neumann's model of a "stored program computer," code is also
represented by objects.)

.. index::
   builtin: id
   builtin: type
   single: identity of an object
   single: value of an object
   single: type of an object
   single: mutable object
   single: immutable object

Every object has an identity, a type and a value.  An object's *identity* never
changes once it has been created; you may think of it as the object's address in
memory.  The ':keyword:`is`' operator compares the identity of two objects; the
:func:`id` function returns an integer representing its identity (currently
implemented as its address). An object's :dfn:`type` is also unchangeable. [#]_
An object's type determines the operations that the object supports (e.g., "does
it have a length?") and also defines the possible values for objects of that
type.  The :func:`type` function returns an object's type (which is an object
itself).  The *value* of some objects can change.  Objects whose value can
change are said to be *mutable*; objects whose value is unchangeable once they
are created are called *immutable*. (The value of an immutable container object
that contains a reference to a mutable object can change when the latter's value
is changed; however the container is still considered immutable, because the
collection of objects it contains cannot be changed.  So, immutability is not
strictly the same as having an unchangeable value, it is more subtle.) An
object's mutability is determined by its type; for instance, numbers, strings
and tuples are immutable, while dictionaries and lists are mutable.

.. index::
   single: garbage collection
   single: reference counting
   single: unreachable object

Objects are never explicitly destroyed; however, when they become unreachable
they may be garbage-collected.  An implementation is allowed to postpone garbage
collection or omit it altogether --- it is a matter of implementation quality
how garbage collection is implemented, as long as no objects are collected that
are still reachable.  (Implementation note: CPython currently uses a
reference-counting scheme with (optional) delayed detection of cyclically linked
garbage, which collects most objects as soon as they become unreachable, but is
not guaranteed to collect garbage containing circular references.  See the
documentation of the :mod:`gc` module for information on controlling the
collection of cyclic garbage.  Other implementations act differently and CPython
may change.)

Note that the use of the implementation's tracing or debugging facilities may
keep objects alive that would normally be collectable. Also note that catching
an exception with a ':keyword:`try`...\ :keyword:`except`' statement may keep
objects alive.

Some objects contain references to "external" resources such as open files or
windows.  It is understood that these resources are freed when the object is
garbage-collected, but since garbage collection is not guaranteed to happen,
such objects also provide an explicit way to release the external resource,
usually a :meth:`close` method. Programs are strongly recommended to explicitly
close such objects.  The ':keyword:`try`...\ :keyword:`finally`' statement
provides a convenient way to do this.

.. index:: single: container

Some objects contain references to other objects; these are called *containers*.
Examples of containers are tuples, lists and dictionaries.  The references are
part of a container's value.  In most cases, when we talk about the value of a
container, we imply the values, not the identities of the contained objects;
however, when we talk about the mutability of a container, only the identities
of the immediately contained objects are implied.  So, if an immutable container
(like a tuple) contains a reference to a mutable object, its value changes if
that mutable object is changed.

Types affect almost all aspects of object behavior.  Even the importance of
object identity is affected in some sense: for immutable types, operations that
compute new values may actually return a reference to any existing object with
the same type and value, while for mutable objects this is not allowed.  E.g.,
after ``a = 1; b = 1``, ``a`` and ``b`` may or may not refer to the same object
with the value one, depending on the implementation, but after ``c = []; d =
[]``, ``c`` and ``d`` are guaranteed to refer to two different, unique, newly
created empty lists. (Note that ``c = d = []`` assigns the same object to both
``c`` and ``d``.)


.. _types:

The standard type hierarchy
===========================

.. index::
   single: type
   pair: data; type
   pair: type; hierarchy
   pair: extension; module
   pair: C; language

Below is a list of the types that are built into Python.  Extension modules
(written in C, Java, or other languages, depending on the implementation) can
define additional types.  Future versions of Python may add types to the type
hierarchy (e.g., rational numbers, efficiently stored arrays of integers, etc.).

.. index::
   single: attribute
   pair: special; attribute
   triple: generic; special; attribute

Some of the type descriptions below contain a paragraph listing 'special
attributes.'  These are attributes that provide access to the implementation and
are not intended for general use.  Their definition may change in the future.

None
   .. index:: object: None

   This type has a single value.  There is a single object with this value. This
   object is accessed through the built-in name ``None``. It is used to signify the
   absence of a value in many situations, e.g., it is returned from functions that
   don't explicitly return anything. Its truth value is false.

NotImplemented
   .. index:: object: NotImplemented

   This type has a single value.  There is a single object with this value. This
   object is accessed through the built-in name ``NotImplemented``. Numeric methods
   and rich comparison methods may return this value if they do not implement the
   operation for the operands provided.  (The interpreter will then try the
   reflected operation, or some other fallback, depending on the operator.)  Its
   truth value is true.

Ellipsis
   .. index:: object: Ellipsis

   This type has a single value.  There is a single object with this value. This
   object is accessed through the built-in name ``Ellipsis``. It is used to
   indicate the presence of the ``...`` syntax in a slice.  Its truth value is
   true.

:class:`numbers.Number`
   .. index:: object: numeric

   These are created by numeric literals and returned as results by arithmetic
   operators and arithmetic built-in functions.  Numeric objects are immutable;
   once created their value never changes.  Python numbers are of course strongly
   related to mathematical numbers, but subject to the limitations of numerical
   representation in computers.

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

   :class:`numbers.Integral`
      .. index:: object: integer

      These represent elements from the mathematical set of integers (positive and
      negative).

      There are three types of integers:

      Plain integers
         .. index::
            object: plain integer
            single: OverflowError (built-in exception)

         These represent numbers in the range -2147483648 through 2147483647.
         (The range may be larger on machines with a larger natural word size,
         but not smaller.)  When the result of an operation would fall outside
         this range, the result is normally returned as a long integer (in some
         cases, the exception :exc:`OverflowError` is raised instead).  For the
         purpose of shift and mask operations, integers are assumed to have a
         binary, 2's complement notation using 32 or more bits, and hiding no
         bits from the user (i.e., all 4294967296 different bit patterns
         correspond to different values).

      Long integers
         .. index:: object: long integer

         These represent numbers in an unlimited range, subject to available
         (virtual) memory only.  For the purpose of shift and mask operations, a
         binary representation is assumed, and negative numbers are represented
         in a variant of 2's complement which gives the illusion of an infinite
         string of sign bits extending to the left.

      Booleans
         .. index::
            object: Boolean
            single: False
            single: True

         These represent the truth values False and True.  The two objects
         representing the values False and True are the only Boolean objects.
         The Boolean type is a subtype of plain integers, and Boolean values
         behave like the values 0 and 1, respectively, in almost all contexts,
         the exception being that when converted to a string, the strings
         ``"False"`` or ``"True"`` are returned, respectively.

      .. index:: pair: integer; representation

      The rules for integer representation are intended to give the most
      meaningful interpretation of shift and mask operations involving negative
      integers and the least surprises when switching between the plain and long
      integer domains.  Any operation, if it yields a result in the plain
      integer domain, will yield the same result in the long integer domain or
      when using mixed operands.  The switch between domains is transparent to
      the programmer.

   :class:`numbers.Real` (:class:`float`)
      .. index::
         object: floating point
         pair: floating point; number
         pair: C; language
         pair: Java; language

      These represent machine-level double precision floating point numbers. You are
      at the mercy of the underlying machine architecture (and C or Java
      implementation) for the accepted range and handling of overflow. Python does not
      support single-precision floating point numbers; the savings in processor and
      memory usage that are usually the reason for using these is dwarfed by the
      overhead of using objects in Python, so there is no reason to complicate the
      language with two kinds of floating point numbers.

   :class:`numbers.Complex`
      .. index::
         object: complex
         pair: complex; number

      These represent complex numbers as a pair of machine-level double precision
      floating point numbers.  The same caveats apply as for floating point numbers.
      The real and imaginary parts of a complex number ``z`` can be retrieved through
      the read-only attributes ``z.real`` and ``z.imag``.

Sequences
   .. index::
      builtin: len
      object: sequence
      single: index operation
      single: item selection
      single: subscription

   These represent finite ordered sets indexed by non-negative numbers. The
   built-in function :func:`len` returns the number of items of a sequence. When
   the length of a sequence is *n*, the index set contains the numbers 0, 1,
   ..., *n*-1.  Item *i* of sequence *a* is selected by ``a[i]``.

   .. index:: single: slicing

   Sequences also support slicing: ``a[i:j]`` selects all items with index *k* such
   that *i* ``<=`` *k* ``<`` *j*.  When used as an expression, a slice is a
   sequence of the same type.  This implies that the index set is renumbered so
   that it starts at 0.

   .. index:: single: extended slicing

   Some sequences also support "extended slicing" with a third "step" parameter:
   ``a[i:j:k]`` selects all items of *a* with index *x* where ``x = i + n*k``, *n*
   ``>=`` ``0`` and *i* ``<=`` *x* ``<`` *j*.

   Sequences are distinguished according to their mutability:

   Immutable sequences
      .. index::
         object: immutable sequence
         object: immutable

      An object of an immutable sequence type cannot change once it is created.  (If
      the object contains references to other objects, these other objects may be
      mutable and may be changed; however, the collection of objects directly
      referenced by an immutable object cannot change.)

      The following types are immutable sequences:

      Strings
         .. index::
            builtin: chr
            builtin: ord
            object: string
            single: character
            single: byte
            single: ASCII@ASCII

         The items of a string are characters.  There is no separate character type; a
         character is represented by a string of one item. Characters represent (at
         least) 8-bit bytes.  The built-in functions :func:`chr` and :func:`ord` convert
         between characters and nonnegative integers representing the byte values.  Bytes
         with the values 0-127 usually represent the corresponding ASCII values, but the
         interpretation of values is up to the program.  The string data type is also
         used to represent arrays of bytes, e.g., to hold data read from a file.

         .. index::
            single: ASCII@ASCII
            single: EBCDIC
            single: character set
            pair: string; comparison
            builtin: chr
            builtin: ord

         (On systems whose native character set is not ASCII, strings may use EBCDIC in
         their internal representation, provided the functions :func:`chr` and
         :func:`ord` implement a mapping between ASCII and EBCDIC, and string comparison
         preserves the ASCII order. Or perhaps someone can propose a better rule?)

      Unicode
         .. index::
            builtin: unichr
            builtin: ord
            builtin: unicode
            object: unicode
            single: character
            single: integer
            single: Unicode

         The items of a Unicode object are Unicode code units.  A Unicode code unit is
         represented by a Unicode object of one item and can hold either a 16-bit or
         32-bit value representing a Unicode ordinal (the maximum value for the ordinal
         is given in ``sys.maxunicode``, and depends on how Python is configured at
         compile time).  Surrogate pairs may be present in the Unicode object, and will
         be reported as two separate items.  The built-in functions :func:`unichr` and
         :func:`ord` convert between code units and nonnegative integers representing the
         Unicode ordinals as defined in the Unicode Standard 3.0. Conversion from and to
         other encodings are possible through the Unicode method :meth:`encode` and the
         built-in function :func:`unicode`.

      Tuples
         .. index::
            object: tuple
            pair: singleton; tuple
            pair: empty; tuple

         The items of a tuple are arbitrary Python objects. Tuples of two or more items
         are formed by comma-separated lists of expressions.  A tuple of one item (a
         'singleton') can be formed by affixing a comma to an expression (an expression
         by itself does not create a tuple, since parentheses must be usable for grouping
         of expressions).  An empty tuple can be formed by an empty pair of parentheses.

   Mutable sequences
      .. index::
         object: mutable sequence
         object: mutable
         pair: assignment; statement
         single: delete
         statement: del
         single: subscription
         single: slicing

      Mutable sequences can be changed after they are created.  The subscription and
      slicing notations can be used as the target of assignment and :keyword:`del`
      (delete) statements.

      There is currently a single intrinsic mutable sequence type:

      Lists
         .. index:: object: list

         The items of a list are arbitrary Python objects.  Lists are formed by placing a
         comma-separated list of expressions in square brackets. (Note that there are no
         special cases needed to form lists of length 0 or 1.)

      .. index:: module: array

      The extension module :mod:`array` provides an additional example of a mutable
      sequence type.

Set types
   .. index::
      builtin: len
      object: set type

   These represent unordered, finite sets of unique, immutable objects. As such,
   they cannot be indexed by any subscript. However, they can be iterated over, and
   the built-in function :func:`len` returns the number of items in a set. Common
   uses for sets are fast membership testing, removing duplicates from a sequence,
   and computing mathematical operations such as intersection, union, difference,
   and symmetric difference.

   For set elements, the same immutability rules apply as for dictionary keys. Note
   that numeric types obey the normal rules for numeric comparison: if two numbers
   compare equal (e.g., ``1`` and ``1.0``), only one of them can be contained in a
   set.

   There are currently two intrinsic set types:

   Sets
      .. index:: object: set

      These represent a mutable set. They are created by the built-in :func:`set`
      constructor and can be modified afterwards by several methods, such as
      :meth:`add`.

   Frozen sets
      .. index:: object: frozenset

      These represent an immutable set.  They are created by the built-in
      :func:`frozenset` constructor.  As a frozenset is immutable and
      :term:`hashable`, it can be used again as an element of another set, or as
      a dictionary key.

Mappings
   .. index::
      builtin: len
      single: subscription
      object: mapping

   These represent finite sets of objects indexed by arbitrary index sets. The
   subscript notation ``a[k]`` selects the item indexed by ``k`` from the mapping
   ``a``; this can be used in expressions and as the target of assignments or
   :keyword:`del` statements. The built-in function :func:`len` returns the number
   of items in a mapping.

   There is currently a single intrinsic mapping type:

   Dictionaries
      .. index:: object: dictionary

      These represent finite sets of objects indexed by nearly arbitrary values.  The
      only types of values not acceptable as keys are values containing lists or
      dictionaries or other mutable types that are compared by value rather than by
      object identity, the reason being that the efficient implementation of
      dictionaries requires a key's hash value to remain constant. Numeric types used
      for keys obey the normal rules for numeric comparison: if two numbers compare
      equal (e.g., ``1`` and ``1.0``) then they can be used interchangeably to index
      the same dictionary entry.

      Dictionaries are mutable; they can be created by the ``{...}`` notation (see
      section :ref:`dict`).

      .. index::
         module: dbm
         module: gdbm
         module: bsddb

      The extension modules :mod:`dbm`, :mod:`gdbm`, and :mod:`bsddb` provide
      additional examples of mapping types.

Callable types
   .. index::
      object: callable
      pair: function; call
      single: invocation
      pair: function; argument

   These are the types to which the function call operation (see section
   :ref:`calls`) can be applied:

   User-defined functions
      .. index::
         pair: user-defined; function
         object: function
         object: user-defined function

      A user-defined function object is created by a function definition (see
      section :ref:`function`).  It should be called with an argument list
      containing the same number of items as the function's formal parameter
      list.

      Special attributes:

      +-----------------------+-------------------------------+-----------+
      | Attribute             | Meaning                       |           |
      +=======================+===============================+===========+
      | :attr:`func_doc`      | The function's documentation  | Writable  |
      |                       | string, or ``None`` if        |           |
      |                       | unavailable                   |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`__doc__`       | Another way of spelling       | Writable  |
      |                       | :attr:`func_doc`              |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`func_name`     | The function's name           | Writable  |
      +-----------------------+-------------------------------+-----------+
      | :attr:`__name__`      | Another way of spelling       | Writable  |
      |                       | :attr:`func_name`             |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`__module__`    | The name of the module the    | Writable  |
      |                       | function was defined in, or   |           |
      |                       | ``None`` if unavailable.      |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`func_defaults` | A tuple containing default    | Writable  |
      |                       | argument values for those     |           |
      |                       | arguments that have defaults, |           |
      |                       | or ``None`` if no arguments   |           |
      |                       | have a default value          |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`func_code`     | The code object representing  | Writable  |
      |                       | the compiled function body.   |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`func_globals`  | A reference to the dictionary | Read-only |
      |                       | that holds the function's     |           |
      |                       | global variables --- the      |           |
      |                       | global namespace of the       |           |
      |                       | module in which the function  |           |
      |                       | was defined.                  |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`func_dict`     | The namespace supporting      | Writable  |
      |                       | arbitrary function            |           |
      |                       | attributes.                   |           |
      +-----------------------+-------------------------------+-----------+
      | :attr:`func_closure`  | ``None`` or a tuple of cells  | Read-only |
      |                       | that contain bindings for the |           |
      |                       | function's free variables.    |           |
      +-----------------------+-------------------------------+-----------+

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

      .. versionchanged:: 2.4
         ``func_name`` is now writable.

      Function objects also support getting and setting arbitrary attributes, which
      can be used, for example, to attach metadata to functions.  Regular attribute
      dot-notation is used to get and set such attributes. *Note that the current
      implementation only supports function attributes on user-defined functions.
      Function attributes on built-in functions may be supported in the future.*

      Additional information about a function's definition can be retrieved from its
      code object; see the description of internal types below.

      .. index::
         single: func_doc (function attribute)
         single: __doc__ (function attribute)
         single: __name__ (function attribute)
         single: __module__ (function attribute)
         single: __dict__ (function attribute)
         single: func_defaults (function attribute)
         single: func_closure (function attribute)
         single: func_code (function attribute)
         single: func_globals (function attribute)
         single: func_dict (function attribute)
         pair: global; namespace

   User-defined methods
      .. index::
         object: method
         object: user-defined method
         pair: user-defined; method

      A user-defined method object combines a class, a class instance (or ``None``)
      and any callable object (normally a user-defined function).

      Special read-only attributes: :attr:`im_self` is the class instance object,
      :attr:`im_func` is the function object; :attr:`im_class` is the class of
      :attr:`im_self` for bound methods or the class that asked for the method for
      unbound methods; :attr:`__doc__` is the method's documentation (same as
      ``im_func.__doc__``); :attr:`__name__` is the method name (same as
      ``im_func.__name__``); :attr:`__module__` is the name of the module the method
      was defined in, or ``None`` if unavailable.

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

      .. versionchanged:: 2.6
         For 3.0 forward-compatibility, :attr:`im_func` is also available as
         :attr:`__func__`, and :attr:`im_self` as :attr:`__self__`.

      .. index::
         single: __doc__ (method attribute)
         single: __name__ (method attribute)
         single: __module__ (method attribute)
         single: im_func (method attribute)
         single: im_self (method attribute)

      Methods also support accessing (but not setting) the arbitrary function
      attributes on the underlying function object.

      User-defined method objects may be created when getting an attribute of a class
      (perhaps via an instance of that class), if that attribute is a user-defined
      function object, an unbound user-defined method object, or a class method
      object. When the attribute is a user-defined method object, a new method object
      is only created if the class from which it is being retrieved is the same as, or
      a derived class of, the class stored in the original method object; otherwise,
      the original method object is used as it is.

      .. index::
         single: im_class (method attribute)
         single: im_func (method attribute)
         single: im_self (method attribute)

      When a user-defined method object is created by retrieving a user-defined
      function object from a class, its :attr:`im_self` attribute is ``None``
      and the method object is said to be unbound. When one is created by
      retrieving a user-defined function object from a class via one of its
      instances, its :attr:`im_self` attribute is the instance, and the method
      object is said to be bound. In either case, the new method's
      :attr:`im_class` attribute is the class from which the retrieval takes
      place, and its :attr:`im_func` attribute is the original function object.

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

      When a user-defined method object is created by retrieving another method object
      from a class or instance, the behaviour is the same as for a function object,
      except that the :attr:`im_func` attribute of the new instance is not the
      original method object but its :attr:`im_func` attribute.

      .. index::
         single: im_class (method attribute)
         single: im_func (method attribute)
         single: im_self (method attribute)

      When a user-defined method object is created by retrieving a class method object
      from a class or instance, its :attr:`im_self` attribute is the class itself (the
      same as the :attr:`im_class` attribute), and its :attr:`im_func` attribute is
      the function object underlying the class method.

      When an unbound user-defined method object is called, the underlying function
      (:attr:`im_func`) is called, with the restriction that the first argument must
      be an instance of the proper class (:attr:`im_class`) or of a derived class
      thereof.

      When a bound user-defined method object is called, the underlying function
      (:attr:`im_func`) is called, inserting the class instance (:attr:`im_self`) in
      front of the argument list.  For instance, when :class:`C` is a class which
      contains a definition for a function :meth:`f`, and ``x`` is an instance of
      :class:`C`, calling ``x.f(1)`` is equivalent to calling ``C.f(x, 1)``.

      When a user-defined method object is derived from a class method object, the
      "class instance" stored in :attr:`im_self` will actually be the class itself, so
      that calling either ``x.f(1)`` or ``C.f(1)`` is equivalent to calling ``f(C,1)``
      where ``f`` is the underlying function.

      Note that the transformation from function object to (unbound or bound) method
      object happens each time the attribute is retrieved from the class or instance.
      In some cases, a fruitful optimization is to assign the attribute to a local
      variable and call that local variable. Also notice that this transformation only
      happens for user-defined functions; other callable objects (and all non-callable
      objects) are retrieved without transformation.  It is also important to note
      that user-defined functions which are attributes of a class instance are not
      converted to bound methods; this *only* happens when the function is an
      attribute of the class.

   Generator functions
      .. index::
         single: generator; function
         single: generator; iterator

      A function or method which uses the :keyword:`yield` statement (see section
      :ref:`yield`) is called a :dfn:`generator
      function`.  Such a function, when called, always returns an iterator object
      which can be used to execute the body of the function:  calling the iterator's
      :meth:`next` method will cause the function to execute until it provides a value
      using the :keyword:`yield` statement.  When the function executes a
      :keyword:`return` statement or falls off the end, a :exc:`StopIteration`
      exception is raised and the iterator will have reached the end of the set of
      values to be returned.

   Built-in functions
      .. index::
         object: built-in function
         object: function
         pair: C; language

      A built-in function object is a wrapper around a C function.  Examples of
      built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
      standard built-in module). The number and type of the arguments are
      determined by the C function. Special read-only attributes:
      :attr:`__doc__` is the function's documentation string, or ``None`` if
      unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is
      set to ``None`` (but see the next item); :attr:`__module__` is the name of
      the module the function was defined in or ``None`` if unavailable.

   Built-in methods
      .. index::
         object: built-in method
         object: method
         pair: built-in; method

      This is really a different disguise of a built-in function, this time containing
      an object passed to the C function as an implicit extra argument.  An example of
      a built-in method is ``alist.append()``, assuming *alist* is a list object. In
      this case, the special read-only attribute :attr:`__self__` is set to the object
      denoted by *list*.

   Class Types
      Class types, or "new-style classes," are callable.  These objects normally act
      as factories for new instances of themselves, but variations are possible for
      class types that override :meth:`__new__`.  The arguments of the call are passed
      to :meth:`__new__` and, in the typical case, to :meth:`__init__` to initialize
      the new instance.

   Classic Classes
      .. index::
         single: __init__() (object method)
         object: class
         object: class instance
         object: instance
         pair: class object; call

      Class objects are described below.  When a class object is called, a new class
      instance (also described below) is created and returned.  This implies a call to
      the class's :meth:`__init__` method if it has one.  Any arguments are passed on
      to the :meth:`__init__` method.  If there is no :meth:`__init__` method, the
      class must be called without arguments.

   Class instances
      Class instances are described below.  Class instances are callable only when the
      class has a :meth:`__call__` method; ``x(arguments)`` is a shorthand for
      ``x.__call__(arguments)``.

Modules
   .. index::
      statement: import
      object: module

   Modules are imported by the :keyword:`import` statement (see section
   :ref:`import`). A module object has a
   namespace implemented by a dictionary object (this is the dictionary referenced
   by the func_globals attribute of functions defined in the module).  Attribute
   references are translated to lookups in this dictionary, e.g., ``m.x`` is
   equivalent to ``m.__dict__["x"]``. A module object does not contain the code
   object used to initialize the module (since it isn't needed once the
   initialization is done).

   Attribute assignment updates the module's namespace dictionary, e.g., ``m.x =
   1`` is equivalent to ``m.__dict__["x"] = 1``.

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

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

   .. index::
      single: __name__ (module attribute)
      single: __doc__ (module attribute)
      single: __file__ (module attribute)
      pair: module; namespace

   Predefined (writable) attributes: :attr:`__name__` is the module's name;
   :attr:`__doc__` is the module's documentation string, or ``None`` if
   unavailable; :attr:`__file__` is the pathname of the file from which the module
   was loaded, if it was loaded from a file. The :attr:`__file__` attribute is not
   present for C modules that are statically linked into the interpreter; for
   extension modules loaded dynamically from a shared library, it is the pathname
   of the shared library file.

Classes
   Both class types (new-style classes) and class objects (old-style/classic
   classes) are typically created by class definitions (see section
   :ref:`class`).  A class has a namespace implemented by a dictionary object.
   Class attribute references are translated to lookups in this dictionary, e.g.,
   ``C.x`` is translated to ``C.__dict__["x"]`` (although for new-style classes
   in particular there are a number of hooks which allow for other means of
   locating attributes). When the attribute name is not found there, the
   attribute search continues in the base classes.  For old-style classes, the
   search is depth-first, left-to-right in the order of occurrence in the base
   class list. New-style classes use the more complex C3 method resolution
   order which behaves correctly even in the presence of 'diamond'
   inheritance structures where there are multiple inheritance paths
   leading back to a common ancestor. Additional details on the C3 MRO used by
   new-style classes can be found in the documentation accompanying the
   2.3 release at http://www.python.org/download/releases/2.3/mro/.

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

   .. index::
      object: class
      object: class instance
      object: instance
      pair: class object; call
      single: container
      object: dictionary
      pair: class; attribute

   When a class attribute reference (for class :class:`C`, say) would yield a
   user-defined function object or an unbound user-defined method object whose
   associated class is either :class:`C` or one of its base classes, it is
   transformed into an unbound user-defined method object whose :attr:`im_class`
   attribute is :class:`C`. When it would yield a class method object, it is
   transformed into a bound user-defined method object whose :attr:`im_class`
   and :attr:`im_self` attributes are both :class:`C`.  When it would yield a
   static method object, it is transformed into the object wrapped by the static
   method object. See section :ref:`descriptors` for another way in which
   attributes retrieved from a class may differ from those actually contained in
   its :attr:`__dict__` (note that only new-style classes support descriptors).

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

   Class attribute assignments update the class's dictionary, never the dictionary
   of a base class.

   .. index:: pair: class object; call

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

   .. index::
      single: __name__ (class attribute)
      single: __module__ (class attribute)
      single: __dict__ (class attribute)
      single: __bases__ (class attribute)
      single: __doc__ (class attribute)

   Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is
   the module name in which the class was defined; :attr:`__dict__` is the
   dictionary containing the class's namespace; :attr:`__bases__` is a tuple
   (possibly empty or a singleton) containing the base classes, in the order of
   their occurrence in the base class list; :attr:`__doc__` is the class's
   documentation string, or None if undefined.

Class instances
   .. index::
      object: class instance
      object: instance
      pair: class; instance
      pair: class instance; attribute

   A class instance is created by calling a class object (see above). A class
   instance has a namespace implemented as a dictionary which is the first place in
   which attribute references are searched.  When an attribute is not found there,
   and the instance's class has an attribute by that name, the search continues
   with the class attributes.  If a class attribute is found that is a user-defined
   function object or an unbound user-defined method object whose associated class
   is the class (call it :class:`C`) of the instance for which the attribute
   reference was initiated or one of its bases, it is transformed into a bound
   user-defined method object whose :attr:`im_class` attribute is :class:`C` and
   whose :attr:`im_self` attribute is the instance. Static method and class method
   objects are also transformed, as if they had been retrieved from class
   :class:`C`; see above under "Classes". See section :ref:`descriptors` for
   another way in which attributes of a class retrieved via its instances may
   differ from the objects actually stored in the class's :attr:`__dict__`. If no
   class attribute is found, and the object's class has a :meth:`__getattr__`
   method, that is called to satisfy the lookup.

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

   Attribute assignments and deletions update the instance's dictionary, never a
   class's dictionary.  If the class has a :meth:`__setattr__` or
   :meth:`__delattr__` method, this is called instead of updating the instance
   dictionary directly.

   .. index::
      object: numeric
      object: sequence
      object: mapping

   Class instances can pretend to be numbers, sequences, or mappings if they have
   methods with certain special names.  See section :ref:`specialnames`.

   .. index::
      single: __dict__ (instance attribute)
      single: __class__ (instance attribute)

   Special attributes: :attr:`__dict__` is the attribute dictionary;
   :attr:`__class__` is the instance's class.

Files
   .. index::
      object: file
      builtin: open
      single: popen() (in module os)
      single: makefile() (socket method)
      single: sys.stdin
      single: sys.stdout
      single: sys.stderr
      single: stdio
      single: stdin (in module sys)
      single: stdout (in module sys)
      single: stderr (in module sys)

   A file object represents an open file.  File objects are created by the
   :func:`open` built-in function, and also by :func:`os.popen`,
   :func:`os.fdopen`, and the :meth:`makefile` method of socket objects (and
   perhaps by other functions or methods provided by extension modules).  The
   objects ``sys.stdin``, ``sys.stdout`` and ``sys.stderr`` are initialized to
   file objects corresponding to the interpreter's standard input, output and
   error streams.  See :ref:`bltin-file-objects` for complete documentation of
   file objects.

Internal types
   .. index::
      single: internal type
      single: types, internal

   A few types used internally by the interpreter are exposed to the user. Their
   definitions may change with future versions of the interpreter, but they are
   mentioned here for completeness.

   Code objects
      .. index::
         single: bytecode
         object: code

      Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
      The difference between a code object and a function object is that the function
      object contains an explicit reference to the function's globals (the module in
      which it was defined), while a code object contains no context; also the default
      argument values are stored in the function object, not in the code object
      (because they represent values calculated at run-time).  Unlike function
      objects, code objects are nearly immutable and contain no references (directly or
      indirectly) to mutable objects.

      Special read-only attributes: :attr:`co_name` gives the function name;
      :attr:`co_argcount` is the number of positional arguments (including arguments
      with default values); :attr:`co_nlocals` is the number of local variables used
      by the function (including arguments); :attr:`co_varnames` is a tuple containing
      the names of the local variables (starting with the argument names);
      :attr:`co_cellvars` is a tuple containing the names of local variables that are
      referenced by nested functions; :attr:`co_freevars` is a tuple containing the
      names of free variables; :attr:`co_code` is a string representing the sequence
      of bytecode instructions; :attr:`co_consts` is a tuple containing the literals
      used by the bytecode; :attr:`co_names` is a tuple containing the names used by
      the bytecode; :attr:`co_filename` is the filename from which the code was
      compiled; :attr:`co_firstlineno` is the first line number of the function;
      :attr:`co_lnotab` is a string encoding the mapping from bytecode offsets to line
      numbers (for details see the source code of the interpreter);
      :attr:`co_stacksize` is the required stack size (including local variables);
      :attr:`co_flags` is an integer encoding a number of flags for the interpreter.
      :attr:`co_llvm` refers to an llvm::Function wrapper that can pretty-print the
      LLVM assembly that implements this code object.

      Writable attributes: :attr:`co_use_jit` is ``True`` if LLVM will be used to
      run this function, or ``False`` if the normal CPython interpreter will be used.
      :attr:`co_optimization` is an integer from -1 to 2 recording how optimized
      :attr:`co_llvm` is.  -1 is totally unoptimized, and 0 is the default
      optimization that happens before a function is JITted.  You cannot lower the
      optimization level of an already-optimized function.

      .. index::
         single: co_argcount (code object attribute)
         single: co_code (code object attribute)
         single: co_consts (code object attribute)
         single: co_filename (code object attribute)
         single: co_firstlineno (code object attribute)
         single: co_flags (code object attribute)
         single: co_lnotab (code object attribute)
         single: co_name (code object attribute)
         single: co_names (code object attribute)
         single: co_nlocals (code object attribute)
         single: co_stacksize (code object attribute)
         single: co_varnames (code object attribute)
         single: co_cellvars (code object attribute)
         single: co_freevars (code object attribute)
         single: co_use_jit (code object attribute)
         single: co_optimization (code object attribute)
         single: co_llvm (code object attribute)

      .. index:: object: generator

      The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
      the function uses the ``*arguments`` syntax to accept an arbitrary number of
      positional arguments; bit ``0x08`` is set if the function uses the
      ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
      if the function is a generator.

      Future feature declarations (``from __future__ import division``) also use bits
      in :attr:`co_flags` to indicate whether a code object was compiled with a
      particular feature enabled: bit ``0x2000`` is set if the function was compiled
      with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
      versions of Python.

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

      .. index:: single: documentation string

      If a code object represents a function, the first item in :attr:`co_consts` is
      the documentation string of the function, or ``None`` if undefined.

   Frame objects
      .. index:: object: frame

      Frame objects represent execution frames.  They may occur in traceback objects
      (see below).

      .. index::
         single: f_back (frame attribute)
         single: f_code (frame attribute)
         single: f_globals (frame attribute)
         single: f_locals (frame attribute)
         single: f_lasti (frame attribute)
         single: f_builtins (frame attribute)
         single: f_restricted (frame attribute)

      Special read-only attributes: :attr:`f_back` is to the previous stack frame
      (towards the caller), or ``None`` if this is the bottom stack frame;
      :attr:`f_code` is the code object being executed in this frame; :attr:`f_locals`
      is the dictionary used to look up local variables; :attr:`f_globals` is used for
      global variables; :attr:`f_builtins` is used for built-in (intrinsic) names;
      :attr:`f_restricted` is a flag indicating whether the function is executing in
      restricted execution mode; :attr:`f_lasti` gives the precise instruction (this
      is an index into the bytecode string of the code object).

      .. index::
         single: f_trace (frame attribute)
         single: f_exc_type (frame attribute)
         single: f_exc_value (frame attribute)
         single: f_exc_traceback (frame attribute)
         single: f_lineno (frame attribute)

      Special writable attributes: :attr:`f_trace`, if not ``None``, is a function
      called at the start of each source code line (this is used by the debugger);
      :attr:`f_exc_type`, :attr:`f_exc_value`, :attr:`f_exc_traceback` represent the
      last exception raised in the parent frame provided another exception was ever
      raised in the current frame (in all other cases they are None); :attr:`f_lineno`
      is the current line number of the frame --- writing to this from within a trace
      function jumps to the given line (only for the bottom-most frame).  A debugger
      can implement a Jump command (aka Set Next Statement) by writing to f_lineno.

   Traceback objects
      .. index::
         object: traceback
         pair: stack; trace
         pair: exception; handler
         pair: execution; stack
         single: exc_info (in module sys)
         single: exc_traceback (in module sys)
         single: last_traceback (in module sys)
         single: sys.exc_info
         single: sys.exc_traceback
         single: sys.last_traceback

      Traceback objects represent a stack trace of an exception.  A traceback object
      is created when an exception occurs.  When the search for an exception handler
      unwinds the execution stack, at each unwound level a traceback object is
      inserted in front of the current traceback.  When an exception handler is
      entered, the stack trace is made available to the program. (See section
      :ref:`try`.) It is accessible as ``sys.exc_traceback``,
      and also as the third item of the tuple returned by ``sys.exc_info()``.  The
      latter is the preferred interface, since it works correctly when the program is
      using multiple threads. When the program contains no suitable handler, the stack
      trace is written (nicely formatted) to the standard error stream; if the
      interpreter is interactive, it is also made available to the user as
      ``sys.last_traceback``.

      .. index::
         single: tb_next (traceback attribute)
         single: tb_frame (traceback attribute)
         single: tb_lineno (traceback attribute)
         single: tb_lasti (traceback attribute)
         statement: try

      Special read-only attributes: :attr:`tb_next` is the next level in the stack
      trace (towards the frame where the exception occurred), or ``None`` if there is
      no next level; :attr:`tb_frame` points to the execution frame of the current
      level; :attr:`tb_lineno` gives the line number where the exception occurred;
      :attr:`tb_lasti` indicates the precise instruction.  The line number and last
      instruction in the traceback may differ from the line number of its frame object
      if the exception occurred in a :keyword:`try` statement with no matching except
      clause or with a finally clause.

   Slice objects
      .. index:: builtin: slice

      Slice objects are used to represent slices when *extended slice syntax* is us…