Source

cpython / Doc / library / importlib.rst

Full commit

:mod:`importlib` -- An implementation of :keyword:`import`

Introduction

The purpose of the :mod:`importlib` package is two-fold. One is to provide an implementation of the :keyword:`import` statement (and thus, by extension, the :func:`__import__` function) in Python source code. This provides an implementation of :keyword:`import` which is portable to any Python interpreter. This also provides a reference implementation which is easier to comprehend than one implemented in a programming language other than Python.

Two, the components to implement :keyword:`import` are exposed in this package, making it easier for users to create their own custom objects (known generically as an :term:`importer`) to participate in the import process. Details on custom importers can be found in PEP 302.

Functions

:mod:`importlib.machinery` -- Importers and path hooks

This module contains the various objects that help :keyword:`import` find and load modules.

An :term:`importer` for built-in modules. All known built-in modules are listed in :data:`sys.builtin_module_names`. This class implements the :class:`importlib.abc.MetaPathFinder` and :class:`importlib.abc.InspectLoader` ABCs.

Only class methods are defined by this class to alleviate the need for instantiation.

An :term:`importer` for frozen modules. This class implements the :class:`importlib.abc.MetaPathFinder` and :class:`importlib.abc.InspectLoader` ABCs.

Only class methods are defined by this class to alleviate the need for instantiation.

:term:`Finder` for modules declared in the Windows registry. This class implements the :class:`importlib.abc.Finder` ABC.

Only class methods are defined by this class to alleviate the need for instantiation.

A :term:`Finder` for :data:`sys.path` and package __path__ attributes. This class implements the :class:`importlib.abc.MetaPathFinder` ABC.

Only class methods are defined by this class to alleviate the need for instantiation.

A concrete implementation of :class:`importlib.abc.PathEntryFinder` which caches results from the file system.

The path argument is the directory for which the finder is in charge of searching.

The loader_details argument is a variable number of 2-item tuples each containing a loader and a sequence of file suffixes the loader recognizes.

The finder will cache the directory contents as necessary, making stat calls for each module search to verify the cache is not outdated. Because cache staleness relies upon the granularity of the operating system's state information of the file system, there is a potential race condition of searching for a module, creating a new file, and then searching for the module the new file represents. If the operations happen fast enough to fit within the granularity of stat calls, then the module search will fail. To prevent this from happening, when you create a module dynamically, make sure to call :func:`importlib.invalidate_caches`.

A concrete implementation of :class:`importlib.abc.SourceLoader` by subclassing :class:`importlib.abc.FileLoader` and providing some concrete implementations of other methods.

A concrete implementation of :class:`importlib.abc.FileLoader` which can import bytecode files (i.e. no source code files exist).

Please note that direct use of bytecode files (and thus not source code files) inhibits your modules from being usable by all Python implementations or new versions of Python which change the bytecode format.

A concrete implementation of :class:`importlib.abc.InspectLoader` for extension modules.

The fullname argument specifies the name of the module the loader is to support. The path argument is the path to the extension module's file.

:mod:`importlib.util` -- Utility code for importers

This module contains the various objects that help in the construction of an :term:`importer`.