29.6. importlib – An implementation of import — Python v3.1.5 documentation

29.6. importlib – An implementation of import — Python v3.1.5 documentation
index
modules
next
previous
Python v3.1.5 documentation
The Python Standard Library
29. Importing Modules
29.6.
importlib
– An implementation of
import
New in version 3.1.
29.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 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.
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 3120
Using UTF-8 as the Default Source Encoding
29.6.2. 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 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
).
29.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.
class
importlib.abc.
Finder
An abstract base class representing a
finder
See
PEP 302
for the exact definition for a finder.
find_module
fullname
path=None
An abstract method for finding a
loader
for the specified
module. If the
finder
is found on
sys.meta_path
and the
module to be searched for is a subpackage or module then
path
will
be the value of
__path__
from the parent package. If a loader
cannot be found,
None
is returned.
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).
__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.)
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 with universal newlines. 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.
PyLoader
An abstract base class inheriting from
importlib.abc.InspectLoader
and
importlib.abc.ResourceLoader
designed to ease the loading of
Python source modules (bytecode is not handled; see
importlib.abc.PyPycLoader
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.
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.
ImportError
if the module cannot be found.
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()
), converting it to standard
newlines, 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
importlib.abc.PyLoader
This ABC is meant to help in creating loaders that support both Python
source and bytecode.
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 module is not found.
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.
29.6.4.
importlib.machinery
– Importers and path hooks
This module contains the various objects that help
import
find and load modules.
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.Finder
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.Finder
and
importlib.abc.InspectLoader
ABCs.
Only class methods are defined by this class to alleviate the need for
instantiation.
class
importlib.machinery.
PathFinder
Finder
for
sys.path
. This class implements the
importlib.abc.Finder
ABC.
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
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 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 returned.
29.6.5.
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
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. 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 which module object a
loader should initialize as specified by
PEP 302
importlib.util.
set_loader
fxn
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 is what
__loader__
should be set to.
importlib.util.
set_package
fxn
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 the execution of the code is possible. By
setting it before the code for the module is executed it allows the
attribute to be used at the global level of the module during
initialization.
29.6.6. Example
Below is an example meta path importer that uses a dict for back-end storage
for source code. While not an optimal solution – manipulations of
__path__
on packages does not influence import – it does illustrate
what little is required to implement an importer.
"""An importer where source is stored in a dict."""
from
importlib
import
abc
class
DictImporter
abc
Finder
abc
PyLoader
):
"""A meta path importer that stores source code in a dict.
The keys are the module names -- packages must end in ``.__init__``.
The values must be something that can be passed to 'bytes'.
"""
def
__init__
self
memory
):
"""Store the dict."""
self
memory
memory
def
contains
self
name
):
"""See if a module or package is in the dict."""
if
name
in
self
memory
return
name
package_name
'{}.__init__'
format
name
if
package_name
in
self
memory
return
package_name
return
False
__contains__
contains
# Convenience.
def
find_module
self
fullname
path
None
):
"""Find the module in the dict."""
if
fullname
in
self
return
self
return
None
def
source_path
self
fullname
):
"""Return the module name if the module is in the dict."""
if
not
fullname
in
self
raise
ImportError
return
fullname
def
get_data
self
path
):
"""Return the bytes for the source.
The value found in the dict is passed through 'bytes' before being
returned.
"""
name
self
contains
path
if
not
name
raise
IOError
return
bytes
self
memory
name
])
def
is_package
self
fullname
):
"""Tell if module is a package based on whether the dict contains the
name with ``.__init__`` appended to it."""
if
fullname
not
in
self
raise
ImportError
if
fullname
in
self
memory
return
False
# If name is in this importer but not as it is then it must end in
# ``__init__``.
else
return
True
Table Of Contents
29.6.
importlib
– An implementation of
import
29.6.1. Introduction
29.6.2. Functions
29.6.3.
importlib.abc
– Abstract base classes related to import
29.6.4.
importlib.machinery
– Importers and path hooks
29.6.5.
importlib.util
– Utility code for importers
29.6.6. Example
Previous topic
29.5.
runpy
— Locating and executing Python modules
Next topic
30. Python Language Services
This Page
Report a Bug
Show Source
Quick search
Enter search terms or a module, class or function name.
index
modules
next
previous
Python v3.1.5 documentation
The Python Standard Library
29. Importing Modules
1990-2012, Python Software Foundation.
The Python Software Foundation is a non-profit corporation.
Please donate.
Found a bug
Created using
Sphinx
0.6.5.