
``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``.
