Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 1 | :mod:`importlib` -- An implementation of :keyword:`import` |
| 2 | ========================================================== |
| 3 | |
| 4 | .. module:: importlib |
| 5 | :synopsis: An implementation of the import machinery. |
| 6 | |
| 7 | .. moduleauthor:: Brett Cannon <brett@python.org> |
| 8 | .. sectionauthor:: Brett Cannon <brett@python.org> |
| 9 | |
| 10 | .. versionadded:: 3.1 |
| 11 | |
| 12 | |
| 13 | Introduction |
| 14 | ------------ |
| 15 | |
| 16 | The purpose of the :mod:`importlib` package is two-fold. One is to provide an |
| 17 | implementation of the :keyword:`import` statement (and thus, by extension, the |
| 18 | :func:`__import__` function) in Python source code. This provides an |
Tarek Ziadé | 434caaa | 2009-05-14 12:48:09 +0000 | [diff] [blame] | 19 | implementation of :keyword:`import` which is portable to any Python |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 20 | interpreter. This also provides a reference implementation which is easier to |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 21 | comprehend than one implemented in a programming language other than Python. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 22 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 23 | Two, the components to implement :keyword:`import` are exposed in this |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 24 | package, making it easier for users to create their own custom objects (known |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 25 | generically as an :term:`importer`) to participate in the import process. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 26 | Details on custom importers can be found in :pep:`302`. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 27 | |
| 28 | .. seealso:: |
| 29 | |
| 30 | :ref:`import` |
| 31 | The language reference for the :keyword:`import` statement. |
| 32 | |
| 33 | `Packages specification <http://www.python.org/doc/essays/packages.html>`__ |
| 34 | Original specification of packages. Some semantics have changed since |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 35 | the writing of this document (e.g. redirecting based on ``None`` |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 36 | in :data:`sys.modules`). |
| 37 | |
| 38 | The :func:`.__import__` function |
Brett Cannon | 0e13c94 | 2010-06-29 18:26:11 +0000 | [diff] [blame] | 39 | The :keyword:`import` statement is syntactic sugar for this function. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 40 | |
| 41 | :pep:`235` |
| 42 | Import on Case-Insensitive Platforms |
| 43 | |
| 44 | :pep:`263` |
| 45 | Defining Python Source Code Encodings |
| 46 | |
| 47 | :pep:`302` |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 48 | New Import Hooks |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 49 | |
| 50 | :pep:`328` |
| 51 | Imports: Multi-Line and Absolute/Relative |
| 52 | |
| 53 | :pep:`366` |
| 54 | Main module explicit relative imports |
| 55 | |
Brett Cannon | 8917d5e | 2010-01-13 19:21:00 +0000 | [diff] [blame] | 56 | :pep:`3120` |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 57 | Using UTF-8 as the Default Source Encoding |
| 58 | |
Brett Cannon | 30b7a90 | 2010-06-27 21:49:22 +0000 | [diff] [blame] | 59 | :pep:`3147` |
| 60 | PYC Repository Directories |
| 61 | |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 62 | |
| 63 | Functions |
| 64 | --------- |
| 65 | |
Brett Cannon | cb4996a | 2012-08-06 16:34:44 -0400 | [diff] [blame] | 66 | .. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0) |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 67 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 68 | An implementation of the built-in :func:`__import__` function. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 69 | |
| 70 | .. function:: import_module(name, package=None) |
| 71 | |
Brett Cannon | 33418c8 | 2009-01-22 18:37:20 +0000 | [diff] [blame] | 72 | Import a module. The *name* argument specifies what module to |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 73 | import in absolute or relative terms |
| 74 | (e.g. either ``pkg.mod`` or ``..mod``). If the name is |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 75 | specified in relative terms, then the *package* argument must be set to |
| 76 | the name of the package which is to act as the anchor for resolving the |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 77 | package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 78 | ``pkg.mod``). |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 79 | |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 80 | The :func:`import_module` function acts as a simplifying wrapper around |
Brett Cannon | 9f4cb1c | 2009-04-01 23:26:47 +0000 | [diff] [blame] | 81 | :func:`importlib.__import__`. This means all semantics of the function are |
| 82 | derived from :func:`importlib.__import__`, including requiring the package |
| 83 | from which an import is occurring to have been previously imported |
| 84 | (i.e., *package* must already be imported). The most important difference |
| 85 | is that :func:`import_module` returns the most nested package or module |
| 86 | that was imported (e.g. ``pkg.mod``), while :func:`__import__` returns the |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 87 | top-level package or module (e.g. ``pkg``). |
| 88 | |
Brett Cannon | ee78a2b | 2012-05-12 17:43:17 -0400 | [diff] [blame] | 89 | .. function:: find_loader(name, path=None) |
| 90 | |
| 91 | Find the loader for a module, optionally within the specified *path*. If the |
| 92 | module is in :attr:`sys.modules`, then ``sys.modules[name].__loader__`` is |
| 93 | returned (unless the loader would be ``None``, in which case |
| 94 | :exc:`ValueError` is raised). Otherwise a search using :attr:`sys.meta_path` |
| 95 | is done. ``None`` is returned if no loader is found. |
| 96 | |
Brett Cannon | 56b4ca7 | 2012-11-17 09:30:55 -0500 | [diff] [blame] | 97 | A dotted name does not have its parent's implicitly imported as that requires |
| 98 | loading them and that may not be desired. To properly import a submodule you |
| 99 | will need to import all parent packages of the submodule and use the correct |
| 100 | argument to *path*. |
Brett Cannon | ee78a2b | 2012-05-12 17:43:17 -0400 | [diff] [blame] | 101 | |
Antoine Pitrou | c541f8e | 2012-02-20 01:48:16 +0100 | [diff] [blame] | 102 | .. function:: invalidate_caches() |
| 103 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 104 | Invalidate the internal caches of finders stored at |
| 105 | :data:`sys.meta_path`. If a finder implements ``invalidate_caches()`` then it |
Brett Cannon | 4067aa2 | 2013-04-27 23:20:32 -0400 | [diff] [blame] | 106 | will be called to perform the invalidation. This function should be called |
| 107 | if any modules are created/installed while your program is running to |
| 108 | guarantee all finders will notice the new module's existence. |
Antoine Pitrou | c541f8e | 2012-02-20 01:48:16 +0100 | [diff] [blame] | 109 | |
| 110 | .. versionadded:: 3.3 |
| 111 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 112 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 113 | :mod:`importlib.abc` -- Abstract base classes related to import |
| 114 | --------------------------------------------------------------- |
| 115 | |
| 116 | .. module:: importlib.abc |
| 117 | :synopsis: Abstract base classes related to import |
| 118 | |
| 119 | The :mod:`importlib.abc` module contains all of the core abstract base classes |
| 120 | used by :keyword:`import`. Some subclasses of the core abstract base classes |
| 121 | are also provided to help in implementing the core ABCs. |
| 122 | |
Andrew Svetlov | a865654 | 2012-08-13 22:19:01 +0300 | [diff] [blame] | 123 | ABC hierarchy:: |
| 124 | |
| 125 | object |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 126 | +-- Finder (deprecated) |
Andrew Svetlov | a865654 | 2012-08-13 22:19:01 +0300 | [diff] [blame] | 127 | | +-- MetaPathFinder |
| 128 | | +-- PathEntryFinder |
| 129 | +-- Loader |
| 130 | +-- ResourceLoader --------+ |
| 131 | +-- InspectLoader | |
| 132 | +-- ExecutionLoader --+ |
| 133 | +-- FileLoader |
| 134 | +-- SourceLoader |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 135 | +-- PyLoader (deprecated) |
| 136 | +-- PyPycLoader (deprecated) |
Andrew Svetlov | a865654 | 2012-08-13 22:19:01 +0300 | [diff] [blame] | 137 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 138 | |
| 139 | .. class:: Finder |
| 140 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 141 | An abstract base class representing a :term:`finder`. |
| 142 | |
| 143 | .. deprecated:: 3.3 |
| 144 | Use :class:`MetaPathFinder` or :class:`PathEntryFinder` instead. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 145 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 146 | .. method:: find_module(fullname, path=None) |
Brett Cannon | b46a179 | 2012-02-27 18:15:42 -0500 | [diff] [blame] | 147 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 148 | An abstact method for finding a :term:`loader` for the specified |
| 149 | module. Originally specified in :pep:`302`, this method was meant |
| 150 | for use in :data:`sys.meta_path` and in the path-based import subsystem. |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 151 | |
| 152 | |
Brett Cannon | 077ef45 | 2012-08-02 17:50:06 -0400 | [diff] [blame] | 153 | .. class:: MetaPathFinder |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 154 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 155 | An abstract base class representing a :term:`meta path finder`. For |
| 156 | compatibility, this is a subclass of :class:`Finder`. |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 157 | |
| 158 | .. versionadded:: 3.3 |
| 159 | |
| 160 | .. method:: find_module(fullname, path) |
| 161 | |
| 162 | An abstract method for finding a :term:`loader` for the specified |
| 163 | module. If this is a top-level import, *path* will be ``None``. |
Ezio Melotti | 1f67e80 | 2012-10-21 07:24:13 +0300 | [diff] [blame] | 164 | Otherwise, this is a search for a subpackage or module and *path* |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 165 | will be the value of :attr:`__path__` from the parent |
| 166 | package. If a loader cannot be found, ``None`` is returned. |
| 167 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 168 | .. method:: invalidate_caches() |
| 169 | |
| 170 | An optional method which, when called, should invalidate any internal |
Brett Cannon | a6e8581 | 2012-08-11 19:41:27 -0400 | [diff] [blame] | 171 | cache used by the finder. Used by :func:`importlib.invalidate_caches` |
| 172 | when invalidating the caches of all finders on :data:`sys.meta_path`. |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 173 | |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 174 | |
Brett Cannon | 077ef45 | 2012-08-02 17:50:06 -0400 | [diff] [blame] | 175 | .. class:: PathEntryFinder |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 176 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 177 | An abstract base class representing a :term:`path entry finder`. Though |
| 178 | it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder`` |
| 179 | is meant for use only within the path-based import subsystem provided |
| 180 | by :class:`PathFinder`. This ABC is a subclass of :class:`Finder` for |
| 181 | compatibility. |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 182 | |
| 183 | .. versionadded:: 3.3 |
| 184 | |
Brett Cannon | 4067aa2 | 2013-04-27 23:20:32 -0400 | [diff] [blame] | 185 | .. method:: find_loader(fullname) |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 186 | |
| 187 | An abstract method for finding a :term:`loader` for the specified |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 188 | module. Returns a 2-tuple of ``(loader, portion)`` where ``portion`` |
| 189 | is a sequence of file system locations contributing to part of a namespace |
| 190 | package. The loader may be ``None`` while specifying ``portion`` to |
| 191 | signify the contribution of the file system locations to a namespace |
| 192 | package. An empty list can be used for ``portion`` to signify the loader |
| 193 | is not part of a package. If ``loader`` is ``None`` and ``portion`` is |
| 194 | the empty list then no loader or location for a namespace package were |
| 195 | found (i.e. failure to find anything for the module). |
| 196 | |
Brett Cannon | 4067aa2 | 2013-04-27 23:20:32 -0400 | [diff] [blame] | 197 | .. method:: find_module(fullname) |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 198 | |
| 199 | A concrete implementation of :meth:`Finder.find_module` which is |
| 200 | equivalent to ``self.find_loader(fullname)[0]``. |
| 201 | |
| 202 | .. method:: invalidate_caches() |
| 203 | |
| 204 | An optional method which, when called, should invalidate any internal |
Brett Cannon | a6e8581 | 2012-08-11 19:41:27 -0400 | [diff] [blame] | 205 | cache used by the finder. Used by :meth:`PathFinder.invalidate_caches` |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 206 | when invalidating the caches of all cached finders. |
Brett Cannon | b46a179 | 2012-02-27 18:15:42 -0500 | [diff] [blame] | 207 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 208 | |
| 209 | .. class:: Loader |
| 210 | |
| 211 | An abstract base class for a :term:`loader`. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 212 | See :pep:`302` for the exact definition for a loader. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 213 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 214 | .. method:: load_module(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 215 | |
| 216 | An abstract method for loading a module. If the module cannot be |
| 217 | loaded, :exc:`ImportError` is raised, otherwise the loaded module is |
| 218 | returned. |
| 219 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 220 | If the requested module already exists in :data:`sys.modules`, that |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 221 | module should be used and reloaded. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 222 | Otherwise the loader should create a new module and insert it into |
| 223 | :data:`sys.modules` before any loading begins, to prevent recursion |
| 224 | from the import. If the loader inserted a module and the load fails, it |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 225 | must be removed by the loader from :data:`sys.modules`; modules already |
| 226 | in :data:`sys.modules` before the loader began execution should be left |
| 227 | alone. The :func:`importlib.util.module_for_loader` decorator handles |
| 228 | all of these details. |
| 229 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 230 | The loader should set several attributes on the module. |
| 231 | (Note that some of these attributes can change when a module is |
| 232 | reloaded.) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 233 | |
| 234 | - :attr:`__name__` |
| 235 | The name of the module. |
| 236 | |
| 237 | - :attr:`__file__` |
| 238 | The path to where the module data is stored (not set for built-in |
| 239 | modules). |
| 240 | |
| 241 | - :attr:`__path__` |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 242 | A list of strings specifying the search path within a |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 243 | package. This attribute is not set on modules. |
| 244 | |
| 245 | - :attr:`__package__` |
| 246 | The parent package for the module/package. If the module is |
| 247 | top-level then it has a value of the empty string. The |
| 248 | :func:`importlib.util.set_package` decorator can handle the details |
| 249 | for :attr:`__package__`. |
| 250 | |
| 251 | - :attr:`__loader__` |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 252 | The loader used to load the module. |
| 253 | (This is not set by the built-in import machinery, |
| 254 | but it should be set whenever a :term:`loader` is used.) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 255 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 256 | .. method:: module_repr(module) |
| 257 | |
| 258 | An abstract method which when implemented calculates and returns the |
| 259 | given module's repr, as a string. |
| 260 | |
| 261 | .. versionadded: 3.3 |
| 262 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 263 | |
| 264 | .. class:: ResourceLoader |
| 265 | |
| 266 | An abstract base class for a :term:`loader` which implements the optional |
| 267 | :pep:`302` protocol for loading arbitrary resources from the storage |
| 268 | back-end. |
| 269 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 270 | .. method:: get_data(path) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 271 | |
| 272 | An abstract method to return the bytes for the data located at *path*. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 273 | Loaders that have a file-like storage back-end |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 274 | that allows storing arbitrary data |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 275 | can implement this abstract method to give direct access |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 276 | to the data stored. :exc:`IOError` is to be raised if the *path* cannot |
| 277 | be found. The *path* is expected to be constructed using a module's |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 278 | :attr:`__file__` attribute or an item from a package's :attr:`__path__`. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 279 | |
| 280 | |
| 281 | .. class:: InspectLoader |
| 282 | |
| 283 | An abstract base class for a :term:`loader` which implements the optional |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 284 | :pep:`302` protocol for loaders that inspect modules. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 285 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 286 | .. method:: get_code(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 287 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 288 | An abstract method to return the :class:`code` object for a module. |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 289 | ``None`` is returned if the module does not have a code object |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 290 | (e.g. built-in module). :exc:`ImportError` is raised if loader cannot |
| 291 | find the requested module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 292 | |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 293 | .. index:: |
| 294 | single: universal newlines; importlib.abc.InspectLoader.get_source method |
| 295 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 296 | .. method:: get_source(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 297 | |
| 298 | An abstract method to return the source of a module. It is returned as |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 299 | a text string using :term:`universal newlines`, translating all |
R David Murray | ee0a945 | 2012-08-15 11:05:36 -0400 | [diff] [blame] | 300 | recognized line separators into ``'\n'`` characters. Returns ``None`` |
| 301 | if no source is available (e.g. a built-in module). Raises |
| 302 | :exc:`ImportError` if the loader cannot find the module specified. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 303 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 304 | .. method:: is_package(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 305 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 306 | An abstract method to return a true value if the module is a package, a |
| 307 | false value otherwise. :exc:`ImportError` is raised if the |
| 308 | :term:`loader` cannot find the module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 309 | |
| 310 | |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 311 | .. class:: ExecutionLoader |
| 312 | |
| 313 | An abstract base class which inherits from :class:`InspectLoader` that, |
Brett Cannon | 2346029 | 2009-07-20 22:59:00 +0000 | [diff] [blame] | 314 | when implemented, helps a module to be executed as a script. The ABC |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 315 | represents an optional :pep:`302` protocol. |
| 316 | |
| 317 | .. method:: get_filename(fullname) |
| 318 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 319 | An abstract method that is to return the value of :attr:`__file__` for |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 320 | the specified module. If no path is available, :exc:`ImportError` is |
| 321 | raised. |
| 322 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 323 | If source code is available, then the method should return the path to |
| 324 | the source file, regardless of whether a bytecode was used to load the |
| 325 | module. |
| 326 | |
| 327 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 328 | .. class:: FileLoader(fullname, path) |
| 329 | |
| 330 | An abstract base class which inherits from :class:`ResourceLoader` and |
Andrew Svetlov | a60de4f | 2013-02-17 16:55:58 +0200 | [diff] [blame] | 331 | :class:`ExecutionLoader`, providing concrete implementations of |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 332 | :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`. |
| 333 | |
| 334 | The *fullname* argument is a fully resolved name of the module the loader is |
| 335 | to handle. The *path* argument is the path to the file for the module. |
| 336 | |
| 337 | .. versionadded:: 3.3 |
| 338 | |
| 339 | .. attribute:: name |
| 340 | |
| 341 | The name of the module the loader can handle. |
| 342 | |
| 343 | .. attribute:: path |
| 344 | |
| 345 | Path to the file of the module. |
| 346 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 347 | .. method:: load_module(fullname) |
Brett Cannon | c049952 | 2012-05-11 14:48:41 -0400 | [diff] [blame] | 348 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 349 | Calls super's ``load_module()``. |
Brett Cannon | c049952 | 2012-05-11 14:48:41 -0400 | [diff] [blame] | 350 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 351 | .. method:: get_filename(fullname) |
| 352 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 353 | Returns :attr:`path`. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 354 | |
| 355 | .. method:: get_data(path) |
| 356 | |
| 357 | Returns the open, binary file for *path*. |
| 358 | |
| 359 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 360 | .. class:: SourceLoader |
| 361 | |
| 362 | An abstract base class for implementing source (and optionally bytecode) |
| 363 | file loading. The class inherits from both :class:`ResourceLoader` and |
| 364 | :class:`ExecutionLoader`, requiring the implementation of: |
| 365 | |
| 366 | * :meth:`ResourceLoader.get_data` |
| 367 | * :meth:`ExecutionLoader.get_filename` |
Brett Cannon | 6dfbff3 | 2010-07-21 09:48:31 +0000 | [diff] [blame] | 368 | Should only return the path to the source file; sourceless |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 369 | loading is not supported. |
| 370 | |
| 371 | The abstract methods defined by this class are to add optional bytecode |
| 372 | file support. Not implementing these optional methods causes the loader to |
| 373 | only work with source code. Implementing the methods allows the loader to |
| 374 | work with source *and* bytecode files; it does not allow for *sourceless* |
| 375 | loading where only bytecode is provided. Bytecode files are an |
| 376 | optimization to speed up loading by removing the parsing step of Python's |
| 377 | compiler, and so no bytecode-specific API is exposed. |
| 378 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 379 | .. method:: path_stats(path) |
Antoine Pitrou | 5136ac0 | 2012-01-13 18:52:16 +0100 | [diff] [blame] | 380 | |
| 381 | Optional abstract method which returns a :class:`dict` containing |
| 382 | metadata about the specifed path. Supported dictionary keys are: |
| 383 | |
| 384 | - ``'mtime'`` (mandatory): an integer or floating-point number |
| 385 | representing the modification time of the source code; |
| 386 | - ``'size'`` (optional): the size in bytes of the source code. |
| 387 | |
| 388 | Any other keys in the dictionary are ignored, to allow for future |
| 389 | extensions. |
| 390 | |
| 391 | .. versionadded:: 3.3 |
| 392 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 393 | .. method:: path_mtime(path) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 394 | |
| 395 | Optional abstract method which returns the modification time for the |
| 396 | specified path. |
| 397 | |
Antoine Pitrou | 5136ac0 | 2012-01-13 18:52:16 +0100 | [diff] [blame] | 398 | .. deprecated:: 3.3 |
| 399 | This method is deprecated in favour of :meth:`path_stats`. You don't |
| 400 | have to implement it, but it is still available for compatibility |
| 401 | purposes. |
| 402 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 403 | .. method:: set_data(path, data) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 404 | |
| 405 | Optional abstract method which writes the specified bytes to a file |
Brett Cannon | 61b1425 | 2010-07-03 21:48:25 +0000 | [diff] [blame] | 406 | path. Any intermediate directories which do not exist are to be created |
| 407 | automatically. |
| 408 | |
| 409 | When writing to the path fails because the path is read-only |
| 410 | (:attr:`errno.EACCES`), do not propagate the exception. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 411 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 412 | .. method:: get_code(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 413 | |
| 414 | Concrete implementation of :meth:`InspectLoader.get_code`. |
| 415 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 416 | .. method:: load_module(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 417 | |
| 418 | Concrete implementation of :meth:`Loader.load_module`. |
| 419 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 420 | .. method:: get_source(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 421 | |
| 422 | Concrete implementation of :meth:`InspectLoader.get_source`. |
| 423 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 424 | .. method:: is_package(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 425 | |
| 426 | Concrete implementation of :meth:`InspectLoader.is_package`. A module |
Brett Cannon | ea0b823 | 2012-06-15 20:00:53 -0400 | [diff] [blame] | 427 | is determined to be a package if its file path (as provided by |
| 428 | :meth:`ExecutionLoader.get_filename`) is a file named |
| 429 | ``__init__`` when the file extension is removed **and** the module name |
| 430 | itself does not end in ``__init__``. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 431 | |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 432 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 433 | .. class:: PyLoader |
| 434 | |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 435 | An abstract base class inheriting from |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 436 | :class:`ExecutionLoader` and |
| 437 | :class:`ResourceLoader` designed to ease the loading of |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 438 | Python source modules (bytecode is not handled; see |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 439 | :class:`SourceLoader` for a source/bytecode ABC). A subclass |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 440 | implementing this ABC will only need to worry about exposing how the source |
| 441 | code is stored; all other details for loading Python source code will be |
| 442 | handled by the concrete implementations of key methods. |
| 443 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 444 | .. deprecated:: 3.2 |
| 445 | This class has been deprecated in favor of :class:`SourceLoader` and is |
| 446 | slated for removal in Python 3.4. See below for how to create a |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 447 | subclass that is compatible with Python 3.1 onwards. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 448 | |
| 449 | If compatibility with Python 3.1 is required, then use the following idiom |
| 450 | to implement a subclass that will work with Python 3.1 onwards (make sure |
| 451 | to implement :meth:`ExecutionLoader.get_filename`):: |
| 452 | |
| 453 | try: |
| 454 | from importlib.abc import SourceLoader |
| 455 | except ImportError: |
| 456 | from importlib.abc import PyLoader as SourceLoader |
| 457 | |
| 458 | |
| 459 | class CustomLoader(SourceLoader): |
| 460 | def get_filename(self, fullname): |
| 461 | """Return the path to the source file.""" |
| 462 | # Implement ... |
| 463 | |
| 464 | def source_path(self, fullname): |
| 465 | """Implement source_path in terms of get_filename.""" |
| 466 | try: |
| 467 | return self.get_filename(fullname) |
| 468 | except ImportError: |
| 469 | return None |
| 470 | |
| 471 | def is_package(self, fullname): |
| 472 | """Implement is_package by looking for an __init__ file |
| 473 | name as returned by get_filename.""" |
| 474 | filename = os.path.basename(self.get_filename(fullname)) |
| 475 | return os.path.splitext(filename)[0] == '__init__' |
| 476 | |
| 477 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 478 | .. method:: source_path(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 479 | |
| 480 | An abstract method that returns the path to the source code for a |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 481 | module. Should return ``None`` if there is no source code. |
Brett Cannon | 3e761a9 | 2009-12-10 00:24:21 +0000 | [diff] [blame] | 482 | Raises :exc:`ImportError` if the loader knows it cannot handle the |
| 483 | module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 484 | |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 485 | .. method:: get_filename(fullname) |
| 486 | |
| 487 | A concrete implementation of |
| 488 | :meth:`importlib.abc.ExecutionLoader.get_filename` that |
| 489 | relies on :meth:`source_path`. If :meth:`source_path` returns |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 490 | ``None``, then :exc:`ImportError` is raised. |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 491 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 492 | .. method:: load_module(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 493 | |
| 494 | A concrete implementation of :meth:`importlib.abc.Loader.load_module` |
Brett Cannon | ad876c7 | 2009-03-09 07:53:09 +0000 | [diff] [blame] | 495 | that loads Python source code. All needed information comes from the |
| 496 | abstract methods required by this ABC. The only pertinent assumption |
| 497 | made by this method is that when loading a package |
| 498 | :attr:`__path__` is set to ``[os.path.dirname(__file__)]``. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 499 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 500 | .. method:: get_code(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 501 | |
| 502 | A concrete implementation of |
| 503 | :meth:`importlib.abc.InspectLoader.get_code` that creates code objects |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 504 | from Python source code, by requesting the source code (using |
Benjamin Peterson | 0089d75 | 2009-11-13 00:52:43 +0000 | [diff] [blame] | 505 | :meth:`source_path` and :meth:`get_data`) and compiling it with the |
| 506 | built-in :func:`compile` function. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 507 | |
Brett Cannon | d43b30b | 2009-03-10 03:29:23 +0000 | [diff] [blame] | 508 | .. method:: get_source(fullname) |
| 509 | |
| 510 | A concrete implementation of |
| 511 | :meth:`importlib.abc.InspectLoader.get_source`. Uses |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 512 | :meth:`importlib.abc.ResourceLoader.get_data` and :meth:`source_path` |
| 513 | to get the source code. It tries to guess the source encoding using |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 514 | :func:`tokenize.detect_encoding`. |
Brett Cannon | d43b30b | 2009-03-10 03:29:23 +0000 | [diff] [blame] | 515 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 516 | |
| 517 | .. class:: PyPycLoader |
| 518 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 519 | An abstract base class inheriting from :class:`PyLoader`. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 520 | This ABC is meant to help in creating loaders that support both Python |
| 521 | source and bytecode. |
| 522 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 523 | .. deprecated:: 3.2 |
| 524 | This class has been deprecated in favor of :class:`SourceLoader` and to |
| 525 | properly support :pep:`3147`. If compatibility is required with |
| 526 | Python 3.1, implement both :class:`SourceLoader` and :class:`PyLoader`; |
| 527 | instructions on how to do so are included in the documentation for |
| 528 | :class:`PyLoader`. Do note that this solution will not support |
| 529 | sourceless/bytecode-only loading; only source *and* bytecode loading. |
| 530 | |
Brett Cannon | 1e33156 | 2012-07-02 14:35:34 -0400 | [diff] [blame] | 531 | .. versionchanged:: 3.3 |
| 532 | Updated to parse (but not use) the new source size field in bytecode |
| 533 | files when reading and to write out the field properly when writing. |
| 534 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 535 | .. method:: source_mtime(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 536 | |
| 537 | An abstract method which returns the modification time for the source |
| 538 | code of the specified module. The modification time should be an |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 539 | integer. If there is no source code, return ``None``. If the |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 540 | module cannot be found then :exc:`ImportError` is raised. |
| 541 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 542 | .. method:: bytecode_path(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 543 | |
| 544 | An abstract method which returns the path to the bytecode for the |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 545 | specified module, if it exists. It returns ``None`` |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 546 | if no bytecode exists (yet). |
Brett Cannon | 3e761a9 | 2009-12-10 00:24:21 +0000 | [diff] [blame] | 547 | Raises :exc:`ImportError` if the loader knows it cannot handle the |
| 548 | module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 549 | |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 550 | .. method:: get_filename(fullname) |
| 551 | |
| 552 | A concrete implementation of |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 553 | :meth:`ExecutionLoader.get_filename` that relies on |
| 554 | :meth:`PyLoader.source_path` and :meth:`bytecode_path`. |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 555 | If :meth:`source_path` returns a path, then that value is returned. |
| 556 | Else if :meth:`bytecode_path` returns a path, that path will be |
| 557 | returned. If a path is not available from both methods, |
| 558 | :exc:`ImportError` is raised. |
| 559 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 560 | .. method:: write_bytecode(fullname, bytecode) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 561 | |
| 562 | An abstract method which has the loader write *bytecode* for future |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 563 | use. If the bytecode is written, return ``True``. Return |
| 564 | ``False`` if the bytecode could not be written. This method |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 565 | should not be called if :data:`sys.dont_write_bytecode` is true. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 566 | The *bytecode* argument should be a bytes string or bytes array. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 567 | |
| 568 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 569 | :mod:`importlib.machinery` -- Importers and path hooks |
| 570 | ------------------------------------------------------ |
| 571 | |
| 572 | .. module:: importlib.machinery |
| 573 | :synopsis: Importers and path hooks |
| 574 | |
| 575 | This module contains the various objects that help :keyword:`import` |
| 576 | find and load modules. |
| 577 | |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 578 | .. attribute:: SOURCE_SUFFIXES |
| 579 | |
| 580 | A list of strings representing the recognized file suffixes for source |
| 581 | modules. |
| 582 | |
| 583 | .. versionadded:: 3.3 |
| 584 | |
| 585 | .. attribute:: DEBUG_BYTECODE_SUFFIXES |
| 586 | |
| 587 | A list of strings representing the file suffixes for non-optimized bytecode |
| 588 | modules. |
| 589 | |
| 590 | .. versionadded:: 3.3 |
| 591 | |
| 592 | .. attribute:: OPTIMIZED_BYTECODE_SUFFIXES |
| 593 | |
| 594 | A list of strings representing the file suffixes for optimized bytecode |
| 595 | modules. |
| 596 | |
| 597 | .. versionadded:: 3.3 |
| 598 | |
| 599 | .. attribute:: BYTECODE_SUFFIXES |
| 600 | |
| 601 | A list of strings representing the recognized file suffixes for bytecode |
| 602 | modules. Set to either :attr:`DEBUG_BYTECODE_SUFFIXES` or |
| 603 | :attr:`OPTIMIZED_BYTECODE_SUFFIXES` based on whether ``__debug__`` is true. |
| 604 | |
| 605 | .. versionadded:: 3.3 |
| 606 | |
| 607 | .. attribute:: EXTENSION_SUFFIXES |
| 608 | |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 609 | A list of strings representing the recognized file suffixes for |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 610 | extension modules. |
| 611 | |
| 612 | .. versionadded:: 3.3 |
| 613 | |
Nick Coghlan | c5afd42 | 2012-07-18 23:59:08 +1000 | [diff] [blame] | 614 | .. function:: all_suffixes() |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 615 | |
| 616 | Returns a combined list of strings representing all file suffixes for |
Nick Coghlan | c5afd42 | 2012-07-18 23:59:08 +1000 | [diff] [blame] | 617 | modules recognized by the standard import machinery. This is a |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 618 | helper for code which simply needs to know if a filesystem path |
Nick Coghlan | c5afd42 | 2012-07-18 23:59:08 +1000 | [diff] [blame] | 619 | potentially refers to a module without needing any details on the kind |
| 620 | of module (for example, :func:`inspect.getmodulename`) |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 621 | |
| 622 | .. versionadded:: 3.3 |
| 623 | |
| 624 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 625 | .. class:: BuiltinImporter |
| 626 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 627 | An :term:`importer` for built-in modules. All known built-in modules are |
| 628 | listed in :data:`sys.builtin_module_names`. This class implements the |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 629 | :class:`importlib.abc.MetaPathFinder` and |
| 630 | :class:`importlib.abc.InspectLoader` ABCs. |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 631 | |
| 632 | Only class methods are defined by this class to alleviate the need for |
| 633 | instantiation. |
| 634 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 635 | |
| 636 | .. class:: FrozenImporter |
| 637 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 638 | An :term:`importer` for frozen modules. This class implements the |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 639 | :class:`importlib.abc.MetaPathFinder` and |
| 640 | :class:`importlib.abc.InspectLoader` ABCs. |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 641 | |
| 642 | Only class methods are defined by this class to alleviate the need for |
| 643 | instantiation. |
| 644 | |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 645 | |
Nick Coghlan | ff79486 | 2012-08-02 21:45:24 +1000 | [diff] [blame] | 646 | .. class:: WindowsRegistryFinder |
| 647 | |
| 648 | :term:`Finder` for modules declared in the Windows registry. This class |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame] | 649 | implements the :class:`importlib.abc.Finder` ABC. |
Nick Coghlan | ff79486 | 2012-08-02 21:45:24 +1000 | [diff] [blame] | 650 | |
| 651 | Only class methods are defined by this class to alleviate the need for |
| 652 | instantiation. |
| 653 | |
| 654 | .. versionadded:: 3.3 |
| 655 | |
| 656 | |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 657 | .. class:: PathFinder |
| 658 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 659 | A :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes. |
| 660 | This class implements the :class:`importlib.abc.MetaPathFinder` ABC. |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 661 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 662 | Only class methods are defined by this class to alleviate the need for |
| 663 | instantiation. |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 664 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 665 | .. classmethod:: find_module(fullname, path=None) |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 666 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 667 | Class method that attempts to find a :term:`loader` for the module |
| 668 | specified by *fullname* on :data:`sys.path` or, if defined, on |
| 669 | *path*. For each path entry that is searched, |
| 670 | :data:`sys.path_importer_cache` is checked. If a non-false object is |
| 671 | found then it is used as the :term:`finder` to look for the module |
| 672 | being searched for. If no entry is found in |
| 673 | :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is |
| 674 | searched for a finder for the path entry and, if found, is stored in |
| 675 | :data:`sys.path_importer_cache` along with being queried about the |
| 676 | module. If no finder is ever found then ``None`` is both stored in |
| 677 | the cache and returned. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 678 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 679 | .. classmethod:: invalidate_caches() |
| 680 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 681 | Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all |
| 682 | finders stored in :attr:`sys.path_importer_cache`. |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 683 | |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 684 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 685 | .. class:: FileFinder(path, \*loader_details) |
| 686 | |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 687 | A concrete implementation of :class:`importlib.abc.PathEntryFinder` which |
| 688 | caches results from the file system. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 689 | |
| 690 | The *path* argument is the directory for which the finder is in charge of |
| 691 | searching. |
| 692 | |
Brett Cannon | ac9f2f3 | 2012-08-10 13:47:54 -0400 | [diff] [blame] | 693 | The *loader_details* argument is a variable number of 2-item tuples each |
| 694 | containing a loader and a sequence of file suffixes the loader recognizes. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 695 | |
| 696 | The finder will cache the directory contents as necessary, making stat calls |
| 697 | for each module search to verify the cache is not outdated. Because cache |
| 698 | staleness relies upon the granularity of the operating system's state |
| 699 | information of the file system, there is a potential race condition of |
| 700 | searching for a module, creating a new file, and then searching for the |
| 701 | module the new file represents. If the operations happen fast enough to fit |
| 702 | within the granularity of stat calls, then the module search will fail. To |
| 703 | prevent this from happening, when you create a module dynamically, make sure |
| 704 | to call :func:`importlib.invalidate_caches`. |
| 705 | |
| 706 | .. versionadded:: 3.3 |
| 707 | |
| 708 | .. attribute:: path |
| 709 | |
| 710 | The path the finder will search in. |
| 711 | |
| 712 | .. method:: find_module(fullname) |
| 713 | |
| 714 | Attempt to find the loader to handle *fullname* within :attr:`path`. |
| 715 | |
| 716 | .. method:: invalidate_caches() |
| 717 | |
| 718 | Clear out the internal cache. |
| 719 | |
| 720 | .. classmethod:: path_hook(\*loader_details) |
| 721 | |
| 722 | A class method which returns a closure for use on :attr:`sys.path_hooks`. |
| 723 | An instance of :class:`FileFinder` is returned by the closure using the |
| 724 | path argument given to the closure directly and *loader_details* |
| 725 | indirectly. |
| 726 | |
| 727 | If the argument to the closure is not an existing directory, |
| 728 | :exc:`ImportError` is raised. |
| 729 | |
| 730 | |
| 731 | .. class:: SourceFileLoader(fullname, path) |
| 732 | |
| 733 | A concrete implementation of :class:`importlib.abc.SourceLoader` by |
| 734 | subclassing :class:`importlib.abc.FileLoader` and providing some concrete |
| 735 | implementations of other methods. |
| 736 | |
| 737 | .. versionadded:: 3.3 |
| 738 | |
| 739 | .. attribute:: name |
| 740 | |
| 741 | The name of the module that this loader will handle. |
| 742 | |
| 743 | .. attribute:: path |
| 744 | |
| 745 | The path to the source file. |
| 746 | |
| 747 | .. method:: is_package(fullname) |
| 748 | |
| 749 | Return true if :attr:`path` appears to be for a package. |
| 750 | |
| 751 | .. method:: path_stats(path) |
| 752 | |
| 753 | Concrete implementation of :meth:`importlib.abc.SourceLoader.path_stats`. |
| 754 | |
| 755 | .. method:: set_data(path, data) |
| 756 | |
| 757 | Concrete implementation of :meth:`importlib.abc.SourceLoader.set_data`. |
| 758 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 759 | |
Marc-Andre Lemburg | 4fe29c9 | 2012-04-25 02:31:37 +0200 | [diff] [blame] | 760 | .. class:: SourcelessFileLoader(fullname, path) |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 761 | |
| 762 | A concrete implementation of :class:`importlib.abc.FileLoader` which can |
| 763 | import bytecode files (i.e. no source code files exist). |
| 764 | |
Marc-Andre Lemburg | 4fe29c9 | 2012-04-25 02:31:37 +0200 | [diff] [blame] | 765 | Please note that direct use of bytecode files (and thus not source code |
| 766 | files) inhibits your modules from being usable by all Python |
| 767 | implementations or new versions of Python which change the bytecode |
| 768 | format. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 769 | |
| 770 | .. versionadded:: 3.3 |
| 771 | |
| 772 | .. attribute:: name |
| 773 | |
| 774 | The name of the module the loader will handle. |
| 775 | |
| 776 | .. attribute:: path |
| 777 | |
| 778 | The path to the bytecode file. |
| 779 | |
| 780 | .. method:: is_package(fullname) |
| 781 | |
| 782 | Determines if the module is a package based on :attr:`path`. |
| 783 | |
| 784 | .. method:: get_code(fullname) |
| 785 | |
| 786 | Returns the code object for :attr:`name` created from :attr:`path`. |
| 787 | |
| 788 | .. method:: get_source(fullname) |
| 789 | |
| 790 | Returns ``None`` as bytecode files have no source when this loader is |
| 791 | used. |
| 792 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 793 | |
| 794 | .. class:: ExtensionFileLoader(fullname, path) |
| 795 | |
| 796 | A concrete implementation of :class:`importlib.abc.InspectLoader` for |
| 797 | extension modules. |
| 798 | |
| 799 | The *fullname* argument specifies the name of the module the loader is to |
| 800 | support. The *path* argument is the path to the extension module's file. |
| 801 | |
| 802 | .. versionadded:: 3.3 |
| 803 | |
| 804 | .. attribute:: name |
| 805 | |
| 806 | Name of the module the loader supports. |
| 807 | |
| 808 | .. attribute:: path |
| 809 | |
| 810 | Path to the extension module. |
| 811 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 812 | .. method:: load_module(fullname) |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 813 | |
Brett Cannon | c049952 | 2012-05-11 14:48:41 -0400 | [diff] [blame] | 814 | Loads the extension module if and only if *fullname* is the same as |
| 815 | :attr:`name` or is ``None``. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 816 | |
| 817 | .. method:: is_package(fullname) |
| 818 | |
Brett Cannon | ac9f2f3 | 2012-08-10 13:47:54 -0400 | [diff] [blame] | 819 | Returns ``True`` if the file path points to a package's ``__init__`` |
| 820 | module based on :attr:`EXTENSION_SUFFIXES`. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 821 | |
| 822 | .. method:: get_code(fullname) |
| 823 | |
| 824 | Returns ``None`` as extension modules lack a code object. |
| 825 | |
| 826 | .. method:: get_source(fullname) |
| 827 | |
| 828 | Returns ``None`` as extension modules do not have source code. |
| 829 | |
| 830 | |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 831 | :mod:`importlib.util` -- Utility code for importers |
| 832 | --------------------------------------------------- |
| 833 | |
| 834 | .. module:: importlib.util |
Brett Cannon | 75321e8 | 2012-03-02 11:58:25 -0500 | [diff] [blame] | 835 | :synopsis: Utility code for importers |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 836 | |
| 837 | This module contains the various objects that help in the construction of |
| 838 | an :term:`importer`. |
| 839 | |
Brett Cannon | d200bf5 | 2012-05-13 13:45:09 -0400 | [diff] [blame] | 840 | .. function:: resolve_name(name, package) |
| 841 | |
| 842 | Resolve a relative module name to an absolute one. |
| 843 | |
| 844 | If **name** has no leading dots, then **name** is simply returned. This |
| 845 | allows for usage such as |
| 846 | ``importlib.util.resolve_name('sys', __package__)`` without doing a |
| 847 | check to see if the **package** argument is needed. |
| 848 | |
| 849 | :exc:`ValueError` is raised if **name** is a relative module name but |
| 850 | package is a false value (e.g. ``None`` or the empty string). |
| 851 | :exc:`ValueError` is also raised a relative name would escape its containing |
| 852 | package (e.g. requesting ``..bacon`` from within the ``spam`` package). |
| 853 | |
| 854 | .. versionadded:: 3.3 |
| 855 | |
Georg Brandl | 8a1caa2 | 2010-07-29 16:01:11 +0000 | [diff] [blame] | 856 | .. decorator:: module_for_loader |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 857 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 858 | A :term:`decorator` for a :term:`loader` method, |
| 859 | to handle selecting the proper |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 860 | module object to load with. The decorated method is expected to have a call |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 861 | signature taking two positional arguments |
| 862 | (e.g. ``load_module(self, module)``) for which the second argument |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 863 | will be the module **object** to be used by the loader. |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 864 | Note that the decorator will not work on static methods because of the |
| 865 | assumption of two arguments. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 866 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 867 | The decorated method will take in the **name** of the module to be loaded |
| 868 | as expected for a :term:`loader`. If the module is not found in |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 869 | :data:`sys.modules` then a new one is constructed with its |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 870 | :attr:`__name__` attribute set to **name**, :attr:`__loader__` set to |
| 871 | **self**, and :attr:`__package__` set if |
| 872 | :meth:`importlib.abc.InspectLoader.is_package` is defined for **self** and |
| 873 | does not raise :exc:`ImportError` for **name**. If a new module is not |
| 874 | needed then the module found in :data:`sys.modules` will be passed into the |
| 875 | method. |
| 876 | |
| 877 | If an exception is raised by the decorated method and a module was added to |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 878 | :data:`sys.modules` it will be removed to prevent a partially initialized |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 879 | module from being in left in :data:`sys.modules`. If the module was already |
| 880 | in :data:`sys.modules` then it is left alone. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 881 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 882 | Use of this decorator handles all the details of which module object a |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 883 | loader should initialize as specified by :pep:`302` as best as possible. |
| 884 | |
| 885 | .. versionchanged:: 3.3 |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 886 | :attr:`__loader__` and :attr:`__package__` are automatically set |
| 887 | (when possible). |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 888 | |
Georg Brandl | 8a1caa2 | 2010-07-29 16:01:11 +0000 | [diff] [blame] | 889 | .. decorator:: set_loader |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 890 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 891 | A :term:`decorator` for a :term:`loader` method, |
| 892 | to set the :attr:`__loader__` |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 893 | attribute on loaded modules. If the attribute is already set the decorator |
| 894 | does nothing. It is assumed that the first positional argument to the |
Brett Cannon | 75321e8 | 2012-03-02 11:58:25 -0500 | [diff] [blame] | 895 | wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set to. |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 896 | |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 897 | .. note:: |
| 898 | |
| 899 | It is recommended that :func:`module_for_loader` be used over this |
| 900 | decorator as it subsumes this functionality. |
| 901 | |
| 902 | |
Georg Brandl | 8a1caa2 | 2010-07-29 16:01:11 +0000 | [diff] [blame] | 903 | .. decorator:: set_package |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 904 | |
| 905 | A :term:`decorator` for a :term:`loader` to set the :attr:`__package__` |
| 906 | attribute on the module returned by the loader. If :attr:`__package__` is |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 907 | set and has a value other than ``None`` it will not be changed. |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 908 | Note that the module returned by the loader is what has the attribute |
| 909 | set on and not the module found in :data:`sys.modules`. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 910 | |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 911 | Reliance on this decorator is discouraged when it is possible to set |
Brett Cannon | 75321e8 | 2012-03-02 11:58:25 -0500 | [diff] [blame] | 912 | :attr:`__package__` before importing. By |
| 913 | setting it beforehand the code for the module is executed with the |
| 914 | attribute set and thus can be used by global level code during |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 915 | initialization. |
| 916 | |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 917 | .. note:: |
| 918 | |
| 919 | It is recommended that :func:`module_for_loader` be used over this |
| 920 | decorator as it subsumes this functionality. |