### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1a1 documentation »
- The Python Standard Library »
- Importing Modules »

# `importlib` – An implementation of `import`

New in version 3.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 implementaiton of `import` which is portable to any Python interpreter. This also provides a reference implementation which is easier to comprehend than one in a programming language other than Python.

Two, the components to implement `import` can be 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 providing custom importers can be found in PEP 302.

See also

The import statement
  The language reference for the `import` statement.
Packages specification
  Original specification of packages. Some semantics have changed since the writing of this document (e.g. redirecting based on `None` in `sys.modules`).
The `__import__()` function
  The built-in function for which the `import` statement is syntactic sugar for.
PEP 235
  Import on Case-Insensitive Platforms
PEP 263
  Defining Python Source Code Encodings
PEP 302
  New Import Hooks.
PEP 328
  Imports: Multi-Line and Absolute/Relative
PEP 366
  Main module explicit relative imports
PEP 3128
  Using UTF-8 as the Default Source Encoding

## Functions

`importlib.``__import__`(name, globals={}, locals={}, fromlist=list(), level=0)
  An implementation of the built-in `__import__()` function. See the built-in function’s documentation for usage instructions.

`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 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 `__import__()`. This means all semantics of the function are derived from `__import__()`, including requiring the package where an import is occuring from to already be imported (i.e., package must already be imported).

## `importlib.machinery` – Importers and path hooks

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

class `importlib.machinery.``BuiltinImporter`

  Importer for built-in modules. All known built-in modules are listed in `sys.builtin_module_names`.

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

  classmethod `find_module`(fullname, path=None)
    Class method that allows this class to be a finder for built-in modules.
  classmethod `load_module`(fullname)
    Class method that allows this class to be a loader for built-in modules.

class `importlib.machinery.``FrozenImporter`

  Importer for frozen modules.

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

  classmethod `find_module`(fullname, path=None)
    Class method that allows this class to be a finder for frozen modules.
  classmethod `load_module`(fullname)
    Class method that allows this class to be a loader for frozen modules.

class `importlib.machinery.``PathFinder`

  Finder for `sys.path`.

  This class does not perfectly mirror the semantics of `import` in terms of `sys.path`. No implicit path hooks are assumed for simplification of the class and its semantics.

  Only class method 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 either on `sys.path` or, if defined, on path. For each path entry that is searched, `sys.path_importer_cache` is checked. If an non-false object is found then it is used as the finder to query for the module being searched for. For 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.

## `importlib.util` – Utility code for importers

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

`importlib.util.``module_for_loader`(method)

  A decorator for a loader which handles selecting the proper module object to load with. The decorated method is expected to have a call signature of `method(self, module_object)` 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. Otherwise 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 what module object a loader should initialize as specified by PEP 302.

`importlib.util.``set_package`(method)
  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`.

### Navigation

- index
- modules |
- next |
- previous |
- Python v3.1a1 documentation »
- The Python Standard Library »
- Importing Modules »