:mod:`!importlib` --- The implementation of :keyword:`!import`

.. module:: importlib

.. versionadded:: 3.1

**Source code:** :source:`Lib/importlib/__init__.py`

Introduction

One is to provide the

implementation of the :keyword:`import` statement (and thus, by extension, the

:func:`__import__` function) in Python source code. This provides an

Three, the package contains modules exposing additional functionality for

managing aspects of Python packages:

* :mod:`importlib.metadata` presents access to metadata from third-party

distributions.

* :mod:`importlib.resources` provides routines for accessing non-code

"resources" from Python packages.

.. seealso::

:ref:`import`

The language reference for the :keyword:`import` statement.

in :data:`sys.modules`).

The :func:`.__import__` function

:ref:`sys-path-init`

The initialization of :data:`sys.path`.

:pep:`235`

Import on Case-Insensitive Platforms

:pep:`263`

Defining Python Source Code Encodings

:pep:`302`

:pep:`328`

Imports: Multi-Line and Absolute/Relative

:pep:`366`

Main module explicit relative imports

:pep:`420`

Implicit namespace packages

:pep:`451`

A ModuleSpec Type for the Import System

:pep:`488`

Elimination of PYO files

:pep:`489`

Multi-phase extension module initialization

:pep:`552`

Deterministic pycs

Using UTF-8 as the Default Source Encoding

:pep:`3147`

PYC Repository Directories

Functions

.. note::

Programmatic importing of modules should use :func:`import_module`

instead of this function.

.. function:: import_module(name, package=None)

import in absolute or relative terms

(e.g. either ``pkg.mod`` or ``..mod``). If the name is

specified in relative terms, then the *package* argument must be set to

the name of the package which is to act as the anchor for resolving the

derived from :func:`importlib.__import__`. The most important difference

between these two functions is that :func:`import_module` returns the

specified package or module (e.g. ``pkg.mod``), while :func:`__import__`

returns the top-level package or module (e.g. ``pkg``).

If you are dynamically importing a module that was created since the

interpreter began execution (e.g., created a Python source file), you may

need to call :func:`invalidate_caches` in order for the new module to be

noticed by the import system.

If the module cannot be imported, :func:`import_module` will raise

:exc:`ImportError` or an appropriate subclass like

:exc:`ModuleNotFoundError`.

.. versionchanged:: 3.3

Parent packages are automatically imported.

.. function:: invalidate_caches()

Invalidate the internal caches of finders stored at

:data:`sys.meta_path`. If a finder implements ``invalidate_caches()`` then it

will be called to perform the invalidation. This function should be called

if any modules are created/installed while your program is running to

guarantee all finders will notice the new module's existence.

.. versionadded:: 3.3

.. versionchanged:: 3.10

Namespace packages created/installed in a different :data:`sys.path`

location after the same namespace was already imported are noticed.

.. function:: reload(module)

Reload a previously imported *module*. The argument must be a module object,

so it must have been successfully imported before. This is useful if you

have edited the module source file using an external editor and want to try

out the new version without leaving the Python interpreter. The return value

is the module object (which can be different if re-importing causes a

different object to be placed in :data:`sys.modules`).

defining a new set of objects which are bound to names in the module's

dictionary by reusing the :term:`loader` which originally loaded the

module. The ``init`` function of extension modules is not called a second

time.

* As with all other objects in Python the old objects are only reclaimed

after their reference counts drop to zero.

* The names in the module namespace are updated to point to any new or

changed objects.

* Other references to the old objects (such as names external to the module) are

not rebound to refer to the new objects and must be updated in each namespace

where they occur if that is desired.

There are a number of other caveats:

When a module is reloaded, its dictionary (containing the module's global

variables) is retained. Redefinitions of names will override the old

definitions, so this is generally not a problem. If the new version of a

module does not define a name that was defined by the old version, the old

definition remains. This feature can be used to the module's advantage if it

maintains a global table or cache of objects --- with a :keyword:`try`

statement it can test for the table's presence and skip its initialization if

desired::

It is generally not very useful to reload built-in or dynamically loaded

modules. Reloading :mod:`sys`, :mod:`__main__`, :mod:`builtins` and other

key modules is not recommended. In many cases extension modules are not

designed to be initialized more than once, and may fail in arbitrary ways

when reloaded.

If a module imports objects from another module using :keyword:`from` ...

:keyword:`import` ..., calling :func:`reload` for the other module does not

redefine the objects imported from it --- one way around this is to

and qualified names (*module.name*) instead.

If a module instantiates instances of a class, reloading the module that

defines the class does not affect the method definitions of the instances ---

they continue to use the old class definition. The same is true for derived

classes.

.. versionadded:: 3.4

.. versionchanged:: 3.7

:exc:`ModuleNotFoundError` is raised when the module being reloaded lacks

.. warning::

This function is not thread-safe. Calling it from multiple threads can result

in unexpected behavior. It's recommended to use the :class:`threading.Lock`

or other synchronization primitives for thread-safe module reloading.

:mod:`!importlib.abc` -- Abstract base classes related to import

.. module:: importlib.abc

:synopsis: Abstract base classes related to import

**Source code:** :source:`Lib/importlib/abc.py`

used by :keyword:`import`. Some subclasses of the core abstract base classes

are also provided to help in implementing the core ABCs.

ABC hierarchy::

.. versionadded:: 3.3

.. method:: find_spec(fullname, path,>

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

parent package. If a spec cannot be found, ``None`` is returned.

When passed in, ``target`` is a module object that the finder may

:func:`importlib.util.spec_from_loader` may be useful for implementing

concrete ``MetaPathFinders``.

.. versionadded:: 3.4

.. method:: invalidate_caches()

An optional method which, when called, should invalidate any internal

cache used by the finder. Used by :func:`importlib.invalidate_caches`

when invalidating the caches of all finders on :data:`sys.meta_path`.

.. method:: discover(parent=None)

An optional method which searches for possible specs with given *parent*

module spec. If *parent* is *None*, :meth:`MetaPathFinder.discover` will

search for top-level modules.

Returns an iterable of possible specs.

Raises :exc:`ValueError` if *parent* is not a package module.

.. warning::

This method can potentially yield a very large number of objects, and

it may carry out IO operations when computing these values.

values on-the-fly, as they are needed. As such, the returned object is

only guaranteed to be an :class:`iterable <collections.abc.Iterable>`,

instead of a :class:`list` or other

:class:`collection <collections.abc.Collection>` type.

An abstract base class representing a :term:`path entry finder`. Though

it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder``

is meant for use only within the path-based import subsystem provided

.. versionadded:: 3.3

.. method:: find_spec(fullname,>

An abstract method for finding a :term:`spec <module spec>` for

the specified module. The finder will search for the module only

within the :term:`path entry` to which it is assigned. 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. :func:`importlib.util.spec_from_loader`

may be useful for implementing concrete ``PathEntryFinders``.

.. versionadded:: 3.4

.. method:: invalidate_caches()

An optional method which, when called, should invalidate any internal

cache used by the finder. Used by

:meth:`importlib.machinery.PathFinder.invalidate_caches`

.. method:: discover(parent=None)

An optional method which searches for possible specs with given *parent*

module spec. If *parent* is *None*, :meth:`PathEntryFinder.discover` will

search for top-level modules.

Returns an iterable of possible specs.

Raises :exc:`ValueError` if *parent* is not a package module.

.. warning::

This method can potentially yield a very large number of objects, and

it may carry out IO operations when computing these values.

values on-the-fly, as they are needed. As such, the returned object is

only guaranteed to be an :class:`iterable <collections.abc.Iterable>`,

instead of a :class:`list` or other

:class:`collection <collections.abc.Collection>` type.

.. class:: Loader

An abstract base class for a :term:`loader`.

.. versionchanged:: 3.7

.. versionchanged:: 3.15

Removed the ``load_module()`` method.

.. method:: create_module(spec)

A method that returns the module object to use when

importing a module. This method may return ``None``,

indicating that default module creation semantics should take place.

.. versionadded:: 3.4

.. versionchanged:: 3.6

This method is no longer optional when

:meth:`exec_module` is defined.

.. method:: exec_module(module)

An abstract method that executes the module in its own namespace

when a module is imported or reloaded. The module should already

be initialized when :meth:`exec_module` is called. When this method exists,

:meth:`create_module` must be defined.

.. versionadded:: 3.4

.. class:: ResourceLoader

*Superseded by TraversableResources*

An abstract base class for a :term:`loader` which implements the optional

:pep:`302` protocol for loading arbitrary resources from the storage

back-end.

.. deprecated:: 3.7

This ABC is deprecated in favour of supporting resource loading

This class exists for backwards compatibility only with other ABCs in

this module.

.. method:: get_data(path)

:abstractmethod:

An abstract method to return the bytes for the data located at *path*.

Loaders that have a file-like storage back-end

that allows storing arbitrary data

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:`~module.__file__` attribute or an item from a package's

:attr:`~module.__path__`.

.. versionchanged:: 3.4

Raises :exc:`OSError` instead of :exc:`NotImplementedError`.

.. class:: InspectLoader

An abstract base class for a :term:`loader` which implements the optional

:pep:`302` protocol for loaders that inspect modules.

.. method:: get_code(fullname)

Return the code object for a module, or ``None`` if the module does not

have a code object (as would be the case, for example, for a built-in

module). Raise an :exc:`ImportError` if loader cannot find the

requested module.

.. note::

While the method has a default implementation, it is suggested that

it be overridden if possible for performance.

.. index::

single: universal newlines; importlib.abc.InspectLoader.get_source method

.. versionchanged:: 3.4

No longer abstract and a concrete implementation is provided.

.. method:: get_source(fullname)

:abstractmethod:

An abstract method to return the source of a module. It is returned as

a text string using :term:`universal newlines`, translating all

recognized line separators into ``'\n'`` characters. Returns ``None``

if no source is available (e.g. a built-in module). Raises

:exc:`ImportError` if the loader cannot find the module specified.

.. versionchanged:: 3.4

Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.

.. method:: is_package(fullname)

An optional method to return a true value if the module is a package, a

false value otherwise. :exc:`ImportError` is raised if the

:term:`loader` cannot find the module.

.. versionchanged:: 3.4

Raises :exc:`ImportError` instead of :exc:`NotImplementedError`.

Create a code object from Python source.

The *data* argument can be whatever the :func:`compile` function

supports (i.e. string or bytes). The *path* argument should be

the "path" to where the source code originated from, which can be an

abstract concept (e.g. location in a zip file).

With the subsequent code object one can execute it in a module by

running ``exec(code, module.__dict__)``.

The optional argument *fullname* specifies the module name.

It is needed to unambiguous :ref:`filter <warning-filter>` syntax

warnings by module name.

.. versionadded:: 3.4

.. versionchanged:: 3.5

Made the method static.

Added the *fullname* parameter.

.. method:: exec_module(module)

Implementation of :meth:`Loader.exec_module`.

.. versionadded:: 3.4

.. class:: ExecutionLoader

An abstract base class which inherits from :class:`InspectLoader` that,

when implemented, helps a module to be executed as a script. The ABC

represents an optional :pep:`302` protocol.