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 11This module provides utilities for the import system, in particular package 12support. 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 <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 231 232.. function:: resolve_name(name) 233 234 Resolve a name to an object. 235 236 This functionality is used in numerous places in the standard library (see 237 :issue:`12915`) - and equivalent functionality is also in widely used 238 third-party packages such as setuptools, Django and Pyramid. 239 240 It is expected that *name* will be a string in one of the following 241 formats, where W is shorthand for a valid Python identifier and dot stands 242 for a literal period in these pseudo-regexes: 243 244 * ``W(.W)*`` 245 * ``W(.W)*:(W(.W)*)?`` 246 247 The first form is intended for backward compatibility only. It assumes that 248 some part of the dotted name is a package, and the rest is an object 249 somewhere within that package, possibly nested inside other objects. 250 Because the place where the package stops and the object hierarchy starts 251 can't be inferred by inspection, repeated attempts to import must be done 252 with this form. 253 254 In the second form, the caller makes the division point clear through the 255 provision of a single colon: the dotted name to the left of the colon is a 256 package to be imported, and the dotted name to the right is the object 257 hierarchy within that package. Only one import is needed in this form. If 258 it ends with the colon, then a module object is returned. 259 260 The function will return an object (which might be a module), or raise one 261 of the following exceptions: 262 263 :exc:`ValueError` -- if *name* isn't in a recognised format. 264 265 :exc:`ImportError` -- if an import failed when it shouldn't have. 266 267 :exc:`AttributeError` -- If a failure occurred when traversing the object 268 hierarchy within the imported package to get to the desired object. 269 270 .. versionadded:: 3.9 271