30.6.1. Introduction

The purpose of the importlib package is two-fold. One is to provide an implementation of the import statement (and thus, by extension, the __import__() function) in Python source code. This provides an implementation of 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 import are exposed in this package, making it easier for users to create their own custom objects (known generically as an importer) to participate in the import process. Details on custom importers can be found in PEP 302.

30.6.2. Functions

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)

An implementation of the built-in __import__() function.

importlib.import_module(name, package=None)

Import a module. The name argument specifies what module to 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 package name (e.g. import_module('..mod', 'pkg.subpkg') will import pkg.mod).

The import_module() function acts as a simplifying wrapper around importlib.__import__(). This means all semantics of the function are derived from importlib.__import__(), including requiring the package from which an import is occurring to have been previously imported (i.e., package must already be imported). The most important difference is that import_module() returns the most nested package or module that was imported (e.g. pkg.mod), while __import__() returns the top-level package or module (e.g. pkg).

importlib.find_loader(name, path=None)

Find the loader for a module, optionally within the specified path. If the module is in sys.modules, then sys.modules[name].__loader__ is returned (unless the loader would be None, in which case ValueError is raised). Otherwise a search using sys.meta_path is done. None is returned if no loader is found.

A dotted name does not have its parent’s implicitly imported as that requires loading them and that may not be desired. To properly import a submodule you will need to import all parent packages of the submodule and use the correct argument to path.

importlib.invalidate_caches()

Invalidate the internal caches of finders stored at 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.

New in version 3.3.

30.6.3. importlib.abc – Abstract base classes related to import

The importlib.abc module contains all of the core abstract base classes used by import. Some subclasses of the core abstract base classes are also provided to help in implementing the core ABCs.

ABC hierarchy:

object
 +-- Finder (deprecated)
 |    +-- MetaPathFinder
 |    +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader
                                      +-- PyLoader (deprecated)
                                      +-- PyPycLoader (deprecated)

class importlib.abc.Finder

An abstract base class representing a finder.

Deprecated since version 3.3: Use MetaPathFinder or PathEntryFinder instead.

find_module(fullname, path=None)

An abstact method for finding a loader for the specified module. Originally specified in PEP 302, this method was meant for use in sys.meta_path and in the path-based import subsystem.

class importlib.abc.MetaPathFinder

An abstract base class representing a meta path finder. For compatibility, this is a subclass of Finder.

New in version 3.3.

find_module(fullname, path)

An abstract method for finding a loader 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 __path__ from the parent package. If a loader cannot be found, None is returned.

invalidate_caches()

An optional method which, when called, should invalidate any internal cache used by the finder. Used by importlib.invalidate_caches() when invalidating the caches of all finders on sys.meta_path.

class importlib.abc.PathEntryFinder

An abstract base class representing a path entry finder. Though it bears some similarities to MetaPathFinder, PathEntryFinder is meant for use only within the path-based import subsystem provided by PathFinder. This ABC is a subclass of Finder for compatibility.

New in version 3.3.

find_loader(fullname)

An abstract method for finding a loader for the specified module. Returns a 2-tuple of (loader, portion) where portion is a sequence of file system locations contributing to part of a namespace package. The loader may be None while specifying portion to signify the contribution of the file system locations to a namespace package. An empty list can be used for portion to signify the loader is not part of a package. If loader is None and portion is the empty list then no loader or location for a namespace package were found (i.e. failure to find anything for the module).

find_module(fullname)

A concrete implementation of Finder.find_module() which is equivalent to self.find_loader(fullname)[0].

invalidate_caches()

An optional method which, when called, should invalidate any internal cache used by the finder. Used by PathFinder.invalidate_caches() when invalidating the caches of all cached finders.

class importlib.abc.Loader

An abstract base class for a loader. See PEP 302 for the exact definition for a loader.

load_module(fullname)

An abstract method for loading a module. If the module cannot be loaded, ImportError is raised, otherwise the loaded module is returned.

If the requested module already exists in sys.modules, that module should be used and reloaded. Otherwise the loader should create a new module and insert it into sys.modules before any loading begins, to prevent recursion from the import. If the loader inserted a module and the load fails, it must be removed by the loader from sys.modules; modules already in sys.modules before the loader began execution should be left alone. The importlib.util.module_for_loader() decorator handles all of these details.

The loader should set several attributes on the module. (Note that some of these attributes can change when a module is reloaded.)

• __name__

  The name of the module.

• __file__

  The path to where the module data is stored (not set for built-in modules).

• __cached__

  The path to where a compiled version of the module is/should be stored (not set when the attribute would be inappropriate).

• __path__

  A list of strings specifying the search path within a package. This attribute is not set on modules.

• __package__

  The parent package for the module/package. If the module is top-level then it has a value of the empty string. The importlib.util.set_package() decorator can handle the details for __package__.

• __loader__

  The loader used to load the module. (This is not set by the built-in import machinery, but it should be set whenever a loader is used.)

module_repr(module)

An abstract method which when implemented calculates and returns the given module’s repr, as a string.

class importlib.abc.ResourceLoader

An abstract base class for a loader which implements the optional PEP 302 protocol for loading arbitrary resources from the storage back-end.

get_data(path)

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. IOError is to be raised if the path cannot be found. The path is expected to be constructed using a module’s __file__ attribute or an item from a package’s __path__.

class importlib.abc.InspectLoader

An abstract base class for a loader which implements the optional PEP 302 protocol for loaders that inspect modules.

get_code(fullname)

An abstract method to return the code object for a module. None is returned if the module does not have a code object (e.g. built-in module). ImportError is raised if loader cannot find the requested module.

get_source(fullname)

An abstract method to return the source of a module. It is returned as a text string using universal newlines, translating all recognized line separators into '\n' characters. Returns None if no source is available (e.g. a built-in module). Raises ImportError if the loader cannot find the module specified.

is_package(fullname)

An abstract method to return a true value if the module is a package, a false value otherwise. ImportError is raised if the loader cannot find the module.

class importlib.abc.ExecutionLoader

An abstract base class which inherits from InspectLoader that, when implemented, helps a module to be executed as a script. The ABC represents an optional PEP 302 protocol.

get_filename(fullname)

An abstract method that is to return the value of __file__ for the specified module. If no path is available, 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 module.

class importlib.abc.FileLoader(fullname, path)

An abstract base class which inherits from ResourceLoader and ExecutionLoader, providing concrete implementations of ResourceLoader.get_data() and ExecutionLoader.get_filename().

The fullname argument is a fully resolved name of the module the loader is to handle. The path argument is the path to the file for the module.

New in version 3.3.

name

The name of the module the loader can handle.

path

Path to the file of the module.

load_module(fullname)

Calls super’s load_module().

get_filename(fullname)

Returns path.

get_data(path)

Returns the open, binary file for path.

class importlib.abc.SourceLoader

An abstract base class for implementing source (and optionally bytecode) file loading. The class inherits from both ResourceLoader and ExecutionLoader, requiring the implementation of:

• ResourceLoader.get_data()

• ExecutionLoader.get_filename()

  Should only return the path to the source file; sourceless loading is not supported.

The abstract methods defined by this class are to add optional bytecode file support. Not implementing these optional methods causes the loader to only work with source code. Implementing the methods allows the loader to work with source and bytecode files; it does not allow for sourceless loading where only bytecode is provided. Bytecode files are an optimization to speed up loading by removing the parsing step of Python’s compiler, and so no bytecode-specific API is exposed.

path_stats(path)

Optional abstract method which returns a dict containing metadata about the specifed path. Supported dictionary keys are:

• 'mtime' (mandatory): an integer or floating-point number representing the modification time of the source code;
• 'size' (optional): the size in bytes of the source code.

Any other keys in the dictionary are ignored, to allow for future extensions.

New in version 3.3.

path_mtime(path)

Optional abstract method which returns the modification time for the specified path.

Deprecated since version 3.3: This method is deprecated in favour of path_stats(). You don’t have to implement it, but it is still available for compatibility purposes.

set_data(path, data)

Optional abstract method which writes the specified bytes to a file path. Any intermediate directories which do not exist are to be created automatically.

When writing to the path fails because the path is read-only (errno.EACCES/PermissionError), do not propagate the exception.

get_code(fullname)

Concrete implementation of InspectLoader.get_code().

load_module(fullname)

Concrete implementation of Loader.load_module().

get_source(fullname)

Concrete implementation of InspectLoader.get_source().

is_package(fullname)

Concrete implementation of InspectLoader.is_package(). A module is determined to be a package if its file path (as provided by ExecutionLoader.get_filename()) is a file named __init__ when the file extension is removed and the module name itself does not end in __init__.

class importlib.abc.PyLoader

An abstract base class inheriting from ExecutionLoader and ResourceLoader designed to ease the loading of Python source modules (bytecode is not handled; see SourceLoader for a source/bytecode ABC). A subclass implementing this ABC will only need to worry about exposing how the source code is stored; all other details for loading Python source code will be handled by the concrete implementations of key methods.

Deprecated since version 3.2: This class has been deprecated in favor of SourceLoader and is slated for removal in Python 3.4. See below for how to create a subclass that is compatible with Python 3.1 onwards.

If compatibility with Python 3.1 is required, then use the following idiom to implement a subclass that will work with Python 3.1 onwards (make sure to implement ExecutionLoader.get_filename()):

try:
    from importlib.abc import SourceLoader
except ImportError:
    from importlib.abc import PyLoader as SourceLoader


class CustomLoader(SourceLoader):
    def get_filename(self, fullname):
        """Return the path to the source file."""
        # Implement ...

    def source_path(self, fullname):
        """Implement source_path in terms of get_filename."""
        try:
            return self.get_filename(fullname)
        except ImportError:
            return None

    def is_package(self, fullname):
        """Implement is_package by looking for an __init__ file
        name as returned by get_filename."""
        filename = os.path.basename(self.get_filename(fullname))
        return os.path.splitext(filename)[0] == '__init__'

source_path(fullname)

An abstract method that returns the path to the source code for a module. Should return None if there is no source code. Raises ImportError if the loader knows it cannot handle the module.

get_filename(fullname)

A concrete implementation of importlib.abc.ExecutionLoader.get_filename() that relies on source_path(). If source_path() returns None, then ImportError is raised.

load_module(fullname)

A concrete implementation of importlib.abc.Loader.load_module() that loads Python source code. All needed information comes from the abstract methods required by this ABC. The only pertinent assumption made by this method is that when loading a package __path__ is set to [os.path.dirname(__file__)].

get_code(fullname)

A concrete implementation of importlib.abc.InspectLoader.get_code() that creates code objects from Python source code, by requesting the source code (using source_path() and get_data()) and compiling it with the built-in compile() function.

get_source(fullname)

A concrete implementation of importlib.abc.InspectLoader.get_source(). Uses importlib.abc.ResourceLoader.get_data() and source_path() to get the source code. It tries to guess the source encoding using tokenize.detect_encoding().

class importlib.abc.PyPycLoader

An abstract base class inheriting from PyLoader. This ABC is meant to help in creating loaders that support both Python source and bytecode.

Deprecated since version 3.2: This class has been deprecated in favor of SourceLoader and to properly support PEP 3147. If compatibility is required with Python 3.1, implement both SourceLoader and PyLoader; instructions on how to do so are included in the documentation for PyLoader. Do note that this solution will not support sourceless/bytecode-only loading; only source and bytecode loading.

Changed in version 3.3: Updated to parse (but not use) the new source size field in bytecode files when reading and to write out the field properly when writing.

source_mtime(fullname)

An abstract method which returns the modification time for the source code of the specified module. The modification time should be an integer. If there is no source code, return None. If the module cannot be found then ImportError is raised.

bytecode_path(fullname)

An abstract method which returns the path to the bytecode for the specified module, if it exists. It returns None if no bytecode exists (yet). Raises ImportError if the loader knows it cannot handle the module.

get_filename(fullname)

A concrete implementation of ExecutionLoader.get_filename() that relies on PyLoader.source_path() and bytecode_path(). If source_path() returns a path, then that value is returned. Else if bytecode_path() returns a path, that path will be returned. If a path is not available from both methods, ImportError is raised.

write_bytecode(fullname, bytecode)

An abstract method which has the loader write bytecode for future use. If the bytecode is written, return True. Return False if the bytecode could not be written. This method should not be called if sys.dont_write_bytecode is true. The bytecode argument should be a bytes string or bytes array.

30.6.4. importlib.machinery – Importers and path hooks

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

importlib.machinery.SOURCE_SUFFIXES

A list of strings representing the recognized file suffixes for source modules.

New in version 3.3.

importlib.machinery.DEBUG_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for non-optimized bytecode modules.

New in version 3.3.

importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES

A list of strings representing the file suffixes for optimized bytecode modules.

New in version 3.3.

importlib.machinery.BYTECODE_SUFFIXES

A list of strings representing the recognized file suffixes for bytecode modules. Set to either DEBUG_BYTECODE_SUFFIXES or OPTIMIZED_BYTECODE_SUFFIXES based on whether __debug__ is true.

New in version 3.3.

importlib.machinery.EXTENSION_SUFFIXES

A list of strings representing the recognized file suffixes for extension modules.

New in version 3.3.

importlib.machinery.all_suffixes()

Returns a combined list of strings representing all file suffixes for modules recognized by the standard import machinery. This is a helper for code which simply needs to know if a filesystem path potentially refers to a module without needing any details on the kind of module (for example, inspect.getmodulename())

New in version 3.3.

class importlib.machinery.BuiltinImporter

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

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

class importlib.machinery.FrozenImporter

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

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

class importlib.machinery.WindowsRegistryFinder

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

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

New in version 3.3.

class importlib.machinery.PathFinder

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

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

classmethod find_module(fullname, path=None)

Class method that attempts to find a loader for the module specified by fullname on sys.path or, if defined, on path. For each path entry that is searched, sys.path_importer_cache is checked. If a non-false object is found then it is used as the path entry finder to look for the module being searched for. If no entry is found in sys.path_importer_cache, then sys.path_hooks is searched for a finder for the path entry and, if found, is stored in sys.path_importer_cache along with being queried about the module. If no finder is ever found then None is both stored in the cache and returned.

classmethod invalidate_caches()

Calls importlib.abc.PathEntryFinder.invalidate_caches() on all finders stored in sys.path_importer_cache.

class importlib.machinery.FileFinder(path, *loader_details)

A concrete implementation of 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 loaders are expected to be callables which accept two arguments of the module’s name and the path to the file found.

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 importlib.invalidate_caches().

New in version 3.3.

path

The path the finder will search in.

find_loader(fullname)

Attempt to find the loader to handle fullname within path.

invalidate_caches()

Clear out the internal cache.

classmethod path_hook(*loader_details)

A class method which returns a closure for use on sys.path_hooks. An instance of FileFinder is returned by the closure using the path argument given to the closure directly and loader_details indirectly.

If the argument to the closure is not an existing directory, ImportError is raised.

class importlib.machinery.SourceFileLoader(fullname, path)

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

New in version 3.3.

name

The name of the module that this loader will handle.

path

The path to the source file.

is_package(fullname)

Return true if path appears to be for a package.

path_stats(path)

Concrete implementation of importlib.abc.SourceLoader.path_stats().

set_data(path, data)

Concrete implementation of importlib.abc.SourceLoader.set_data().

class importlib.machinery.SourcelessFileLoader(fullname, path)

A concrete implementation of 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.

New in version 3.3.

name

The name of the module the loader will handle.

path

The path to the bytecode file.

is_package(fullname)

Determines if the module is a package based on path.

get_code(fullname)

Returns the code object for name created from path.

get_source(fullname)

Returns None as bytecode files have no source when this loader is used.

class importlib.machinery.ExtensionFileLoader(fullname, path)

A concrete implementation of 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.

New in version 3.3.

name

Name of the module the loader supports.

path

Path to the extension module.

load_module(fullname)

Loads the extension module if and only if fullname is the same as name or is None.

is_package(fullname)

Returns True if the file path points to a package’s __init__ module based on EXTENSION_SUFFIXES.

get_code(fullname)

Returns None as extension modules lack a code object.

get_source(fullname)

Returns None as extension modules do not have source code.

30.6.5. importlib.util – Utility code for importers

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

importlib.util.resolve_name(name, package)

Resolve a relative module name to an absolute one.

If name has no leading dots, then name is simply returned. This allows for usage such as importlib.util.resolve_name('sys', __package__) without doing a check to see if the package argument is needed.

ValueError is raised if name is a relative module name but package is a false value (e.g. None or the empty string). ValueError is also raised a relative name would escape its containing package (e.g. requesting ..bacon from within the spam package).

New in version 3.3.

@importlib.util.module_for_loader

A decorator for a loader method, to handle selecting the proper module object to load with. The decorated method is expected to have a call signature taking two positional arguments (e.g. load_module(self, module)) for which the second argument will be the module object to be used by the loader. Note that the decorator will not work on static methods because of the assumption of two arguments.

The decorated method will take in the name of the module to be loaded as expected for a loader. If the module is not found in sys.modules then a new one is constructed with its __name__ attribute set to name, __loader__ set to self, and __package__ set if importlib.abc.InspectLoader.is_package() is defined for self and does not raise ImportError for name. If a new module is not needed then the module found in sys.modules will be passed into the method.

If an exception is raised by the decorated method and a module was added to sys.modules it will be removed to prevent a partially initialized module from being in left in sys.modules. If the module was already in sys.modules then it is left alone.

Use of this decorator handles all the details of which module object a loader should initialize as specified by PEP 302 as best as possible.

Changed in version 3.3: __loader__ and __package__ are automatically set (when possible).

@importlib.util.set_loader

A decorator for a loader method, to set the __loader__ attribute on loaded modules. If the attribute is already set the decorator does nothing. It is assumed that the first positional argument to the wrapped method (i.e. self) is what __loader__ should be set to.

Note

It is recommended that module_for_loader() be used over this decorator as it subsumes this functionality.

@importlib.util.set_package

A decorator for a loader to set the __package__ attribute on the module returned by the loader. If __package__ is set and has a value other than None it will not be changed. Note that the module returned by the loader is what has the attribute set on and not the module found in sys.modules.

Reliance on this decorator is discouraged when it is possible to set __package__ before importing. By setting it beforehand the code for the module is executed with the attribute set and thus can be used by global level code during initialization.

Note

It is recommended that module_for_loader() be used over this decorator as it subsumes this functionality.