1 :mod:`pkgutil` --- Package extension utility 2 ============================================ 3 4 .. module:: pkgutil 5 :synopsis: Utilities for the import system. 6 7 .. versionadded:: 2.3 8 9 **Source code:** :source:`Lib/pkgutil.py` 10 11 -------------- 12 13 This module provides utilities for the import system, in particular package 14 support. 15 16 17 .. function:: extend_path(path, name) 18 19 Extend the search path for the modules which comprise a package. Intended 20 use is to place the following code in a package's :file:`__init__.py`:: 21 22 from pkgutil import extend_path 23 __path__ = extend_path(__path__, __name__) 24 25 This will add to the package's ``__path__`` all subdirectories of directories 26 on ``sys.path`` named after the package. This is useful if one wants to 27 distribute different parts of a single logical package as multiple 28 directories. 29 30 It also looks for :file:`\*.pkg` files beginning where ``*`` matches the 31 *name* argument. This feature is similar to :file:`\*.pth` files (see the 32 :mod:`site` module for more information), except that it doesn't special-case 33 lines starting with ``import``. A :file:`\*.pkg` file is trusted at face 34 value: apart from checking for duplicates, all entries found in a 35 :file:`\*.pkg` file are added to the path, regardless of whether they exist 36 on the filesystem. (This is a feature.) 37 38 If the input path is not a list (as is the case for frozen packages) it is 39 returned unchanged. The input path is not modified; an extended copy is 40 returned. Items are only appended to the copy at the end. 41 42 It is assumed that :data:`sys.path` is a sequence. Items of :data:`sys.path` 43 that are not (Unicode or 8-bit) strings referring to existing directories are 44 ignored. Unicode items on :data:`sys.path` that cause errors when used as 45 filenames may cause this function to raise an exception (in line with 46 :func:`os.path.isdir` behavior). 47 48 49 .. class:: ImpImporter(dirname=None) 50 51 :pep:`302` Importer that wraps Python's "classic" import algorithm. 52 53 If *dirname* is a string, a :pep:`302` importer is created that searches that 54 directory. If *dirname* is ``None``, a :pep:`302` importer is created that 55 searches the current :data:`sys.path`, plus any modules that are frozen or 56 built-in. 57 58 Note that :class:`ImpImporter` does not currently support being used by 59 placement on :data:`sys.meta_path`. 60 61 62 .. class:: ImpLoader(fullname, file, filename, etc) 63 64 :pep:`302` Loader that wraps Python's "classic" import algorithm. 65 66 67 .. function:: find_loader(fullname) 68 69 Find a :pep:`302` "loader" object for *fullname*. 70 71 If *fullname* contains dots, path must be the containing package's 72 ``__path__``. Returns ``None`` if the module cannot be found or imported. 73 This function uses :func:`iter_importers`, and is thus subject to the same 74 limitations regarding platform-specific special import locations such as the 75 Windows registry. 76 77 78 .. function:: get_importer(path_item) 79 80 Retrieve a :pep:`302` importer for the given *path_item*. 81 82 The returned importer is cached in :data:`sys.path_importer_cache` if it was 83 newly created by a path hook. 84 85 If there is no importer, a wrapper around the basic import machinery is 86 returned. This wrapper is never inserted into the importer cache (``None`` 87 is inserted instead). 88 89 The cache (or part of it) can be cleared manually if a rescan of 90 :data:`sys.path_hooks` is necessary. 91 92 93 .. function:: get_loader(module_or_name) 94 95 Get a :pep:`302` "loader" object for *module_or_name*. 96 97 If the module or package is accessible via the normal import mechanism, a 98 wrapper around the relevant part of that machinery is returned. Returns 99 ``None`` if the module cannot be found or imported. If the named module is 100 not already imported, its containing package (if any) is imported, in order 101 to establish the package ``__path__``. 102 103 This function uses :func:`iter_importers`, and is thus subject to the same 104 limitations regarding platform-specific special import locations such as the 105 Windows registry. 106 107 108 .. function:: iter_importers(fullname='') 109 110 Yield :pep:`302` importers for the given module name. 111 112 If fullname contains a '.', the importers will be for the package containing 113 fullname, otherwise they will be importers for :data:`sys.meta_path`, 114 :data:`sys.path`, and Python's "classic" import machinery, in that order. If 115 the named module is in a package, that package is imported as a side effect 116 of invoking this function. 117 118 Non-:pep:`302` mechanisms (e.g. the Windows registry) used by the standard 119 import machinery to find files in alternative locations are partially 120 supported, but are searched *after* :data:`sys.path`. Normally, these 121 locations are searched *before* :data:`sys.path`, preventing :data:`sys.path` 122 entries from shadowing them. 123 124 For this to cause a visible difference in behaviour, there must be a module 125 or package name that is accessible via both :data:`sys.path` and one of the 126 non-:pep:`302` file system mechanisms. In this case, the emulation will find 127 the former version, while the builtin import mechanism will find the latter. 128 129 Items of the following types can be affected by this discrepancy: 130 ``imp.C_EXTENSION``, ``imp.PY_SOURCE``, ``imp.PY_COMPILED``, 131 ``imp.PKG_DIRECTORY``. 132 133 134 .. function:: iter_modules(path=None, prefix='') 135 136 Yields ``(module_loader, name, ispkg)`` for all submodules on *path*, or, if 137 path is ``None``, all top-level modules on ``sys.path``. 138 139 *path* should be either ``None`` or a list of paths to look for modules in. 140 141 *prefix* is a string to output on the front of every module name on output. 142 143 144 .. function:: walk_packages(path=None, prefix='', onerror=None) 145 146 Yields ``(module_loader, name, ispkg)`` for all modules recursively on 147 *path*, or, if path is ``None``, all accessible modules. 148 149 *path* should be either ``None`` or a list of paths to look for modules in. 150 151 *prefix* is a string to output on the front of every module name on output. 152 153 Note that this function must import all *packages* (*not* all modules!) on 154 the given *path*, in order to access the ``__path__`` attribute to find 155 submodules. 156 157 *onerror* is a function which gets called with one argument (the name of the 158 package which was being imported) if any exception occurs while trying to 159 import a package. If no *onerror* function is supplied, :exc:`ImportError`\s 160 are caught and ignored, while all other exceptions are propagated, 161 terminating the search. 162 163 Examples:: 164 165 # list all modules python can access 166 walk_packages() 167 168 # list all submodules of ctypes 169 walk_packages(ctypes.__path__, ctypes.__name__ + '.') 170 171 172 .. function:: get_data(package, resource) 173 174 Get a resource from a package. 175 176 This is a wrapper for the :pep:`302` loader :func:`get_data` API. The 177 *package* argument should be the name of a package, in standard module format 178 (``foo.bar``). The *resource* argument should be in the form of a relative 179 filename, using ``/`` as the path separator. The parent directory name 180 ``..`` is not allowed, and nor is a rooted name (starting with a ``/``). 181 182 The function returns a binary string that is the contents of the specified 183 resource. 184 185 For packages located in the filesystem, which have already been imported, 186 this is the rough equivalent of:: 187 188 d = os.path.dirname(sys.modules[package].__file__) 189 data = open(os.path.join(d, resource), 'rb').read() 190 191 If the package cannot be located or loaded, or it uses a :pep:`302` loader 192 which does not support :func:`get_data`, then ``None`` is returned. 193 194 .. versionadded:: 2.6 195
