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