diff options
author | Brett Cannon <bcannon@gmail.com> | 2009-03-09 03:35:50 (GMT) |
---|---|---|
committer | Brett Cannon <bcannon@gmail.com> | 2009-03-09 03:35:50 (GMT) |
commit | 2a922ed6adf28fabd10cb852133be5aeeb906aa5 (patch) | |
tree | 233b1352e48970174dade4ca795d853b8cc6e501 /Doc | |
parent | aa1c8d88992d482f90268f2352fccb6e74d87279 (diff) | |
download | cpython-2a922ed6adf28fabd10cb852133be5aeeb906aa5.zip cpython-2a922ed6adf28fabd10cb852133be5aeeb906aa5.tar.gz cpython-2a922ed6adf28fabd10cb852133be5aeeb906aa5.tar.bz2 |
Introduce importlib.abc. The module contains various ABCs related to imports
(mostly stuff specified by PEP 302). There are two ABCs, PyLoader and
PyPycLoader, which help with implementing source and source/bytecode loaders by
implementing load_module in terms of other methods. This removes a lot of
gritty details loaders typically have to worry about.
Diffstat (limited to 'Doc')
-rw-r--r-- | Doc/library/importlib.rst | 215 |
1 files changed, 184 insertions, 31 deletions
diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 1481302..eb9fd00 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -82,6 +82,175 @@ Functions occuring from to already be imported (i.e., *package* must already be imported). +:mod:`importlib.abc` -- Abstract base classes related to import +--------------------------------------------------------------- + +.. module:: importlib.abc + :synopsis: Abstract base classes related to import + +The :mod:`importlib.abc` module contains all of the core abstract base classes +used by :keyword:`import`. Some subclasses of the core abstract base classes +are also provided to help in implementing the core ABCs. + + +.. class:: Finder + + An abstract base class representing a :term:`finder`. + + ..method:: find_module(fullname, path=None) + + An abstract method for finding a :term:`loader` for the specified + module. If the :term:`finder` is found on :data:`sys.meta_path` and the + module to be searched for is a subpackage or module then *path* is set + to the value of :attr:`__path__` from the parent package. If a loader + cannot be found, :keyword:`None` is returned. + + The exact definition of a :term:`finder` can be found in :pep:`302`. + + +.. class:: Loader + + An abstract base class for a :term:`loader`. + + ..method:: load_module(fullname) + + An abstract method for loading a module. If the module cannot be + loaded, :exc:`ImportError` is raised, otherwise the loaded module is + returned. + + If the requested module is already exists in :data:`sys.modules`, that + module should be used and reloaded. + Otherwise a new module is to be created by the loader and inserted into + :data:`sys.modules`before any loading begins to prevent recursion from + the import. If the loader inserted into a module and the load fails it + must be removed by the loader from :data:`sys.modules`; modules already + in :data:`sys.modules` before the loader began execution should be left + alone. The :func:`importlib.util.module_for_loader` decorator handles + all of these details. + + The loader is expected to set several attributes on the module when + adding a new module to :data:`sys.modules`. + + - :attr:`__name__` + The name of the module. + + - :attr:`__file__` + The path to where the module data is stored (not set for built-in + modules). + + - :attr:`__path__` + Set to a list of strings specifying the search path within a + package. This attribute is not set on modules. + + - :attr:`__package__` + The parent package for the module/package. If the module is + top-level then it has a value of the empty string. The + :func:`importlib.util.set_package` decorator can handle the details + for :attr:`__package__`. + + - :attr:`__loader__` + Set to the loader used to load the module. + + See :pep:`302` for the exact definition for a loader. + + +.. class:: ResourceLoader + + An abstract base class for a :term:`loader` which implements the optional + :pep:`302` protocol for loading arbitrary resources from the storage + back-end. + + ..method:: 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 can implement this + abstract method to give direct access + to the data stored. :exc:`IOError` is to be raised if the *path* cannot + be found. The *path* is expected to be constructed using a module's + :attr:`__path__` attribute or an item from :attr:`__path__`. + + +.. class:: InspectLoader + + An abstract base class for a :term:`loader` which implements the optional + :pep:`302` protocol for loaders which inspect modules. + + ..method:: is_package(fullname) + + An abstract method to return a true value if the module is a package, a + false value otherwise. :exc:`ImportError` is raised if the + :term:`loader` cannot find the module. + + ..method:: get_source(fullname) + + An abstract method to return the source of a module. It is returned as + a string with universal newline support. Returns :keyword:`None` if no + source is available (e.g. a built-in module). Raises :exc:`ImportError` + if the loader cannot find the module specified. + + ..method:: get_code(fullname) + + An abstract method to return the :class:`code` object for a module. + :keyword:`None` is returned if the module does not have a code object + (e.g. built-in module). :exc:`ImportError` is raised if loader cannot + find the requested module. + + +.. class:: PyLoader + + An abstract base class inheriting from :class:`importlib.abc.InspectLoader` + and :class:`importlib.abc.ResourceLoader` designed to ease the loading of + Python source modules (bytecode is not handled; see + :class:`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. + + ..method:: source_path(fullname) + + An abstract method that returns the path to the source code for a + module. Should return :keyword:`None` if there is no source code. + :exc:`ImportError` if the module cannot be found. + + ..method:: load_module(fullname) + + A concrete implementation of :meth:`importlib.abc.Loader.load_module` + that loads Python source code. + + ..method:: get_code(fullname) + + A concrete implementation of + :meth:`importlib.abc.InspectLoader.get_code` that creates code objects + from Python source code. + + +.. class:: PyPycLoader + + An abstract base class inheriting from :class:`importlib.abc.PyLoader`. + This ABC is meant to help in creating loaders that support both Python + source and bytecode. + + ..method:: 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 :keyword:`None. If the + module cannot be found then :exc:`ImportError` is raised. + + ..method:: bytecode_path(fullname) + + An abstract method which returns the path to the bytecode for the + specified module. :keyword:`None` is returned if there is no bytecode. + :exc:`ImportError` is raised if the module is not found. + + ..method:: write_bytecode(fullname, bytecode) + + An abstract method which has the loader write *bytecode* for future + use. If the bytecode is written, return :keyword:`True`. Return + :keyword:`False` if the bytecode could not be written. This method + should not be called if :data:`sys.dont_write_bytecode` is true. + + :mod:`importlib.machinery` -- Importers and path hooks ------------------------------------------------------ @@ -93,44 +262,27 @@ find and load modules. .. class:: BuiltinImporter - :term:`Importer` for built-in modules. All known built-in modules are - listed in :data:`sys.builtin_module_names`. + 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.Finder` and :class:`importlib.abc.Loader` ABCs. 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 :term:`finder` for built-in - modules. - - .. classmethod:: load_module(fullname) - - Class method that allows this class to be a :term:`loader` for built-in - modules. - .. class:: FrozenImporter - :term:`Importer` for frozen modules. + An :term:`importer` for frozen modules. This class implements the + :class:`importlib.abc.Finder` and :class:`importlib.abc.Loader` ABCs. 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 :term:`finder` for frozen - modules. - - .. classmethod:: load_module(fullname) - - Class method that allows this class to be a :term:`loader` for frozen - modules. - .. class:: PathFinder - :term:`Finder` for :data:`sys.path`. + :term:`Finder` for :data:`sys.path`. This class implements the + :class:`importlib.abc.Finder` ABC. This class does not perfectly mirror the semantics of :keyword:`import` in terms of :data:`sys.path`. No implicit path hooks are assumed for @@ -142,15 +294,15 @@ find and load modules. .. classmethod:: find_module(fullname, path=None) Class method that attempts to find a :term:`loader` for the module - specified by *fullname* either on :data:`sys.path` or, if defined, on + specified by *fullname* on :data:`sys.path` or, if defined, on *path*. For each path entry that is searched, :data:`sys.path_importer_cache` is checked. If an non-false object is - found then it is used as the :term:`finder` to query for the module - being searched for. For no entry is found in + found then it is used as the :term:`finder` to look for the module + being searched for. If no entry is found in :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is searched for a finder for the path entry and, if found, is stored in :data:`sys.path_importer_cache` along with being queried about the - module. + module. If no finder is ever found then :keyword:`None` is returned. :mod:`importlib.util` -- Utility code for importers @@ -166,10 +318,11 @@ an :term:`importer`. A :term:`decorator` for a :term:`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 + 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). + arguments. The decorated method will take in the name of the module to be loaded as expected for a :term:`loader`. If the module is not found in |