.. _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: the current implementation 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.)

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::