datamodel.rst

.. _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. Even code is
represented by objects.

.. index::
   pair: built-in function; id
   pair: built-in function; 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.

.. impl-detail::

   For CPython, ``id(x)`` is the memory address where ``x`` is stored.

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).  Like its identity, an object's :dfn:`type` is also unchangeable.
[#]_

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.

.. impl-detail::

   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.
   Do not depend on immediate finalization of objects when they become
   unreachable (so you should always close files explicitly).

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
and the :keyword:`with` statement provide convenient ways 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.
For example, 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.
This is because :class:`int` is an immutable type, so the reference to ``1``
can be reused. This behaviour depends on the implementation used, so should
not be relied upon, but is something to be aware of when making use of object
identity tests.
However, after ``c = []; d = []``, *c* and *d* are guaranteed to refer to two
different, unique, newly created empty lists. (Note that ``e = f = []`` assigns
the *same* object to both *e* and *f*.)


.. _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.),
although such additions will often be provided via the standard library instead.

.. 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:: pair: 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:: pair: 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 :data:`NotImplemented`. Numeric methods
and rich comparison methods should 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.)  It
should not be evaluated in a boolean context.

See
:ref:`implementing-the-arithmetic-operations`
for more details.

.. versionchanged:: 3.9
   Evaluating :data:`NotImplemented` in a boolean context was deprecated.

.. versionchanged:: 3.14
   Evaluating :data:`NotImplemented` in a boolean context now raises a :exc:`TypeError`.
   It previously evaluated to :const:`True` and emitted a :exc:`DeprecationWarning`
   since Python 3.9.


Ellipsis
--------
.. index::
   pair: object; Ellipsis
   single: ...; ellipsis literal

This type has a single value.  There is a single object with this value. This
object is accessed through the literal ``...`` or the built-in name
``Ellipsis``.  Its truth value is true.


:class:`numbers.Number`
-----------------------

.. index:: pair: 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.

The string representations of the numeric classes, computed by
:meth:`~object.__repr__` and :meth:`~object.__str__`, have the following
properties:

* They are valid numeric literals which, when passed to their
  class constructor, produce an object having the value of the
  original numeric.

* The representation is in base 10, when possible.

* Leading zeros, possibly excepting a single zero before a
  decimal point, are not shown.

* Trailing zeros, possibly excepting a single zero after a
  decimal point, are not shown.

* A sign is shown only when the number is negative.

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


:class:`numbers.Integral`
^^^^^^^^^^^^^^^^^^^^^^^^^

.. index:: pair: object; integer

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

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

There are two types of integers:

Integers (:class:`int`)
   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 (:class:`bool`)
   .. index::
      pair: 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 the integer type, 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.


.. _datamodel-float:

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

.. index::
   pair: 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 are 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` (:class:`complex`)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. index::
   pair: 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``.

.. _datamodel-sequences:

Sequences
---------

.. index::
   pair: built-in function; len
   pair: 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]``. Some sequences,
including built-in sequences, interpret negative subscripts by adding the
sequence length. For example, ``a[-2]`` equals ``a[n-2]``, the second to last
item of sequence a with length ``n``.

The resulting value must be a nonnegative integer less than the number of items
in the sequence. If it is not, an :exc:`IndexError` is raised.

.. index::
   single: slicing
   single: start (slice object attribute)
   single: stop (slice object attribute)
   single: step (slice object attribute)

Sequences also support slicing: ``a[start:stop]`` selects all items with index *k* such
that *start* ``<=`` *k* ``<`` *stop*.  When used as an expression, a slice is a
sequence of the same type. The comment above about negative subscripts also applies
to negative slice positions.
Note that no error is raised if a slice position is less than zero or larger
than the length of the sequence.

If *start* is missing or :data:`None`, slicing behaves as if *start* was zero.
If *stop* is missing or ``None``, slicing behaves as if *stop* was equal to
the length of the sequence.

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::
   pair: object; immutable sequence
   pair: 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:

.. index::
   single: string; immutable sequences

Strings
   .. index::
      pair: built-in function; chr
      pair: built-in function; ord
      single: character
      pair: string; item
      single: Unicode

   A string (:class:`str`) is a sequence of values that represent
   :dfn:`characters`, or more formally, *Unicode code points*.
   All the code points in the range ``0`` to ``0x10FFFF`` can be
   represented in a string.

   Python doesn't have a dedicated *character* type.
   Instead, every code point in the string is represented as a string
   object with length ``1``.

   The built-in function :func:`ord`
   converts a code point from its string form to an integer in the
   range ``0`` to ``0x10FFFF``; :func:`chr` converts an integer in the range
   ``0`` to ``0x10FFFF`` to the corresponding length ``1`` string object.
   :meth:`str.encode` can be used to convert a :class:`str` to
   :class:`bytes` using the given text encoding, and
   :meth:`bytes.decode` can be used to achieve the opposite.

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

   The items of a :class:`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.

Bytes
   .. index:: bytes, byte

   A :class:`bytes` object is an immutable array.  The items are 8-bit bytes,
   represented by integers in the range 0 <= x < 256.  Bytes literals
   (like ``b'abc'``) and the built-in :func:`bytes` constructor
   can be used to create bytes objects.  Also, bytes objects can be
   decoded to strings via the :meth:`~bytes.decode` method.


Mutable sequences
^^^^^^^^^^^^^^^^^

.. index::
   pair: object; mutable sequence
   pair: object; mutable
   pair: assignment; statement
   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.

.. note::
   .. index:: pair: module; array
   .. index:: pair: module; collections

   The :mod:`collections` and :mod:`array` module provide
   additional examples of mutable sequence types.

There are currently two intrinsic mutable sequence types:

Lists
   .. index:: pair: 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.)

Byte Arrays
   .. index:: bytearray

   A bytearray object is a mutable array. They are created by the built-in
   :func:`bytearray` constructor.  Aside from being mutable
   (and hence unhashable), byte arrays otherwise provide the same interface
   and functionality as immutable :class:`bytes` objects.


Set types
---------

.. index::
   pair: built-in function; len
   pair: 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:: pair: 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:`~set.add`.


Frozen sets
   .. index:: pair: 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.


.. _datamodel-mappings:

Mappings
--------

.. index::
   pair: built-in function; len
   single: subscription
   pair: 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:: pair: 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 preserve insertion order, meaning that keys will be produced
in the same order they were added sequentially over the dictionary.
Replacing an existing key does not change the order, however removing a key
and re-inserting it will add it to the end instead of keeping its old place.

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

.. index::
   pair: module; dbm.ndbm
   pair: module; dbm.gnu

The extension modules :mod:`dbm.ndbm` and :mod:`dbm.gnu` provide
additional examples of mapping types, as does the :mod:`collections`
module.

.. versionchanged:: 3.7
   Dictionaries did not preserve insertion order in versions of Python before 3.6.
   In CPython 3.6, insertion order was preserved, but it was considered
   an implementation detail at that time rather than a language guarantee.


Callable types
--------------

.. index::
   pair: 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-funcs:

User-defined functions
^^^^^^^^^^^^^^^^^^^^^^

.. index::
   pair: user-defined; function
   pair: object; function
   pair: 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 read-only attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: __builtins__ (function attribute)
   single: __closure__ (function attribute)
   single: __globals__ (function attribute)
   pair: global; namespace

.. list-table::
   :header-rows: 1

   * - Attribute
     - Meaning

   * - .. attribute:: function.__builtins__
     - A reference to the :class:`dictionary <dict>` that holds the function's
       builtins namespace.

       .. versionadded:: 3.10

   * - .. attribute:: function.__globals__
     - A reference to the :class:`dictionary <dict>` that holds the function's
       :ref:`global variables <naming>` -- the global namespace of the module
       in which the function was defined.

   * - .. attribute:: function.__closure__
     - ``None`` or a :class:`tuple` of cells that contain bindings for the names specified
       in the :attr:`~codeobject.co_freevars` attribute of the function's
       :attr:`code object <function.__code__>`.

       A cell object has the attribute ``cell_contents``.
       This can be used to get the value of the cell, as well as set the value.

Special writable attributes
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. index::
   single: __doc__ (function attribute)
   single: __name__ (function attribute)
   single: __module__ (function attribute)
   single: __dict__ (function attribute)
   single: __defaults__ (function attribute)
   single: __code__ (function attribute)
   single: __annotations__ (function attribute)
   single: __annotate__ (function attribute)
   single: __kwdefaults__ (function attribute)
   single: __type_params__ (function attribute)

Most of these attributes check the type of the assigned value:

.. list-table::
   :header-rows: 1

   * - Attribute
     - Meaning

   * - .. attribute:: function.__doc__
     - The function's documentation string, or ``None`` if unavailable.

   * - .. attribute:: function.__name__
     - The function's name.
       See also: :attr:`__name__ attributes <definition.__name__>`.

   * - .. attribute:: function.__qualname__
     - The function's :term:`qualified name`.
       See also: :attr:`__qualname__ attributes <definition.__qualname__>`.

       .. versionadded:: 3.3

   * - .. attribute:: function.__module__
     - The name of the module the function was defined in,
       or ``None`` if unavailable.

   * - .. attribute:: function.__defaults__
     - A :class:`tuple` containing default :term:`parameter` values
       for those parameters that have defaults,
       or ``None`` if no parameters have a default value.

   * - .. attribute:: function.__code__
     - The :ref:`code object <code-objects>` representing
       the compiled function body.

   * - .. attribute:: function.__dict__
     - The namespace supporting arbitrary function attributes.
       See also: :attr:`__dict__ attributes <object.__dict__>`.

   * - .. attribute:: function.__annotations__
     - A :class:`dictionary <dict>` containing annotations of
       :term:`parameters <parameter>`.
       The keys of the dictionary are the parameter names,
       and ``'return'`` for the return annotation, if provided.
       See also: :attr:`object.__annotations__`.

       .. versionchanged:: 3.14
          Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
          See :pep:`649`.

   * - .. attribute:: function.__annotate__
     - The :term:`annotate function` for this function, or ``None``
       if the function has no annotations. See :attr:`object.__annotate__`.

       .. versionadded:: 3.14

   * - .. attribute:: function.__kwdefaults__
     - A :class:`dictionary <dict>` containing defaults for keyword-only
       :term:`parameters <parameter>`.

   * - .. attribute:: function.__type_params__
     - A :class:`tuple` containing the :ref:`type parameters <type-params>` of
       a :ref:`generic function <generic-functions>`.

       .. versionadded:: 3.12

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.

.. impl-detail::

   CPython's current implementation only supports function attributes
   on user-defined functions. Function attributes on
   :ref:`built-in functions <builtin-functions>` may be supported in the
   future.

Additional information about a function's definition can be retrieved from its
:ref:`code object <code-objects>`
(accessible via the :attr:`~function.__code__` attribute).


.. _instance-methods:

Instance methods
^^^^^^^^^^^^^^^^

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

An instance method object combines a class, a class instance and any
callable object (normally a user-defined function).

.. index::
   single: __func__ (method attribute)
   single: __self__ (method attribute)
   single: __doc__ (method attribute)
   single: __name__ (method attribute)
   single: __module__ (method attribute)

Special read-only attributes:

.. list-table::

   * - .. attribute:: method.__self__
     - Refers to the class instance object to which the method is
       :ref:`bound <method-binding>`

   * - .. attribute:: method.__func__
     - Refers to the original :ref:`function object <user-defined-funcs>`

   * - .. attribute:: method.__doc__
     - The method's documentation
       (same as :attr:`method.__func__.__doc__ <function.__doc__>`).
       A :class:`string <str>` if the original function had a docstring, else
       ``None``.

   * - .. attribute:: method.__name__
     - The name of the method
       (same as :attr:`method.__func__.__name__ <function.__name__>`)

   * - .. attribute:: method.__module__
     - The name of the module the method was defined in, or ``None`` if
       unavailable.

Methods also support accessing (but not setting) the arbitrary function
attributes on the underlying :ref:`function object <user-defined-funcs>`.

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 :ref:`function object <user-defined-funcs>` or a
:class:`classmethod` object.

.. _method-binding:

When an instance method object is created by retrieving a user-defined
:ref:`function object <user-defined-funcs>` from a class via one of its
instances, its :attr:`~method.__self__` attribute is the instance, and the
method object is said to be *bound*.  The new method's :attr:`~method.__func__`
attribute is the original function object.

When an instance method object is created by retrieving a :class:`classmethod`
object from a class or instance, its :attr:`~method.__self__` attribute is the
class itself, and its :attr:`~method.__func__` attribute is the function object
underlying the class method.

When an instance method object is called, the underlying function
(:attr:`~method.__func__`) is called, inserting the class instance
(:attr:`~method.__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 an instance method object is derived from a :class:`classmethod` object, the
"class instance" stored in :attr:`~method.__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.

It is 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 :term:`iterator` object which can be used to
execute the body of the function:  calling the iterator's
:meth:`iterator.__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.


Coroutine functions
^^^^^^^^^^^^^^^^^^^

.. index::
   single: coroutine; function

A function or method which is defined using :keyword:`async def` is called
a :dfn:`coroutine function`.  Such a function, when called, returns a
:term:`coroutine` object.  It may contain :keyword:`await` expressions,
as well as :keyword:`async with` and :keyword:`async for` statements. See
also the :ref:`coroutine-objects` section.


Asynchronous generator functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. index::
   single: asynchronous generator; function
   single: asynchronous generator; asynchronous iterator

A function or method which is defined using :keyword:`async def` and
which uses the :keyword:`yield` statement is called a
:dfn:`asynchronous generator function`.  Such a function, when called,
returns an :term:`asynchronous iterator` object which can be used in an
:keyword:`async for` statement to execute the body of the function.

Calling the asynchronous iterator's
:meth:`aiterator.__anext__ <object.__anext__>` method
will return an :term:`awaitable` which when awaited
will execute until it provides a value using the :keyword:`yield`
expression.  When the function executes an empty :keyword:`return`
statement or falls off the end, a :exc:`StopAsyncIteration` exception
is raised and the asynchronous iterator will have reached the end of
the set of values to be yielded.


.. _builtin-functions:

Built-in functions
^^^^^^^^^^^^^^^^^^

.. index::
   pair: object; built-in function
   pair: 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. See :attr:`function.__doc__`.
* :attr:`!__name__` is the function's name. See :attr:`function.__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.
  See :attr:`function.__module__`.


.. _builtin-methods:

Built-in methods
^^^^^^^^^^^^^^^^

.. index::
   pair: object; built-in method
   pair: 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 *alist*. (The attribute has the same semantics as it does with
:attr:`other instance methods <method.__self__>`.)

.. _classes:

Classes
^^^^^^^

Classes are callable.  These objects normally act as factories for new
instances of themselves, but variations are possible for class types that
override :meth:`~object.__new__`.  The arguments of the call are passed to
:meth:`!__new__` and, in the typical case, to :meth:`~object.__init__` to
initialize the new instance.


Class Instances
^^^^^^^^^^^^^^^

Instances of arbitrary classes can be made callable by defining a
:meth:`~object.__call__` method in their class.


.. _module-objects:

Modules
-------

.. index::
   pair: statement; import
   pair: object; module

Modules are a basic organizational unit of Python code, and are created by
the :ref:`import system <importsystem>` as invoked either by the
:keyword:`import` statement, or by calling
functions such as :func:`importlib.import_module` and built-in
:func:`__import__`.  A module object has a namespace implemented by a
:class:`dictionary <dict>` object (this is the dictionary referenced by the
:attr:`~function.__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: __name__ (module attribute)
   single: __spec__ (module attribute)
   single: __package__ (module attribute)
   single: __loader__ (module attribute)
   single: __path__ (module attribute)
   single: __file__ (module attribute)
   single: __doc__ (module attribute)
   single: __annotations__ (module attribute)
   single: __annotate__ (module attribute)
   single: __lazy_modules__ (module attribute)
   pair: module; namespace

.. _import-mod-attrs:

Import-related attributes on module objects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Module objects have the following attributes that relate to the
:ref:`import system <importsystem>`. When a module is created using the machinery associated
with the import system, these attributes are filled in based on the module's
:term:`spec <module spec>`, before the :term:`loader` executes and loads the
module.

To create a module dynamically rather than using the import system,
it's recommended to use :func:`importlib.util.module_from_spec`,
which will set the various import-controlled attributes to appropriate values.
It's also possible to use the :class:`types.ModuleType` constructor to create
modules directly, but this technique is more error-prone, as most attributes
must be manually set on the module object after it has been created when using
this approach.

.. caution::

   With the exception of :attr:`~module.__name__`, it is **strongly**
   recommended that you rely on :attr:`~module.__spec__` and its attributes
   instead of any of the other individual attributes listed in this subsection.
   Note that updating an attribute on :attr:`!__spec__` will not update the
   corresponding attribute on the module itself:

   .. doctest::

     >>> import typing
     >>> typing.__name__, typing.__spec__.name
     ('typing', 'typing')
     >>> typing.__spec__.name = 'spelling'
     >>> typing.__name__, typing.__spec__.name
     ('typing', 'spelling')
     >>> typing.__name__ = 'keyboard_smashing'
     >>> typing.__name__, typing.__spec__.name
     ('keyboard_smashing', 'spelling')

.. attribute:: module.__name__

   The name used to uniquely identify the module in the import system.
   For a directly executed module, this will be set to ``"__main__"``.

   This attribute must be set to the fully qualified name of the module.
   It is expected to match the value of
   :attr:`module.__spec__.name <importlib.machinery.ModuleSpec.name>`.

.. attribute:: module.__spec__

   A record of the module's import-system-related state.

   Set to the :class:`module spec <importlib.machinery.ModuleSpec>` that was
   used when importing the module. See :ref:`module-specs` for more details.

   .. versionadded:: 3.4

.. attribute:: module.__package__

   The :term:`package` a module belongs to.

   If the module is top-level (that is, not a part of any specific package)
   then the attribute should be set to ``''`` (the empty string). Otherwise,
   it should be set to the name of the module's package (which can be equal to
   :attr:`module.__name__` if the module itself is a package). See :pep:`366`
   for further details.

   This attribute is used instead of :attr:`~module.__name__` to calculate
   explicit relative imports for main modules. It defaults to ``None`` for