1 :mod:`pkgutil` --- Package extension utility 2 ============================================ 3 4 .. module:: pkgutil 5 :synopsis: Utilities for the import system. 6 7 **Source code:** :source:`Lib/pkgutil.py` 8 9 -------------- 10 11 This module provides utilities for the import system, in particular package 12 support. 13 14 .. class:: ModuleInfo(module_finder, name, ispkg) 15 16 A namedtuple that holds a brief summary of a module's info. 17 18 .. versionadded:: 3.6 19 20 .. function:: extend_path(path, name) 21 22 Extend the search path for the modules which comprise a package. Intended 23 use is to place the following code in a package's :file:`__init__.py`:: 24 25 from pkgutil import extend_path 26 __path__ = extend_path(__path__, __name__) 27 28 This will add to the package's ``__path__`` all subdirectories of directories 29 on ``sys.path`` named after the package. This is useful if one wants to 30 distribute different parts of a single logical package as multiple 31 directories. 32 33 It also looks for :file:`\*.pkg` files beginning where ``*`` matches the 34 *name* argument. This feature is similar to :file:`\*.pth` files (see the 35 :mod:`site` module for more information), except that it doesn't special-case 36 lines starting with ``import``. A :file:`\*.pkg` file is trusted at face 37 value: apart from checking for duplicates, all entries found in a 38 :file:`\*.pkg` file are added to the path, regardless of whether they exist 39 on the filesystem. (This is a feature.) 40 41 If the input path is not a list (as is the case for frozen packages) it is 42 returned unchanged. The input path is not modified; an extended copy is 43 returned. Items are only appended to the copy at the end. 44 45 It is assumed that :data:`sys.path` is a sequence. Items of :data:`sys.path` 46 that are not strings referring to existing directories are ignored. Unicode 47 items on :data:`sys.path` that cause errors when used as filenames may cause 48 this function to raise an exception (in line with :func:`os.path.isdir` 49 behavior). 50 51 52 .. class:: ImpImporter(dirname=None) 53 54 :pep:`302` Finder that wraps Python's "classic" import algorithm. 55 56 If *dirname* is a string, a :pep:`302` finder is created that searches that 57 directory. If *dirname* is ``None``, a :pep:`302` finder is created that 58 searches the current :data:`sys.path`, plus any modules that are frozen or 59 built-in. 60 61 Note that :class:`ImpImporter` does not currently support being used by 62 placement on :data:`sys.meta_path`. 63 64 .. deprecated:: 3.3 65 This emulation is no longer needed, as the standard import mechanism 66 is now fully PEP 302 compliant and available in :mod:`importlib`. 67 68 69 .. class:: ImpLoader(fullname, file, filename, etc) 70 71 :term:`Loader` that wraps Python's "classic" import algorithm. 72 73 .. deprecated:: 3.3 74 This emulation is no longer needed, as the standard import mechanism 75 is now fully PEP 302 compliant and available in :mod:`importlib`. 76 77 78 .. function:: find_loader(fullname) 79 80 Retrieve a module :term:`loader` for the given *fullname*. 81 82 This is a backwards compatibility wrapper around 83 :func:`importlib.util.find_spec` that converts most failures to 84 :exc:`ImportError` and only returns the loader rather than the full 85 :class:`ModuleSpec`. 86 87 .. versionchanged:: 3.3 88 Updated to be based directly on :mod:`importlib` rather than relying 89 on the package internal PEP 302 import emulation. 90 91 .. versionchanged:: 3.4 92 Updated to be based on :pep:`451` 93 94 .. function:: get_importer(path_item) 95 96 Retrieve a :term:`finder` for the given *path_item*. 97 98 The returned finder is cached in :data:`sys.path_importer_cache` if it was 99 newly created by a path hook. 100 101 The cache (or part of it) can be cleared manually if a rescan of 102 :data:`sys.path_hooks` is necessary. 103 104 .. versionchanged:: 3.3 105 Updated to be based directly on :mod:`importlib` rather than relying 106 on the package internal PEP 302 import emulation. 107 108 109 .. function:: get_loader(module_or_name) 110 111 Get a :term:`loader` object for *module_or_name*. 112 113 If the module or package is accessible via the normal import mechanism, a 114 wrapper around the relevant part of that machinery is returned. Returns 115 ``None`` if the module cannot be found or imported. If the named module is 116 not already imported, its containing package (if any) is imported, in order 117 to establish the package ``__path__``. 118 119 .. versionchanged:: 3.3 120 Updated to be based directly on :mod:`importlib` rather than relying 121 on the package internal PEP 302 import emulation. 122 123 .. versionchanged:: 3.4 124 Updated to be based on :pep:`451` 125 126 127 .. function:: iter_importers(fullname='') 128 129 Yield :term:`finder` objects for the given module name. 130 131 If fullname contains a '.', the finders will be for the package 132 containing fullname, otherwise they will be all registered top level 133 finders (i.e. those on both sys.meta_path and sys.path_hooks). 134 135 If the named module is in a package, that package is imported as a side 136 effect of invoking this function. 137 138 If no module name is specified, all top level finders are produced. 139 140 .. versionchanged:: 3.3 141 Updated to be based directly on :mod:`importlib` rather than relying 142 on the package internal PEP 302 import emulation. 143 144 145 .. function:: iter_modules(path=None, prefix='') 146 147 Yields :class:`ModuleInfo` for all submodules on *path*, or, if 148 *path* is ``None``, all top-level modules on ``sys.path``. 149 150 *path* should be either ``None`` or a list of paths to look for modules in. 151 152 *prefix* is a string to output on the front of every module name on output. 153 154 .. note:: 155 156 Only works for a :term:`finder` which defines an ``iter_modules()`` 157 method. This interface is non-standard, so the module also provides 158 implementations for :class:`importlib.machinery.FileFinder` and 159 :class:`zipimport.zipimporter`. 160 161 .. versionchanged:: 3.3 162 Updated to be based directly on :mod:`importlib` rather than relying 163 on the package internal PEP 302 import emulation. 164 165 166 .. function:: walk_packages(path=None, prefix='', onerror=None) 167 168 Yields :class:`ModuleInfo` for all modules recursively on 169 *path*, or, if *path* is ``None``, all accessible modules. 170 171 *path* should be either ``None`` or a list of paths to look for modules in. 172 173 *prefix* is a string to output on the front of every module name on output. 174 175 Note that this function must import all *packages* (*not* all modules!) on 176 the given *path*, in order to access the ``__path__`` attribute to find 177 submodules. 178 179 *onerror* is a function which gets called with one argument (the name of the 180 package which was being imported) if any exception occurs while trying to 181 import a package. If no *onerror* function is supplied, :exc:`ImportError`\s 182 are caught and ignored, while all other exceptions are propagated, 183 terminating the search. 184 185 Examples:: 186 187 # list all modules python can access 188 walk_packages() 189 190 # list all submodules of ctypes 191 walk_packages(ctypes.__path__, ctypes.__name__ + '.') 192 193 .. note:: 194 195 Only works for a :term:`finder` which defines an ``iter_modules()`` 196 method. This interface is non-standard, so the module also provides 197 implementations for :class:`importlib.machinery.FileFinder` and 198 :class:`zipimport.zipimporter`. 199 200 .. versionchanged:: 3.3 201 Updated to be based directly on :mod:`importlib` rather than relying 202 on the package internal PEP 302 import emulation. 203 204 205 .. function:: get_data(package, resource) 206 207 Get a resource from a package. 208 209 This is a wrapper for the :term:`loader` 210 :meth:`get_data <importlib.abc.ResourceLoader.get_data>` API. The 211 *package* argument should be the name of a package, in standard module format 212 (``foo.bar``). The *resource* argument should be in the form of a relative 213 filename, using ``/`` as the path separator. The parent directory name 214 ``..`` is not allowed, and nor is a rooted name (starting with a ``/``). 215 216 The function returns a binary string that is the contents of the specified 217 resource. 218 219 For packages located in the filesystem, which have already been imported, 220 this is the rough equivalent of:: 221 222 d = os.path.dirname(sys.modules[package].__file__) 223 data = open(os.path.join(d, resource), 'rb').read() 224 225 If the package cannot be located or loaded, or it uses a :term:`loader` 226 which does not support :meth:`get_data <importlib.abc.ResourceLoader.get_data>`, 227 then ``None`` is returned. In particular, the :term:`loader` for 228 :term:`namespace packages <namespace package>` does not support 229 :meth:`get_data <importlib.abc.ResourceLoader.get_data>`. 230
