.. _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 is deprecated. While

it currently evaluates as true, it will emit a :exc:`DeprecationWarning`.

It will raise a :exc:`TypeError` in a future version of Python.

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.

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

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``.

.. 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. The comment above about negative indexes also applies

to negative slice positions.

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

single: integer

single: Unicode

A string is a sequence of values that represent Unicode code points.

All the code points in the range ``U+0000 - U+10FFFF`` can be

represented in a string. Python doesn't have a :c:expr:`char` 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 - 10FFFF``; :func:`chr` converts an integer in the range

``0 - 10FFFF`` 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 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 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.

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: __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: :ref:`annotations-howto`.

* - .. 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 contains a :keyword:`yield` expression (see section

:ref:`yieldexpr`) 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` expression. 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 contains a :keyword:`yield` expression 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: __cached__ (module attribute)

single: __doc__ (module attribute)

single: __annotations__ (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

modules created dynamically using the :class:`types.ModuleType` constructor;

use :func:`importlib.util.module_from_spec` instead to ensure the attribute

is set to a :class:`str`.

It is **strongly** recommended that you use

:attr:`module.__spec__.parent <importlib.machinery.ModuleSpec.parent>`

instead of :attr:`!module.__package__`. :attr:`__package__` is now only used

as a fallback if :attr:`!__spec__.parent` is not set, and this fallback

path is deprecated.

.. versionchanged:: 3.4

This attribute now defaults to ``None`` for modules created dynamically

using the :class:`types.ModuleType` constructor.

Previously the attribute was optional.

.. versionchanged:: 3.6

The value of :attr:`!__package__` is expected to be the same as

:attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.

:attr:`__package__` is now only used as a fallback during import

resolution if :attr:`!__spec__.parent` is not defined.

.. versionchanged:: 3.10

:exc:`ImportWarning` is raised if an import resolution falls back to

:attr:`!__package__` instead of

:attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`.

.. versionchanged:: 3.12

Raise :exc:`DeprecationWarning` instead of :exc:`ImportWarning` when

falling back to :attr:`!__package__` during import resolution.

.. deprecated-removed:: 3.13 3.15

:attr:`!__package__` will cease to be set or taken into consideration

by the import system or standard library.

.. attribute:: module.__loader__

The :term:`loader` object that the import machinery used to load the module.