diff options
Diffstat (limited to 'Doc/library/pkgutil.rst')
| -rw-r--r-- | Doc/library/pkgutil.rst | 85 |
1 files changed, 56 insertions, 29 deletions
diff --git a/Doc/library/pkgutil.rst b/Doc/library/pkgutil.rst index 3118ff2..22d44eb 100644 --- a/Doc/library/pkgutil.rst +++ b/Doc/library/pkgutil.rst @@ -56,21 +56,32 @@ support. Note that :class:`ImpImporter` does not currently support being used by placement on :data:`sys.meta_path`. + .. deprecated:: 3.3 + This emulation is no longer needed, as the standard import mechanism + is now fully PEP 302 compliant and available in :mod:`importlib` + .. class:: ImpLoader(fullname, file, filename, etc) :pep:`302` Loader that wraps Python's "classic" import algorithm. + .. deprecated:: 3.3 + This emulation is no longer needed, as the standard import mechanism + is now fully PEP 302 compliant and available in :mod:`importlib` + .. function:: find_loader(fullname) - Find a :pep:`302` "loader" object for *fullname*. + Retrieve a :pep:`302` module loader for the given *fullname*. - If *fullname* contains dots, path must be the containing package's - ``__path__``. Returns ``None`` if the module cannot be found or imported. - This function uses :func:`iter_importers`, and is thus subject to the same - limitations regarding platform-specific special import locations such as the - Windows registry. + This is a convenience wrapper around :func:`importlib.find_loader` that + sets the *path* argument correctly when searching for submodules, and + also ensures parent packages (if any) are imported before searching for + submodules. + + .. versionchanged:: 3.3 + Updated to be based directly on :mod:`importlib` rather than relying + on the package internal PEP 302 import emulation. .. function:: get_importer(path_item) @@ -80,13 +91,13 @@ support. The returned importer is cached in :data:`sys.path_importer_cache` if it was newly created by a path hook. - If there is no importer, a wrapper around the basic import machinery is - returned. This wrapper is never inserted into the importer cache (``None`` - is inserted instead). - The cache (or part of it) can be cleared manually if a rescan of :data:`sys.path_hooks` is necessary. + .. versionchanged:: 3.3 + Updated to be based directly on :mod:`importlib` rather than relying + on the package internal PEP 302 import emulation. + .. function:: get_loader(module_or_name) @@ -102,46 +113,52 @@ support. limitations regarding platform-specific special import locations such as the Windows registry. + .. versionchanged:: 3.3 + Updated to be based directly on :mod:`importlib` rather than relying + on the package internal PEP 302 import emulation. + .. function:: iter_importers(fullname='') Yield :pep:`302` importers for the given module name. - If fullname contains a '.', the importers will be for the package containing - fullname, otherwise they will be importers for :data:`sys.meta_path`, - :data:`sys.path`, and Python's "classic" import machinery, in that order. If - the named module is in a package, that package is imported as a side effect - of invoking this function. + If fullname contains a '.', the importers will be for the package + containing fullname, otherwise they will be all registered top level + importers (i.e. those on both sys.meta_path and sys.path_hooks). - Non-:pep:`302` mechanisms (e.g. the Windows registry) used by the standard - import machinery to find files in alternative locations are partially - supported, but are searched *after* :data:`sys.path`. Normally, these - locations are searched *before* :data:`sys.path`, preventing :data:`sys.path` - entries from shadowing them. + If the named module is in a package, that package is imported as a side + effect of invoking this function. - For this to cause a visible difference in behaviour, there must be a module - or package name that is accessible via both :data:`sys.path` and one of the - non-:pep:`302` file system mechanisms. In this case, the emulation will find - the former version, while the builtin import mechanism will find the latter. + If no module name is specified, all top level importers are produced. - Items of the following types can be affected by this discrepancy: - ``imp.C_EXTENSION``, ``imp.PY_SOURCE``, ``imp.PY_COMPILED``, - ``imp.PKG_DIRECTORY``. + .. versionchanged:: 3.3 + Updated to be based directly on :mod:`importlib` rather than relying + on the package internal PEP 302 import emulation. .. function:: iter_modules(path=None, prefix='') - Yields ``(module_loader, name, ispkg)`` for all submodules on *path*, or, if + Yields ``(module_finder, name, ispkg)`` for all submodules on *path*, or, if path is ``None``, all top-level modules on ``sys.path``. *path* should be either ``None`` or a list of paths to look for modules in. *prefix* is a string to output on the front of every module name on output. + .. note:: + Only works for a :term:`finder` which defines an ``iter_modules()`` + method. This interface is non-standard, so the module also provides + implementations for :class:`importlib.machinery.FileFinder` and + :class:`zipimport.zipimporter`. + + .. versionchanged:: 3.3 + Updated to be based directly on :mod:`importlib` rather than relying + on the package internal PEP 302 import emulation. + .. function:: walk_packages(path=None, prefix='', onerror=None) - Yields ``(module_loader, name, ispkg)`` for all modules recursively on + Yields ``(module_finder, name, ispkg)`` for all modules recursively on *path*, or, if path is ``None``, all accessible modules. *path* should be either ``None`` or a list of paths to look for modules in. @@ -166,6 +183,16 @@ support. # list all submodules of ctypes walk_packages(ctypes.__path__, ctypes.__name__ + '.') + .. note:: + Only works for a :term:`finder` which defines an ``iter_modules()`` + method. This interface is non-standard, so the module also provides + implementations for :class:`importlib.machinery.FileFinder` and + :class:`zipimport.zipimporter`. + + .. versionchanged:: 3.3 + Updated to be based directly on :mod:`importlib` rather than relying + on the package internal PEP 302 import emulation. + .. function:: get_data(package, resource) |