such modules have no way to know that the module object is an unknown (and
probably damaged with respect to the module author's intents) state.
- The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
- not set already, with the appropriate values. The spec's loader will
- be set to the module's ``__loader__`` (if set) and to an instance of
- :class:`~importlib.machinery.SourceFileLoader` otherwise.
+ The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be
+ set, if not set already, with the appropriate values. The spec's loader
+ will be set to the module's :attr:`!__loader__` (if set) and to an instance
+ of :class:`~importlib.machinery.SourceFileLoader` otherwise.
- The module's :attr:`__file__` attribute will be set to the code object's
- :attr:`~codeobject.co_filename`. If applicable, :attr:`__cached__` will also
- be set.
+ The module's :attr:`~module.__file__` attribute will be set to the code
+ object's :attr:`~codeobject.co_filename`. If applicable,
+ :attr:`~module.__cached__` will also be set.
This function will reload the module if it was already imported. See
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
:c:func:`PyImport_ExecCodeModuleWithPathnames`.
.. versionchanged:: 3.12
- The setting of :attr:`__cached__` and :attr:`__loader__` is
- deprecated. See :class:`~importlib.machinery.ModuleSpec` for
+ The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__`
+ is deprecated. See :class:`~importlib.machinery.ModuleSpec` for
alternatives.
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
- Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
- the module object is set to *pathname* if it is non-``NULL``.
+ Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__`
+ attribute of the module object is set to *pathname* if it is non-``NULL``.
See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
- Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
+ Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__`
attribute of the module object is set to *cpathname* if it is
non-``NULL``. Of the three functions, this is the preferred one to use.
.. versionadded:: 3.3
.. versionchanged:: 3.12
- Setting :attr:`__cached__` is deprecated. See
+ Setting :attr:`~module.__cached__` is deprecated. See
:class:`~importlib.machinery.ModuleSpec` for alternatives.
single: __package__ (module attribute)
single: __loader__ (module attribute)
- Return a new module object with the :attr:`__name__` attribute set to *name*.
- The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
- :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
- to ``None``); the caller is responsible for providing a :attr:`__file__`
- attribute.
+ Return a new module object with :attr:`module.__name__` set to *name*.
+ The module's :attr:`!__name__`, :attr:`~module.__doc__`,
+ :attr:`~module.__package__` and :attr:`~module.__loader__` attributes are
+ filled in (all but :attr:`!__name__` are set to ``None``). The caller is
+ responsible for setting a :attr:`~module.__file__` attribute.
Return ``NULL`` with an exception set on error.
.. versionadded:: 3.3
.. versionchanged:: 3.4
- :attr:`__package__` and :attr:`__loader__` are set to ``None``.
+ :attr:`~module.__package__` and :attr:`~module.__loader__` are now set to
+ ``None``.
.. c:function:: PyObject* PyModule_New(const char *name)
single: __name__ (module attribute)
single: SystemError (built-in exception)
- Return *module*'s :attr:`__name__` value. If the module does not provide one,
- or if it is not a string, :exc:`SystemError` is raised and ``NULL`` is returned.
+ Return *module*'s :attr:`~module.__name__` value. If the module does not
+ provide one, or if it is not a string, :exc:`SystemError` is raised and
+ ``NULL`` is returned.
.. versionadded:: 3.3
single: SystemError (built-in exception)
Return the name of the file from which *module* was loaded using *module*'s
- :attr:`__file__` attribute. If this is not defined, or if it is not a
- unicode string, raise :exc:`SystemError` and return ``NULL``; otherwise return
+ :attr:`~module.__file__` attribute. If this is not defined, or if it is not a
+ string, raise :exc:`SystemError` and return ``NULL``; otherwise return
a reference to a Unicode object.
.. versionadded:: 3.2
Pending Removal in Python 3.14
------------------------------
+* The import system:
+
+ * Setting :attr:`~module.__loader__` on a module while
+ failing to set :attr:`__spec__.loader <importlib.machinery.ModuleSpec.loader>`
+ is deprecated. In Python 3.14, :attr:`!__loader__` will cease to be set or
+ taken into consideration by the import system or the standard library.
+
* :mod:`argparse`: The *type*, *choices*, and *metavar* parameters
of :class:`!argparse.BooleanOptionalAction` are deprecated
and will be removed in 3.14.
Pending Removal in Python 3.15
------------------------------
+* The import system:
+
+ * Setting :attr:`~module.__cached__` on a module while
+ failing to set :attr:`__spec__.cached <importlib.machinery.ModuleSpec.cached>`
+ is deprecated. In Python 3.15, :attr:`!__cached__` will cease to be set or
+ take into consideration by the import system or standard library. (:gh:`97879`)
+
+ * Setting :attr:`~module.__package__` on a module while
+ failing to set :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>`
+ is deprecated. In Python 3.15, :attr:`!__package__` will cease to be set or
+ take into consideration by the import system or standard library. (:gh:`97879`)
+
* :mod:`ctypes`:
* The undocumented :func:`!ctypes.SetPointerType` function
* The :option:`!--cgi` flag to the :program:`python -m http.server`
command-line interface has been deprecated since Python 3.13.
-* :mod:`importlib`: ``__package__`` and ``__cached__`` will cease to be set or
- taken into consideration by the import system (:gh:`97879`).
-
* :class:`locale`:
* The :func:`~locale.getdefaultlocale` function
<meta path finder>` for use with :data:`sys.meta_path`, and :term:`path
entry finders <path entry finder>` for use with :data:`sys.path_hooks`.
- See :ref:`importsystem` and :mod:`importlib` for much more detail.
+ See :ref:`finders-and-loaders` and :mod:`importlib` for much more detail.
floor division
Mathematical division that rounds down to nearest integer. The floor
loader
An object that loads a module. It must define a method named
:meth:`load_module`. A loader is typically returned by a
- :term:`finder`. See :pep:`302` for details and
- :class:`importlib.abc.Loader` for an :term:`abstract base class`.
+ :term:`finder`. See also:
+
+ * :ref:`finders-and-loaders`
+ * :class:`importlib.abc.Loader`
+ * :pep:`302`
locale encoding
On Unix, it is the encoding of the LC_CTYPE locale. It can be set with
A namespace containing the import-related information used to load a
module. An instance of :class:`importlib.machinery.ModuleSpec`.
+ See also :ref:`module-specs`.
+
MRO
See :term:`method resolution order`.
(indicating a "simple" target). A "simple" target consists solely of a
:class:`Name` node that does not appear between parentheses; all other
targets are considered complex. Only simple targets appear in
- the :attr:`__annotations__` dictionary of modules and classes.
+ the :attr:`~object.__annotations__` dictionary of modules and classes.
.. doctest::
An abstract method for finding a :term:`spec <module spec>` for
the specified module. If this is a top-level import, *path* will
be ``None``. Otherwise, this is a search for a subpackage or
- module and *path* will be the value of :attr:`__path__` from the
+ module and *path* will be the value of :attr:`~module.__path__` from the
parent package. If a spec cannot be found, ``None`` is returned.
When passed in, ``target`` is a module object that the finder may
use to make a more educated guess about what spec to return.
(note that some of these attributes can change when a module is
reloaded):
- - :attr:`__name__`
- The module's fully qualified name.
- It is ``'__main__'`` for an executed module.
-
- - :attr:`__file__`
- The location the :term:`loader` used to load the module.
- For example, for modules loaded from a .py file this is the filename.
- It is not set on all modules (e.g. built-in modules).
-
- - :attr:`__cached__`
- The filename of a compiled version of the module's code.
- It is not set on all modules (e.g. built-in modules).
-
- - :attr:`__path__`
- The list of locations where the package's submodules will be found.
- Most of the time this is a single directory.
- The import system passes this attribute to ``__import__()`` and to finders
- in the same way as :data:`sys.path` but just for the package.
- It is not set on non-package modules so it can be used
- as an indicator that the module is a package.
-
- - :attr:`__package__`
- The fully qualified name of the package the module is in (or the
- empty string for a top-level module).
- If the module is a package then this is the same as :attr:`__name__`.
-
- - :attr:`__loader__`
- The :term:`loader` used to load the module.
+ - :attr:`module.__name__`
+ - :attr:`module.__file__`
+ - :attr:`module.__cached__` *(deprecated)*
+ - :attr:`module.__path__`
+ - :attr:`module.__package__` *(deprecated)*
+ - :attr:`module.__loader__` *(deprecated)*
When :meth:`exec_module` is available then backwards-compatible
functionality is provided.
can implement this abstract method to give direct access
to the data stored. :exc:`OSError` is to be raised if the *path* cannot
be found. The *path* is expected to be constructed using a module's
- :attr:`__file__` attribute or an item from a package's :attr:`__path__`.
+ :attr:`~module.__file__` attribute or an item from a package's
+ :attr:`~module.__path__`.
.. versionchanged:: 3.4
Raises :exc:`OSError` instead of :exc:`NotImplementedError`.
.. abstractmethod:: get_filename(fullname)
- An abstract method that is to return the value of :attr:`__file__` for
- the specified module. If no path is available, :exc:`ImportError` is
- raised.
+ An abstract method that is to return the value of
+ :attr:`~module.__file__` for the specified module. If no path is
+ available, :exc:`ImportError` is raised.
If source code is available, then the method should return the path to
the source file, regardless of whether a bytecode was used to load the
.. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None)
A specification for a module's import-system-related state. This is
- typically exposed as the module's :attr:`__spec__` attribute. Many
+ typically exposed as the module's :attr:`~module.__spec__` attribute. Many
of these attributes are also available directly on a module: for example,
``module.__spec__.origin == module.__file__``. Note, however, that
while the *values* are usually equivalent, they can differ since there is
- no synchronization between the two objects. For example, it is possible to update
- the module's :attr:`__file__` at runtime and this will not be automatically
- reflected in the module's :attr:`__spec__.origin`, and vice versa.
+ no synchronization between the two objects. For example, it is possible to
+ update the module's :attr:`~module.__file__` at runtime and this will not be
+ automatically reflected in the module's
+ :attr:`__spec__.origin <ModuleSpec.origin>`, and vice versa.
.. versionadded:: 3.4
.. attribute:: name
- The module's fully qualified name
- (see :attr:`__name__` attributes on modules).
+ The module's fully qualified name (see :attr:`module.__name__`).
The :term:`finder` should always set this attribute to a non-empty string.
.. attribute:: loader
- The :term:`loader` used to load the module
- (see :attr:`__loader__` attributes on modules).
+ The :term:`loader` used to load the module (see :attr:`module.__loader__`).
The :term:`finder` should always set this attribute.
.. attribute:: origin
The location the :term:`loader` should use to load the module
- (see :attr:`__file__` attributes on modules).
- For example, for modules loaded from a .py file this is the filename.
+ (see :attr:`module.__file__`).
+ For example, for modules loaded from a ``.py`` file this is the filename.
The :term:`finder` should always set this attribute to a meaningful value
for the :term:`loader` to use. In the uncommon case that there is not one
(like for namespace packages), it should be set to ``None``.
.. attribute:: submodule_search_locations
- The list of locations where the package's submodules will be found
- (see :attr:`__path__` attributes on modules).
- Most of the time this is a single directory.
- The :term:`finder` should set this attribute to a list, even an empty one, to indicate
+ A (possibly empty) :term:`sequence` of strings enumerating the locations
+ in which a package's submodules will be found
+ (see :attr:`module.__path__`). Most of the time there will only be a
+ single directory in this list.
+
+ The :term:`finder` should set this attribute to a sequence, even an empty
+ one, to indicate
to the import system that the module is a package. It should be set to ``None`` for
non-package modules. It is set automatically later to a special object for
namespace packages.
.. attribute:: cached
The filename of a compiled version of the module's code
- (see :attr:`__cached__` attributes on modules).
+ (see :attr:`module.__cached__`).
The :term:`finder` should always set this attribute but it may be ``None``
for modules that do not need compiled code stored.
(Read-only) The fully qualified name of the package the module is in (or the
empty string for a top-level module).
- See :attr:`__package__` attributes on modules.
+ See :attr:`module.__package__`.
If the module is a package then this is the same as :attr:`name`.
.. attribute:: has_location
``True`` if the spec's :attr:`origin` refers to a loadable location,
- ``False`` otherwise. This value impacts how :attr:`origin` is interpreted
- and how the module's :attr:`__file__` is populated.
+ ``False`` otherwise. This value impacts how :attr:`!origin` is interpreted
+ and how the module's :attr:`~module.__file__` is populated.
.. class:: AppleFrameworkLoader(name, path)
.. versionchanged:: 3.7
Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if
- **package** is in fact not a package (i.e. lacks a :attr:`__path__`
- attribute).
+ **package** is in fact not a package (i.e. lacks a
+ :attr:`~module.__path__` attribute).
.. function:: module_from_spec(spec)
__path__ = extend_path(__path__, __name__)
For each directory on :data:`sys.path` that has a subdirectory that matches the
- package name, add the subdirectory to the package's :attr:`__path__`. This is useful
+ package name, add the subdirectory to the package's
+ :attr:`~module.__path__`. This is useful
if one wants to distribute different parts of a single logical package as multiple
directories.
that implement Python's default import semantics. The
:meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at
least the absolute name of the module being imported. If the module to be
- imported is contained in a package, then the parent package's :attr:`__path__`
+ imported is contained in a package, then the parent package's
+ :attr:`~module.__path__`
attribute is passed in as a second argument. The method returns a
:term:`module spec`, or ``None`` if the module cannot be found.
The type of :term:`modules <module>`. The constructor takes the name of the
module to be created and optionally its :term:`docstring`.
- .. note::
- Use :func:`importlib.util.module_from_spec` to create a new module if you
- wish to set the various import-controlled attributes.
-
- .. attribute:: __doc__
-
- The :term:`docstring` of the module. Defaults to ``None``.
-
- .. attribute:: __loader__
-
- The :term:`loader` which loaded the module. Defaults to ``None``.
-
- This attribute is to match :attr:`importlib.machinery.ModuleSpec.loader`
- as stored in the :attr:`__spec__` object.
-
- .. note::
- A future version of Python may stop setting this attribute by default.
- To guard against this potential change, preferably read from the
- :attr:`__spec__` attribute instead or use
- ``getattr(module, "__loader__", None)`` if you explicitly need to use
- this attribute.
-
- .. versionchanged:: 3.4
- Defaults to ``None``. Previously the attribute was optional.
-
- .. attribute:: __name__
-
- The name of the module. Expected to match
- :attr:`importlib.machinery.ModuleSpec.name`.
-
- .. attribute:: __package__
-
- Which :term:`package` a module belongs to. If the module is top-level
- (i.e. not a part of any specific package) then the attribute should be set
- to ``''``, else it should be set to the name of the package (which can be
- :attr:`__name__` if the module is a package itself). Defaults to ``None``.
-
- This attribute is to match :attr:`importlib.machinery.ModuleSpec.parent`
- as stored in the :attr:`__spec__` object.
-
- .. note::
- A future version of Python may stop setting this attribute by default.
- To guard against this potential change, preferably read from the
- :attr:`__spec__` attribute instead or use
- ``getattr(module, "__package__", None)`` if you explicitly need to use
- this attribute.
-
- .. versionchanged:: 3.4
- Defaults to ``None``. Previously the attribute was optional.
-
- .. attribute:: __spec__
-
- A record of the module's import-system-related state. Expected to be an
- instance of :class:`importlib.machinery.ModuleSpec`.
+ .. seealso::
- .. versionadded:: 3.4
+ :ref:`Documentation on module objects <module-objects>`
+ Provides details on the special attributes that can be found on
+ instances of :class:`!ModuleType`.
+ :func:`importlib.util.module_from_spec`
+ Modules created using the :class:`!ModuleType` constructor are
+ created with many of their special attributes unset or set to default
+ values. :func:`!module_from_spec` provides a more robust way of
+ creating :class:`!ModuleType` instances which ensures the various
+ attributes are set appropriately.
.. data:: EllipsisType
:meth:`~object.__call__` method in their class.
+.. _module-objects:
+
Modules
-------
.. index::
single: __name__ (module attribute)
- single: __doc__ (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)
single: __annotate__ (module attribute)
pair: module; namespace
-Predefined (writable) attributes:
+.. _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__
- :attr:`__name__`
- The module's name.
+ The name used to uniquely identify the module in the import system.
+ For a directly executed module, this will be set to ``"__main__"``.
- :attr:`__doc__`
- The module's documentation string, or ``None`` if
- unavailable.
+ 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>`.
- :attr:`__file__`
- The pathname of the file from which the
- module was loaded, if it was loaded from a file.
- The :attr:`__file__`
- attribute may be missing for certain types of modules, such as C modules
- that are statically linked into the interpreter. For extension modules
- loaded dynamically from a shared library, it's the pathname of the shared
- library file.
+.. attribute:: module.__spec__
- :attr:`~object.__annotations__`
- A dictionary containing
- :term:`variable annotations <variable annotation>` collected during
- module body execution. For best practices on working
- with :attr:`!__annotations__`, see :mod:`annotationlib`.
+ 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.
- .. versionchanged:: 3.14
- Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
- See :pep:`649`.
+ .. deprecated-removed:: 3.13 3.15
+ :attr:`!__package__` will cease to be set or taken into consideration
+ by the import system or standard library.
- :attr:`~object.__annotate__`
- The :term:`annotate function` for this module, or ``None``
- if the module has no annotations. See :attr:`object.__annotate__`.
+.. attribute:: module.__loader__
- .. versionadded:: 3.14
+ The :term:`loader` object that the import machinery used to load the module.
+
+ This attribute is mostly useful for introspection, but can be used for
+ additional loader-specific functionality, for example getting data
+ associated with a loader.
+
+ :attr:`!__loader__` 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 :term:`loader` object.
+
+ It is **strongly** recommended that you use
+ :attr:`module.__spec__.loader <importlib.machinery.ModuleSpec.loader>`
+ instead of :attr:`!module.__loader__`.
+
+ .. versionchanged:: 3.4
+ This attribute now defaults to ``None`` for modules created dynamically
+ using the :class:`types.ModuleType` constructor.
+ Previously the attribute was optional.
+
+ .. deprecated-removed:: 3.12 3.14
+ Setting :attr:`!__loader__` on a module while failing to set
+ :attr:`!__spec__.loader` is deprecated. In Python 3.14,
+ :attr:`!__loader__` will cease to be set or taken into consideration by
+ the import system or the standard library.
+
+.. attribute:: module.__path__
+
+ A (possibly empty) :term:`sequence` of strings enumerating the locations
+ where the package's submodules will be found. Non-package modules should
+ not have a :attr:`!__path__` attribute. See :ref:`package-path-rules` for
+ more details.
+
+ It is **strongly** recommended that you use
+ :attr:`module.__spec__.submodule_search_locations <importlib.machinery.ModuleSpec.submodule_search_locations>`
+ instead of :attr:`!module.__path__`.
+
+.. attribute:: module.__file__
+.. attribute:: module.__cached__
+
+ :attr:`!__file__` and :attr:`!__cached__` are both optional attributes that
+ may or may not be set. Both attributes should be a :class:`str` when they
+ are available.
+
+ :attr:`!__file__` indicates the pathname of the file from which the module
+ was loaded (if loaded from a file), or the pathname of the shared library
+ file for extension modules loaded dynamically from a shared library.
+ It might be missing for certain types of modules, such as C modules that are
+ statically linked into the interpreter, and the
+ :ref:`import system <importsystem>` may opt to leave it unset if it
+ has no semantic meaning (for example, a module loaded from a database).
+
+ If :attr:`!__file__` is set then the :attr:`!__cached__` attribute might
+ also be set, which is the path to any compiled version of
+ the code (for example, a byte-compiled file). The file does not need to exist
+ to set this attribute; the path can simply point to where the
+ compiled file *would* exist (see :pep:`3147`).
+
+ Note that :attr:`!__cached__` may be set even if :attr:`!__file__` is not
+ set. However, that scenario is quite atypical. Ultimately, the
+ :term:`loader` is what makes use of the module spec provided by the
+ :term:`finder` (from which :attr:`!__file__` and :attr:`!__cached__` are
+ derived). So if a loader can load from a cached module but otherwise does
+ not load from a file, that atypical scenario may be appropriate.
+
+ It is **strongly** recommended that you use
+ :attr:`module.__spec__.cached <importlib.machinery.ModuleSpec.cached>`
+ instead of :attr:`!module.__cached__`.
+
+ .. deprecated-removed:: 3.13 3.15
+ Setting :attr:`!__cached__` on a module while failing to set
+ :attr:`!__spec__.cached` is deprecated. In Python 3.15,
+ :attr:`!__cached__` will cease to be set or taken into consideration by
+ the import system or standard library.
+
+Other writable attributes on module objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As well as the import-related attributes listed above, module objects also have
+the following writable attributes:
+
+.. attribute:: module.__doc__
+
+ The module's documentation string, or ``None`` if unavailable.
+ See also: :attr:`__doc__ attributes <definition.__doc__>`.
+
+.. attribute:: module.__annotations__
+
+ A dictionary containing :term:`variable annotations <variable annotation>`
+ collected during module body execution. For best practices on working with
+ :attr:`!__annotations__`, see :mod:`annotationlib`.
+
+ .. versionchanged:: 3.14
+ Annotations are now :ref:`lazily evaluated <lazy-evaluation>`.
+ See :pep:`649`.
+
+.. attribute:: module.__annotate__
+
+ The :term:`annotate function` for this module, or ``None`` if the module has
+ no annotations. See also: :attr:`~object.__annotate__` attributes.
+
+ .. versionadded:: 3.14
+
+Module dictionaries
+^^^^^^^^^^^^^^^^^^^
+
+Module objects also have the following special read-only attribute:
.. index:: single: __dict__ (module attribute)
+.. attribute:: module.__dict__
-Special read-only attribute: :attr:`~object.__dict__` is the module's
-namespace as a dictionary object.
+ The module's namespace as a dictionary object. Uniquely among the attributes
+ listed here, :attr:`!__dict__` cannot be accessed as a global variable from
+ within a module; it can only be accessed as an attribute on module objects.
-.. impl-detail::
+ .. impl-detail::
- Because of the way CPython clears module dictionaries, the module
- dictionary will be cleared when the module falls out of scope even if the
- dictionary still has live references. To avoid this, copy the dictionary
- or keep the module around while using its dictionary directly.
+ Because of the way CPython clears module dictionaries, the module
+ dictionary will be cleared when the module falls out of scope even if the
+ dictionary still has live references. To avoid this, copy the dictionary
+ or keep the module around while using its dictionary directly.
.. _class-attrs-and-methods:
``sys.modules['spam.foo']`` (as you would after the above import), the latter
must appear as the ``foo`` attribute of the former.
-Module spec
------------
+.. _module-specs:
+
+Module specs
+------------
The import machinery uses a variety of information about each module
during import, especially before loading. Most of the information is
import machinery to perform the boilerplate operations of loading,
whereas without a module spec the loader had that responsibility.
-The module's spec is exposed as the ``__spec__`` attribute on a module object.
+The module's spec is exposed as :attr:`module.__spec__`. Setting
+:attr:`!__spec__` appropriately applies equally to
+:ref:`modules initialized during interpreter startup <programs>`.
+The one exception is ``__main__``, where :attr:`!__spec__` is
+:ref:`set to None in some cases <main_spec>`.
+
See :class:`~importlib.machinery.ModuleSpec` for details on the contents of
the module spec.
.. versionadded:: 3.4
-.. _import-mod-attrs:
-
-Import-related module attributes
---------------------------------
-
-The import machinery fills in these attributes on each module object
-during loading, based on the module's spec, before the loader executes
-the module.
-
-It is **strongly** recommended that you rely on :attr:`__spec__` and
-its attributes instead of any of the other individual attributes
-listed below, except :attr:`__name__`.
-
-.. attribute:: __name__
-
- The ``__name__`` attribute must be set to the fully qualified name of
- the module. This name is used to uniquely identify the module in
- the import system.
-
-.. attribute:: __loader__
-
- The ``__loader__`` attribute must be set to the loader object that
- the import machinery used when loading the module. This is mostly
- for introspection, but can be used for additional loader-specific
- functionality, for example getting data associated with a loader.
-
- It is **strongly** recommended that you rely on :attr:`__spec__`
- instead of this attribute.
-
- .. versionchanged:: 3.12
- The value of ``__loader__`` is expected to be the same as
- ``__spec__.loader``. The use of ``__loader__`` is deprecated and slated
- for removal in Python 3.14.
-
-.. attribute:: __package__
-
- The module's ``__package__`` attribute may be set. Its value must
- be a string, but it can be the same value as its ``__name__``. When
- the module is a package, its ``__package__`` value should be set to
- its ``__name__``. When the module is not a package, ``__package__``
- should be set to the empty string for top-level modules, or for
- submodules, to the parent package's name. See :pep:`366` for further
- details.
-
- This attribute is used instead of ``__name__`` to calculate explicit
- relative imports for main modules, as defined in :pep:`366`.
-
- It is **strongly** recommended that you rely on :attr:`__spec__`
- instead of this attribute.
-
- .. versionchanged:: 3.6
- The value of ``__package__`` is expected to be the same as
- ``__spec__.parent``.
-
- .. versionchanged:: 3.10
- :exc:`ImportWarning` is raised if import falls back to
- ``__package__`` instead of
- :attr:`~importlib.machinery.ModuleSpec.parent`.
-
- .. versionchanged:: 3.12
- Raise :exc:`DeprecationWarning` instead of :exc:`ImportWarning`
- when falling back to ``__package__``.
-
- .. deprecated-removed:: 3.13 3.15
- ``__package__`` will cease to be set or taken into consideration
- by the import system or standard library.
-
-
-.. attribute:: __spec__
-
- The ``__spec__`` attribute must be set to the module spec that was
- used when importing the module. Setting ``__spec__``
- appropriately applies equally to :ref:`modules initialized during
- interpreter startup <programs>`. The one exception is ``__main__``,
- where ``__spec__`` is :ref:`set to None in some cases <main_spec>`.
-
- When ``__spec__.parent`` is not set, ``__package__`` is used as
- a fallback.
-
- .. versionadded:: 3.4
-
- .. versionchanged:: 3.6
- ``__spec__.parent`` is used as a fallback when ``__package__`` is
- not defined.
-
-.. attribute:: __path__
-
- If the module is a package (either regular or namespace), the module
- object's ``__path__`` attribute must be set. The value must be
- iterable, but may be empty if ``__path__`` has no further significance.
- If ``__path__`` is not empty, it must produce strings when iterated
- over. More details on the semantics of ``__path__`` are given
- :ref:`below <package-path-rules>`.
-
- Non-package modules should not have a ``__path__`` attribute.
-
-.. attribute:: __file__
-.. attribute:: __cached__
-
- ``__file__`` is optional (if set, value must be a string). It indicates
- the pathname of the file from which the module was loaded (if
- loaded from a file), or the pathname of the shared library file
- for extension modules loaded dynamically from a shared library.
- It might be missing for certain types of modules, such as C
- modules that are statically linked into the interpreter, and the
- import system may opt to leave it unset if it has no semantic
- meaning (e.g. a module loaded from a database).
-
- If ``__file__`` is set then the ``__cached__`` attribute might also
- be set, which is the path to any compiled version of
- the code (e.g. byte-compiled file). The file does not need to exist
- to set this attribute; the path can simply point to where the
- compiled file would exist (see :pep:`3147`).
-
- Note that ``__cached__`` may be set even if ``__file__`` is not
- set. However, that scenario is quite atypical. Ultimately, the
- loader is what makes use of the module spec provided by the finder
- (from which ``__file__`` and ``__cached__`` are derived). So
- if a loader can load from a cached module but otherwise does not load
- from a file, that atypical scenario may be appropriate.
-
- It is **strongly** recommended that you rely on :attr:`__spec__`
- instead of ``__cached__``.
-
- .. deprecated-removed:: 3.13 3.15
- ``__cached__`` will cease to be set or taken into consideration
- by the import system or standard library.
-
.. _package-path-rules:
-module.__path__
----------------
+__path__ attributes on modules
+------------------------------
-By definition, if a module has a ``__path__`` attribute, it is a package.
+The :attr:`~module.__path__` attribute should be a (possibly empty)
+:term:`sequence` of strings enumerating the locations where the package's
+submodules will be found. By definition, if a module has a :attr:`!__path__`
+attribute, it is a :term:`package`.
-A package's ``__path__`` attribute is used during imports of its subpackages.
+A package's :attr:`~module.__path__` attribute is used during imports of its
+subpackages.
Within the import machinery, it functions much the same as :data:`sys.path`,
i.e. providing a list of locations to search for modules during import.
-However, ``__path__`` is typically much more constrained than
-:data:`sys.path`.
+However, :attr:`!__path__` is typically much more constrained than
+:data:`!sys.path`.
-``__path__`` must be an iterable of strings, but it may be empty.
The same rules used for :data:`sys.path` also apply to a package's
-``__path__``, and :data:`sys.path_hooks` (described below) are
-consulted when traversing a package's ``__path__``.
+:attr:`!__path__`. :data:`sys.path_hooks` (described below) are
+consulted when traversing a package's :attr:`!__path__`.
-A package's ``__init__.py`` file may set or alter the package's ``__path__``
+A package's ``__init__.py`` file may set or alter the package's
+:attr:`~module.__path__`
attribute, and this was typically the way namespace packages were implemented
prior to :pep:`420`. With the adoption of :pep:`420`, namespace packages no
-longer need to supply ``__init__.py`` files containing only ``__path__``
-manipulation code; the import machinery automatically sets ``__path__``
+longer need to supply ``__init__.py`` files containing only :attr:`!__path__`
+manipulation code; the import machinery automatically sets :attr:`!__path__`
correctly for the namespace package.
Module reprs
Packages in Multiple Directories
--------------------------------
-Packages support one more special attribute, :attr:`__path__`. This is
-initialized to be a list containing the name of the directory holding the
+Packages support one more special attribute, :attr:`~module.__path__`. This is
+initialized to be a :term:`sequence` of strings containing the name of the
+directory holding the
package's :file:`__init__.py` before the code in that file is executed. This
variable can be modified; doing so affects future searches for modules and
subpackages contained in the package.
When you ran a module that was located inside a package, relative
imports didn't work correctly.
-The fix for Python 2.6 adds a :attr:`__package__` attribute to
-modules. When this attribute is present, relative imports will be
+The fix for Python 2.6 adds a :attr:`module.__package__` attribute.
+When this attribute is present, relative imports will be
relative to the value of this attribute instead of the
-:attr:`__name__` attribute.
+:attr:`~module.__name__` attribute.
-PEP 302-style importers can then set :attr:`__package__` as necessary.
+PEP 302-style importers can then set :attr:`~module.__package__` as necessary.
The :mod:`runpy` module that implements the :option:`-m` switch now
does this, so relative imports will now work correctly in scripts
running from inside a package.
provides a standardized way of annotating a function's parameters
and return value. There are no semantics attached to such
annotations except that they can be introspected at runtime using
- the :attr:`__annotations__` attribute. The intent is to encourage
- experimentation through metaclasses, decorators or frameworks.
+ the :attr:`~object.__annotations__` attribute. The intent is to
+ encourage experimentation through metaclasses, decorators or frameworks.
* :pep:`3102`: Keyword-only arguments. Named parameters occurring
after ``*args`` in the parameter list *must* be specified using
may be removed in a future version of Python. Use the single-arg versions
of these functions instead. (Contributed by Ofey Chan in :gh:`89874`.)
-* :exc:`DeprecationWarning` is now raised when ``__package__`` on a
- module differs from ``__spec__.parent`` (previously it was
- :exc:`ImportWarning`).
+* :exc:`DeprecationWarning` is now raised when :attr:`~module.__package__` on a
+ module differs from
+ :attr:`__spec__.parent <importlib.machinery.ModuleSpec.parent>` (previously
+ it was :exc:`ImportWarning`).
(Contributed by Brett Cannon in :gh:`65961`.)
-* Setting ``__package__`` or ``__cached__`` on a module is deprecated,
- and will cease to be set or taken into consideration by the import system in Python 3.14.
- (Contributed by Brett Cannon in :gh:`65961`.)
+* Setting :attr:`~module.__package__` or :attr:`~module.__cached__` on a
+ module is deprecated, and will cease to be set or taken into consideration by
+ the import system in Python 3.14. (Contributed by Brett Cannon in :gh:`65961`.)
* The bitwise inversion operator (``~``) on bool is deprecated. It will throw an
error in Python 3.16. Use ``not`` for logical negation of bools instead.
Aside from the filenames and target directories, the new scheme has a few
aspects that are visible to the programmer:
-* Imported modules now have a :attr:`__cached__` attribute which stores the name
- of the actual file that was imported:
+* Imported modules now have a :attr:`~module.__cached__` attribute which stores
+ the name of the actual file that was imported:
>>> import collections
>>> collections.__cached__ # doctest: +SKIP
:func:`super` and falling through all the way to the ABCs. For compatibility,
catch both :exc:`NotImplementedError` or the appropriate exception as needed.
-* The module type now initializes the :attr:`__package__` and :attr:`__loader__`
+* The module type now initializes the :attr:`~module.__package__` and
+ :attr:`~module.__loader__`
attributes to ``None`` by default. To determine if these attributes were set
in a backwards-compatible fashion, use e.g.
``getattr(module, '__loader__', None) is not None``. (:issue:`17115`.)
return 'Hello ' + name
While these annotations are available at runtime through the usual
-:attr:`__annotations__` attribute, *no automatic type checking happens at
-runtime*. Instead, it is assumed that a separate off-line type checker
+:attr:`~object.__annotations__` attribute, *no automatic type checking happens
+at runtime*. Instead, it is assumed that a separate off-line type checker
(e.g. `mypy <https://mypy-lang.org>`_) will be used for on-demand
source code analysis.
.. section: Core and Builtins
Enable ``from __future__ import annotations`` (:pep:`563`) by default. The
-values found in :attr:`__annotations__` dicts are now strings, e.g. ``{"x":
-"int"}`` instead of ``{"x": int}``.
+values found in :attr:`~object.__annotations__` dicts are now strings, for
+example ``{"x": "int"}`` instead of ``{"x": int}``.
..
.. nonce: geS-aP
.. section: Library
-:mod:`pdb` now gracefully handles ``help`` when :attr:`__doc__` is missing,
-for example when run with pregenerated optimized ``.pyc`` files.
+:mod:`pdb` now gracefully handles ``help`` when :attr:`~module.__doc__` is
+missing, for example when run with pregenerated optimized ``.pyc`` files.
..
.. nonce: 4dzB80
.. section: Library
-Set :attr:`doctest.DocTest.lineno` to ``None`` when object does not have
-:attr:`__doc__`.
+Set :attr:`doctest.DocTest.lineno` to ``None`` when an object does not have
+:attr:`~definition.__doc__`.
..
:func:`classmethod` and :func:`staticmethod` now wrap the
-:attr:`__annotations__` and :attr:`!__annotate__` attributes of their
-underlying callable lazily. See :pep:`649`. Patch by Jelle Zijlstra.
+:attr:`~object.__annotations__` and :attr:`~object.__annotate__` attributes of
+their underlying callable lazily. See :pep:`649`. Patch by Jelle Zijlstra.
projects / thirdparty / Python / cpython.git / commitdiff
