Serhiy Storchaka | 29b0a26 | 2016-12-04 10:20:55 +0200 | [diff] [blame] | 1 | :mod:`importlib` --- The implementation of :keyword:`import` |
| 2 | ============================================================ |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: importlib |
Brett Cannon | 07fbd78 | 2014-02-06 09:46:08 -0500 | [diff] [blame] | 5 | :synopsis: The implementation of the import machinery. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 6 | |
| 7 | .. moduleauthor:: Brett Cannon <brett@python.org> |
| 8 | .. sectionauthor:: Brett Cannon <brett@python.org> |
| 9 | |
| 10 | .. versionadded:: 3.1 |
| 11 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 12 | **Source code:** :source:`Lib/importlib/__init__.py` |
| 13 | |
| 14 | -------------- |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 15 | |
| 16 | Introduction |
| 17 | ------------ |
| 18 | |
Brett Cannon | 07fbd78 | 2014-02-06 09:46:08 -0500 | [diff] [blame] | 19 | The purpose of the :mod:`importlib` package is two-fold. One is to provide the |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 20 | implementation of the :keyword:`import` statement (and thus, by extension, the |
| 21 | :func:`__import__` function) in Python source code. This provides an |
Tarek Ziadé | 434caaa | 2009-05-14 12:48:09 +0000 | [diff] [blame] | 22 | implementation of :keyword:`import` which is portable to any Python |
Brett Cannon | 07fbd78 | 2014-02-06 09:46:08 -0500 | [diff] [blame] | 23 | interpreter. This also provides an implementation which is easier to |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 24 | comprehend than one implemented in a programming language other than Python. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 25 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 26 | Two, the components to implement :keyword:`import` are exposed in this |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 27 | 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] | 28 | generically as an :term:`importer`) to participate in the import process. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 29 | |
| 30 | .. seealso:: |
| 31 | |
| 32 | :ref:`import` |
| 33 | The language reference for the :keyword:`import` statement. |
| 34 | |
Benjamin Peterson | 60dbed1 | 2017-09-05 16:24:39 -0700 | [diff] [blame] | 35 | `Packages specification <https://www.python.org/doc/essays/packages/>`__ |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 36 | Original specification of packages. Some semantics have changed since |
Georg Brandl | 375aec2 | 2011-01-15 17:03:02 +0000 | [diff] [blame] | 37 | the writing of this document (e.g. redirecting based on ``None`` |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 38 | in :data:`sys.modules`). |
| 39 | |
| 40 | The :func:`.__import__` function |
Brett Cannon | 0e13c94 | 2010-06-29 18:26:11 +0000 | [diff] [blame] | 41 | The :keyword:`import` statement is syntactic sugar for this function. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 42 | |
| 43 | :pep:`235` |
| 44 | Import on Case-Insensitive Platforms |
| 45 | |
| 46 | :pep:`263` |
| 47 | Defining Python Source Code Encodings |
| 48 | |
| 49 | :pep:`302` |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 50 | New Import Hooks |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 51 | |
| 52 | :pep:`328` |
| 53 | Imports: Multi-Line and Absolute/Relative |
| 54 | |
| 55 | :pep:`366` |
| 56 | Main module explicit relative imports |
| 57 | |
Eric Snow | 338502b | 2016-05-28 11:56:53 -0600 | [diff] [blame] | 58 | :pep:`420` |
| 59 | Implicit namespace packages |
| 60 | |
Brett Cannon | 07fbd78 | 2014-02-06 09:46:08 -0500 | [diff] [blame] | 61 | :pep:`451` |
| 62 | A ModuleSpec Type for the Import System |
| 63 | |
Nick Coghlan | d5cacbb | 2015-05-23 22:24:10 +1000 | [diff] [blame] | 64 | :pep:`488` |
| 65 | Elimination of PYO files |
| 66 | |
| 67 | :pep:`489` |
| 68 | Multi-phase extension module initialization |
| 69 | |
Benjamin Peterson | 42aa93b | 2017-12-09 10:26:52 -0800 | [diff] [blame] | 70 | :pep:`552` |
| 71 | Deterministic pycs |
| 72 | |
Brett Cannon | 8917d5e | 2010-01-13 19:21:00 +0000 | [diff] [blame] | 73 | :pep:`3120` |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 74 | Using UTF-8 as the Default Source Encoding |
| 75 | |
Brett Cannon | 30b7a90 | 2010-06-27 21:49:22 +0000 | [diff] [blame] | 76 | :pep:`3147` |
| 77 | PYC Repository Directories |
| 78 | |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 79 | |
| 80 | Functions |
| 81 | --------- |
| 82 | |
Brett Cannon | cb4996a | 2012-08-06 16:34:44 -0400 | [diff] [blame] | 83 | .. function:: __import__(name, globals=None, locals=None, fromlist=(), level=0) |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 84 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 85 | An implementation of the built-in :func:`__import__` function. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 86 | |
Brett Cannon | 3fa8422 | 2015-02-20 10:34:20 -0500 | [diff] [blame] | 87 | .. note:: |
| 88 | Programmatic importing of modules should use :func:`import_module` |
| 89 | instead of this function. |
| 90 | |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 91 | .. function:: import_module(name, package=None) |
| 92 | |
Brett Cannon | 33418c8 | 2009-01-22 18:37:20 +0000 | [diff] [blame] | 93 | Import a module. The *name* argument specifies what module to |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 94 | import in absolute or relative terms |
| 95 | (e.g. either ``pkg.mod`` or ``..mod``). If the name is |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 96 | specified in relative terms, then the *package* argument must be set to |
| 97 | 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] | 98 | package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 99 | ``pkg.mod``). |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 100 | |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 101 | The :func:`import_module` function acts as a simplifying wrapper around |
Brett Cannon | 9f4cb1c | 2009-04-01 23:26:47 +0000 | [diff] [blame] | 102 | :func:`importlib.__import__`. This means all semantics of the function are |
Brett Cannon | 3fa8422 | 2015-02-20 10:34:20 -0500 | [diff] [blame] | 103 | derived from :func:`importlib.__import__`. The most important difference |
| 104 | between these two functions is that :func:`import_module` returns the |
| 105 | specified package or module (e.g. ``pkg.mod``), while :func:`__import__` |
| 106 | returns the top-level package or module (e.g. ``pkg``). |
| 107 | |
| 108 | If you are dynamically importing a module that was created since the |
| 109 | interpreter began execution (e.g., created a Python source file), you may |
| 110 | need to call :func:`invalidate_caches` in order for the new module to be |
| 111 | noticed by the import system. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 112 | |
Brett Cannon | 98620d8 | 2013-12-13 13:57:41 -0500 | [diff] [blame] | 113 | .. versionchanged:: 3.3 |
| 114 | Parent packages are automatically imported. |
| 115 | |
Brett Cannon | ee78a2b | 2012-05-12 17:43:17 -0400 | [diff] [blame] | 116 | .. function:: find_loader(name, path=None) |
| 117 | |
| 118 | Find the loader for a module, optionally within the specified *path*. If the |
| 119 | module is in :attr:`sys.modules`, then ``sys.modules[name].__loader__`` is |
Brett Cannon | 3279923 | 2013-03-13 11:09:08 -0700 | [diff] [blame] | 120 | returned (unless the loader would be ``None`` or is not set, in which case |
Brett Cannon | ee78a2b | 2012-05-12 17:43:17 -0400 | [diff] [blame] | 121 | :exc:`ValueError` is raised). Otherwise a search using :attr:`sys.meta_path` |
| 122 | is done. ``None`` is returned if no loader is found. |
| 123 | |
Benjamin Peterson | f7e2ea2 | 2016-09-05 14:02:59 -0700 | [diff] [blame] | 124 | A dotted name does not have its parents implicitly imported as that requires |
Brett Cannon | 56b4ca7 | 2012-11-17 09:30:55 -0500 | [diff] [blame] | 125 | loading them and that may not be desired. To properly import a submodule you |
| 126 | will need to import all parent packages of the submodule and use the correct |
| 127 | argument to *path*. |
Brett Cannon | ee78a2b | 2012-05-12 17:43:17 -0400 | [diff] [blame] | 128 | |
Brett Cannon | 3279923 | 2013-03-13 11:09:08 -0700 | [diff] [blame] | 129 | .. versionadded:: 3.3 |
| 130 | |
| 131 | .. versionchanged:: 3.4 |
| 132 | If ``__loader__`` is not set, raise :exc:`ValueError`, just like when the |
| 133 | attribute is set to ``None``. |
| 134 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 135 | .. deprecated:: 3.4 |
Eric Snow | 6029e08 | 2014-01-25 15:32:46 -0700 | [diff] [blame] | 136 | Use :func:`importlib.util.find_spec` instead. |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 137 | |
Antoine Pitrou | c541f8e | 2012-02-20 01:48:16 +0100 | [diff] [blame] | 138 | .. function:: invalidate_caches() |
| 139 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 140 | Invalidate the internal caches of finders stored at |
| 141 | :data:`sys.meta_path`. If a finder implements ``invalidate_caches()`` then it |
Brett Cannon | 4067aa2 | 2013-04-27 23:20:32 -0400 | [diff] [blame] | 142 | will be called to perform the invalidation. This function should be called |
| 143 | if any modules are created/installed while your program is running to |
| 144 | guarantee all finders will notice the new module's existence. |
Antoine Pitrou | c541f8e | 2012-02-20 01:48:16 +0100 | [diff] [blame] | 145 | |
| 146 | .. versionadded:: 3.3 |
| 147 | |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 148 | .. function:: reload(module) |
| 149 | |
| 150 | Reload a previously imported *module*. The argument must be a module object, |
| 151 | so it must have been successfully imported before. This is useful if you |
| 152 | have edited the module source file using an external editor and want to try |
| 153 | out the new version without leaving the Python interpreter. The return value |
Brett Cannon | 8ad3786 | 2013-10-25 13:52:46 -0400 | [diff] [blame] | 154 | is the module object (which can be different if re-importing causes a |
| 155 | different object to be placed in :data:`sys.modules`). |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 156 | |
Brett Cannon | 8ad3786 | 2013-10-25 13:52:46 -0400 | [diff] [blame] | 157 | When :func:`reload` is executed: |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 158 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 159 | * Python module's code is recompiled and the module-level code re-executed, |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 160 | defining a new set of objects which are bound to names in the module's |
| 161 | dictionary by reusing the :term:`loader` which originally loaded the |
| 162 | module. The ``init`` function of extension modules is not called a second |
| 163 | time. |
| 164 | |
| 165 | * As with all other objects in Python the old objects are only reclaimed |
| 166 | after their reference counts drop to zero. |
| 167 | |
| 168 | * The names in the module namespace are updated to point to any new or |
| 169 | changed objects. |
| 170 | |
| 171 | * Other references to the old objects (such as names external to the module) are |
| 172 | not rebound to refer to the new objects and must be updated in each namespace |
| 173 | where they occur if that is desired. |
| 174 | |
| 175 | There are a number of other caveats: |
| 176 | |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 177 | When a module is reloaded, its dictionary (containing the module's global |
| 178 | variables) is retained. Redefinitions of names will override the old |
| 179 | definitions, so this is generally not a problem. If the new version of a |
| 180 | module does not define a name that was defined by the old version, the old |
| 181 | definition remains. This feature can be used to the module's advantage if it |
| 182 | maintains a global table or cache of objects --- with a :keyword:`try` |
| 183 | statement it can test for the table's presence and skip its initialization if |
| 184 | desired:: |
| 185 | |
| 186 | try: |
| 187 | cache |
| 188 | except NameError: |
| 189 | cache = {} |
| 190 | |
Robert Collins | 1ae28d2 | 2015-08-05 08:20:53 +1200 | [diff] [blame] | 191 | It is generally not very useful to reload built-in or dynamically loaded |
| 192 | modules. Reloading :mod:`sys`, :mod:`__main__`, :mod:`builtins` and other |
| 193 | key modules is not recommended. In many cases extension modules are not |
| 194 | designed to be initialized more than once, and may fail in arbitrary ways |
| 195 | when reloaded. |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 196 | |
| 197 | If a module imports objects from another module using :keyword:`from` ... |
| 198 | :keyword:`import` ..., calling :func:`reload` for the other module does not |
| 199 | redefine the objects imported from it --- one way around this is to |
| 200 | re-execute the :keyword:`from` statement, another is to use :keyword:`import` |
| 201 | and qualified names (*module.name*) instead. |
| 202 | |
| 203 | If a module instantiates instances of a class, reloading the module that |
| 204 | defines the class does not affect the method definitions of the instances --- |
| 205 | they continue to use the old class definition. The same is true for derived |
| 206 | classes. |
| 207 | |
| 208 | .. versionadded:: 3.4 |
Garvit Khatri | 9498782 | 2017-05-25 03:49:50 +0530 | [diff] [blame] | 209 | .. versionchanged:: 3.7 |
| 210 | :exc:`ModuleNotFoundError` is raised when the module being reloaded lacks |
| 211 | a :class:`ModuleSpec`. |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 212 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 213 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 214 | :mod:`importlib.abc` -- Abstract base classes related to import |
| 215 | --------------------------------------------------------------- |
| 216 | |
| 217 | .. module:: importlib.abc |
| 218 | :synopsis: Abstract base classes related to import |
| 219 | |
Terry Jan Reedy | dcb6c88 | 2016-06-22 22:46:34 -0400 | [diff] [blame] | 220 | **Source code:** :source:`Lib/importlib/abc.py` |
| 221 | |
| 222 | -------------- |
| 223 | |
| 224 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 225 | The :mod:`importlib.abc` module contains all of the core abstract base classes |
| 226 | used by :keyword:`import`. Some subclasses of the core abstract base classes |
| 227 | are also provided to help in implementing the core ABCs. |
| 228 | |
Andrew Svetlov | a865654 | 2012-08-13 22:19:01 +0300 | [diff] [blame] | 229 | ABC hierarchy:: |
| 230 | |
| 231 | object |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 232 | +-- Finder (deprecated) |
Andrew Svetlov | a865654 | 2012-08-13 22:19:01 +0300 | [diff] [blame] | 233 | | +-- MetaPathFinder |
| 234 | | +-- PathEntryFinder |
| 235 | +-- Loader |
| 236 | +-- ResourceLoader --------+ |
| 237 | +-- InspectLoader | |
| 238 | +-- ExecutionLoader --+ |
| 239 | +-- FileLoader |
| 240 | +-- SourceLoader |
Andrew Svetlov | a865654 | 2012-08-13 22:19:01 +0300 | [diff] [blame] | 241 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 242 | |
| 243 | .. class:: Finder |
| 244 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 245 | An abstract base class representing a :term:`finder`. |
| 246 | |
| 247 | .. deprecated:: 3.3 |
| 248 | Use :class:`MetaPathFinder` or :class:`PathEntryFinder` instead. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 249 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 250 | .. abstractmethod:: find_module(fullname, path=None) |
Brett Cannon | b46a179 | 2012-02-27 18:15:42 -0500 | [diff] [blame] | 251 | |
Xtreak | c151f78 | 2018-06-16 10:38:31 +0530 | [diff] [blame] | 252 | An abstract method for finding a :term:`loader` for the specified |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 253 | module. Originally specified in :pep:`302`, this method was meant |
| 254 | 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] | 255 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 256 | .. versionchanged:: 3.4 |
| 257 | Returns ``None`` when called instead of raising |
| 258 | :exc:`NotImplementedError`. |
| 259 | |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 260 | |
Brett Cannon | 077ef45 | 2012-08-02 17:50:06 -0400 | [diff] [blame] | 261 | .. class:: MetaPathFinder |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 262 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 263 | An abstract base class representing a :term:`meta path finder`. For |
| 264 | compatibility, this is a subclass of :class:`Finder`. |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 265 | |
| 266 | .. versionadded:: 3.3 |
| 267 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 268 | .. method:: find_spec(fullname, path, target=None) |
| 269 | |
| 270 | An abstract method for finding a :term:`spec <module spec>` for |
| 271 | the specified module. If this is a top-level import, *path* will |
| 272 | be ``None``. Otherwise, this is a search for a subpackage or |
| 273 | module and *path* will be the value of :attr:`__path__` from the |
| 274 | parent package. If a spec cannot be found, ``None`` is returned. |
| 275 | When passed in, ``target`` is a module object that the finder may |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 276 | use to make a more educated guess about what spec to return. |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 277 | |
| 278 | .. versionadded:: 3.4 |
| 279 | |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 280 | .. method:: find_module(fullname, path) |
| 281 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 282 | A legacy method for finding a :term:`loader` for the specified |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 283 | module. If this is a top-level import, *path* will be ``None``. |
Ezio Melotti | 1f67e80 | 2012-10-21 07:24:13 +0300 | [diff] [blame] | 284 | Otherwise, this is a search for a subpackage or module and *path* |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 285 | will be the value of :attr:`__path__` from the parent |
| 286 | package. If a loader cannot be found, ``None`` is returned. |
| 287 | |
Brett Cannon | 8d94229 | 2014-01-07 15:52:42 -0500 | [diff] [blame] | 288 | If :meth:`find_spec` is defined, backwards-compatible functionality is |
| 289 | provided. |
| 290 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 291 | .. versionchanged:: 3.4 |
| 292 | Returns ``None`` when called instead of raising |
Brett Cannon | 8d94229 | 2014-01-07 15:52:42 -0500 | [diff] [blame] | 293 | :exc:`NotImplementedError`. Can use :meth:`find_spec` to provide |
| 294 | functionality. |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 295 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 296 | .. deprecated:: 3.4 |
| 297 | Use :meth:`find_spec` instead. |
| 298 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 299 | .. method:: invalidate_caches() |
| 300 | |
| 301 | An optional method which, when called, should invalidate any internal |
Brett Cannon | a6e8581 | 2012-08-11 19:41:27 -0400 | [diff] [blame] | 302 | cache used by the finder. Used by :func:`importlib.invalidate_caches` |
| 303 | when invalidating the caches of all finders on :data:`sys.meta_path`. |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 304 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 305 | .. versionchanged:: 3.4 |
| 306 | Returns ``None`` when called instead of ``NotImplemented``. |
| 307 | |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 308 | |
Brett Cannon | 077ef45 | 2012-08-02 17:50:06 -0400 | [diff] [blame] | 309 | .. class:: PathEntryFinder |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 310 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 311 | An abstract base class representing a :term:`path entry finder`. Though |
| 312 | it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder`` |
| 313 | is meant for use only within the path-based import subsystem provided |
| 314 | by :class:`PathFinder`. This ABC is a subclass of :class:`Finder` for |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 315 | compatibility reasons only. |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 316 | |
| 317 | .. versionadded:: 3.3 |
| 318 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 319 | .. method:: find_spec(fullname, target=None) |
| 320 | |
| 321 | An abstract method for finding a :term:`spec <module spec>` for |
| 322 | the specified module. The finder will search for the module only |
| 323 | within the :term:`path entry` to which it is assigned. If a spec |
| 324 | cannot be found, ``None`` is returned. When passed in, ``target`` |
| 325 | is a module object that the finder may use to make a more educated |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 326 | guess about what spec to return. |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 327 | |
| 328 | .. versionadded:: 3.4 |
| 329 | |
Brett Cannon | 4067aa2 | 2013-04-27 23:20:32 -0400 | [diff] [blame] | 330 | .. method:: find_loader(fullname) |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 331 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 332 | A legacy method for finding a :term:`loader` for the specified |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 333 | module. Returns a 2-tuple of ``(loader, portion)`` where ``portion`` |
| 334 | is a sequence of file system locations contributing to part of a namespace |
| 335 | package. The loader may be ``None`` while specifying ``portion`` to |
| 336 | signify the contribution of the file system locations to a namespace |
| 337 | package. An empty list can be used for ``portion`` to signify the loader |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 338 | is not part of a namespace package. If ``loader`` is ``None`` and |
| 339 | ``portion`` is the empty list then no loader or location for a namespace |
| 340 | package were found (i.e. failure to find anything for the module). |
| 341 | |
Brett Cannon | 8d94229 | 2014-01-07 15:52:42 -0500 | [diff] [blame] | 342 | If :meth:`find_spec` is defined then backwards-compatible functionality is |
| 343 | provided. |
| 344 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 345 | .. versionchanged:: 3.4 |
| 346 | Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`. |
Brett Cannon | 8d94229 | 2014-01-07 15:52:42 -0500 | [diff] [blame] | 347 | Uses :meth:`find_spec` when available to provide functionality. |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 348 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 349 | .. deprecated:: 3.4 |
| 350 | Use :meth:`find_spec` instead. |
| 351 | |
Brett Cannon | 4067aa2 | 2013-04-27 23:20:32 -0400 | [diff] [blame] | 352 | .. method:: find_module(fullname) |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 353 | |
| 354 | A concrete implementation of :meth:`Finder.find_module` which is |
| 355 | equivalent to ``self.find_loader(fullname)[0]``. |
| 356 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 357 | .. deprecated:: 3.4 |
| 358 | Use :meth:`find_spec` instead. |
| 359 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 360 | .. method:: invalidate_caches() |
| 361 | |
| 362 | An optional method which, when called, should invalidate any internal |
Brett Cannon | a6e8581 | 2012-08-11 19:41:27 -0400 | [diff] [blame] | 363 | cache used by the finder. Used by :meth:`PathFinder.invalidate_caches` |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 364 | when invalidating the caches of all cached finders. |
Brett Cannon | b46a179 | 2012-02-27 18:15:42 -0500 | [diff] [blame] | 365 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 366 | |
| 367 | .. class:: Loader |
| 368 | |
| 369 | An abstract base class for a :term:`loader`. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 370 | See :pep:`302` for the exact definition for a loader. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 371 | |
Barry Warsaw | 997b8c1 | 2018-02-16 10:45:39 -0500 | [diff] [blame] | 372 | Loaders that wish to support resource reading should implement a |
| 373 | ``get_resource_reader(fullname)`` method as specified by |
| 374 | :class:`importlib.abc.ResourceReader`. |
Brett Cannon | bca4218 | 2018-01-12 15:08:59 -0800 | [diff] [blame] | 375 | |
| 376 | .. versionchanged:: 3.7 |
| 377 | Introduced the optional ``get_resource_reader()`` method. |
| 378 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 379 | .. method:: create_module(spec) |
| 380 | |
Brett Cannon | 02d8454 | 2015-01-09 11:39:21 -0500 | [diff] [blame] | 381 | A method that returns the module object to use when |
| 382 | importing a module. This method may return ``None``, |
| 383 | indicating that default module creation semantics should take place. |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 384 | |
| 385 | .. versionadded:: 3.4 |
| 386 | |
Brett Cannon | 02d8454 | 2015-01-09 11:39:21 -0500 | [diff] [blame] | 387 | .. versionchanged:: 3.5 |
| 388 | Starting in Python 3.6, this method will not be optional when |
| 389 | :meth:`exec_module` is defined. |
| 390 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 391 | .. method:: exec_module(module) |
| 392 | |
| 393 | An abstract method that executes the module in its own namespace |
| 394 | when a module is imported or reloaded. The module should already |
Brett Cannon | 696c35e | 2016-06-25 10:58:17 -0700 | [diff] [blame] | 395 | be initialized when ``exec_module()`` is called. When this method exists, |
| 396 | :meth:`~importlib.abc.Loader.create_module` must be defined. |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 397 | |
| 398 | .. versionadded:: 3.4 |
| 399 | |
Brett Cannon | 696c35e | 2016-06-25 10:58:17 -0700 | [diff] [blame] | 400 | .. versionchanged:: 3.6 |
| 401 | :meth:`~importlib.abc.Loader.create_module` must also be defined. |
| 402 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 403 | .. method:: load_module(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 404 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 405 | A legacy method for loading a module. If the module cannot be |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 406 | loaded, :exc:`ImportError` is raised, otherwise the loaded module is |
| 407 | returned. |
| 408 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 409 | If the requested module already exists in :data:`sys.modules`, that |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 410 | module should be used and reloaded. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 411 | Otherwise the loader should create a new module and insert it into |
| 412 | :data:`sys.modules` before any loading begins, to prevent recursion |
| 413 | 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] | 414 | must be removed by the loader from :data:`sys.modules`; modules already |
| 415 | in :data:`sys.modules` before the loader began execution should be left |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 416 | alone (see :func:`importlib.util.module_for_loader`). |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 417 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 418 | The loader should set several attributes on the module. |
| 419 | (Note that some of these attributes can change when a module is |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 420 | reloaded): |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 421 | |
| 422 | - :attr:`__name__` |
| 423 | The name of the module. |
| 424 | |
| 425 | - :attr:`__file__` |
| 426 | The path to where the module data is stored (not set for built-in |
| 427 | modules). |
| 428 | |
Brett Cannon | 2cefb3c | 2013-05-25 11:26:11 -0400 | [diff] [blame] | 429 | - :attr:`__cached__` |
| 430 | The path to where a compiled version of the module is/should be |
| 431 | stored (not set when the attribute would be inappropriate). |
| 432 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 433 | - :attr:`__path__` |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 434 | A list of strings specifying the search path within a |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 435 | package. This attribute is not set on modules. |
| 436 | |
| 437 | - :attr:`__package__` |
| 438 | The parent package for the module/package. If the module is |
| 439 | top-level then it has a value of the empty string. The |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 440 | :func:`importlib.util.module_for_loader` decorator can handle the |
| 441 | details for :attr:`__package__`. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 442 | |
| 443 | - :attr:`__loader__` |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 444 | The loader used to load the module. The |
| 445 | :func:`importlib.util.module_for_loader` decorator can handle the |
| 446 | details for :attr:`__package__`. |
| 447 | |
Brett Cannon | 8d94229 | 2014-01-07 15:52:42 -0500 | [diff] [blame] | 448 | When :meth:`exec_module` is available then backwards-compatible |
| 449 | functionality is provided. |
| 450 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 451 | .. versionchanged:: 3.4 |
| 452 | Raise :exc:`ImportError` when called instead of |
Brett Cannon | 8d94229 | 2014-01-07 15:52:42 -0500 | [diff] [blame] | 453 | :exc:`NotImplementedError`. Functionality provided when |
| 454 | :meth:`exec_module` is available. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 455 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 456 | .. deprecated:: 3.4 |
| 457 | The recommended API for loading a module is :meth:`exec_module` |
Brett Cannon | 02d8454 | 2015-01-09 11:39:21 -0500 | [diff] [blame] | 458 | (and :meth:`create_module`). Loaders should implement |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 459 | it instead of load_module(). The import machinery takes care of |
| 460 | all the other responsibilities of load_module() when exec_module() |
| 461 | is implemented. |
| 462 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 463 | .. method:: module_repr(module) |
| 464 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 465 | A legacy method which when implemented calculates and returns the |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 466 | given module's repr, as a string. The module type's default repr() will |
| 467 | use the result of this method as appropriate. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 468 | |
Georg Brandl | 526575d | 2013-04-11 16:10:13 +0200 | [diff] [blame] | 469 | .. versionadded:: 3.3 |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 470 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 471 | .. versionchanged:: 3.4 |
Georg Brandl | 526575d | 2013-04-11 16:10:13 +0200 | [diff] [blame] | 472 | Made optional instead of an abstractmethod. |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 473 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 474 | .. deprecated:: 3.4 |
| 475 | The import machinery now takes care of this automatically. |
| 476 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 477 | |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 478 | .. class:: ResourceReader |
| 479 | |
Brett Cannon | bca4218 | 2018-01-12 15:08:59 -0800 | [diff] [blame] | 480 | An :term:`abstract base class` to provide the ability to read |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 481 | *resources*. |
| 482 | |
| 483 | From the perspective of this ABC, a *resource* is a binary |
| 484 | artifact that is shipped within a package. Typically this is |
| 485 | something like a data file that lives next to the ``__init__.py`` |
| 486 | file of the package. The purpose of this class is to help abstract |
| 487 | out the accessing of such data files so that it does not matter if |
| 488 | the package and its data file(s) are stored in a e.g. zip file |
| 489 | versus on the file system. |
| 490 | |
| 491 | For any of methods of this class, a *resource* argument is |
Barry Warsaw | deae6b4 | 2017-12-30 15:18:06 -0500 | [diff] [blame] | 492 | expected to be a :term:`path-like object` which represents |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 493 | conceptually just a file name. This means that no subdirectory |
| 494 | paths should be included in the *resource* argument. This is |
Brett Cannon | bca4218 | 2018-01-12 15:08:59 -0800 | [diff] [blame] | 495 | because the location of the package the reader is for, acts as the |
| 496 | "directory". Hence the metaphor for directories and file |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 497 | names is packages and resources, respectively. This is also why |
| 498 | instances of this class are expected to directly correlate to |
| 499 | a specific package (instead of potentially representing multiple |
| 500 | packages or a module). |
| 501 | |
Brett Cannon | bca4218 | 2018-01-12 15:08:59 -0800 | [diff] [blame] | 502 | Loaders that wish to support resource reading are expected to |
| 503 | provide a method called ``get_resource_loader(fullname)`` which |
| 504 | returns an object implementing this ABC's interface. If the module |
| 505 | specified by fullname is not a package, this method should return |
| 506 | :const:`None`. An object compatible with this ABC should only be |
| 507 | returned when the specified module is a package. |
| 508 | |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 509 | .. versionadded:: 3.7 |
| 510 | |
| 511 | .. abstractmethod:: open_resource(resource) |
| 512 | |
| 513 | Returns an opened, :term:`file-like object` for binary reading |
| 514 | of the *resource*. |
| 515 | |
| 516 | If the resource cannot be found, :exc:`FileNotFoundError` is |
| 517 | raised. |
| 518 | |
| 519 | .. abstractmethod:: resource_path(resource) |
| 520 | |
| 521 | Returns the file system path to the *resource*. |
| 522 | |
| 523 | If the resource does not concretely exist on the file system, |
| 524 | raise :exc:`FileNotFoundError`. |
| 525 | |
| 526 | .. abstractmethod:: is_resource(name) |
| 527 | |
| 528 | Returns ``True`` if the named *name* is considered a resource. |
| 529 | :exc:`FileNotFoundError` is raised if *name* does not exist. |
| 530 | |
| 531 | .. abstractmethod:: contents() |
| 532 | |
Brett Cannon | 3ab9365 | 2018-04-30 11:31:45 -0700 | [diff] [blame] | 533 | Returns an :term:`iterable` of strings over the contents of |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 534 | the package. Do note that it is not required that all names |
| 535 | returned by the iterator be actual resources, e.g. it is |
| 536 | acceptable to return names for which :meth:`is_resource` would |
| 537 | be false. |
| 538 | |
| 539 | Allowing non-resource names to be returned is to allow for |
| 540 | situations where how a package and its resources are stored |
| 541 | are known a priori and the non-resource names would be useful. |
| 542 | For instance, returning subdirectory names is allowed so that |
| 543 | when it is known that the package and resources are stored on |
Brett Cannon | bca4218 | 2018-01-12 15:08:59 -0800 | [diff] [blame] | 544 | the file system then those subdirectory names can be used |
| 545 | directly. |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 546 | |
Brett Cannon | 3ab9365 | 2018-04-30 11:31:45 -0700 | [diff] [blame] | 547 | The abstract method returns an iterable of no items. |
Brett Cannon | 4ac5150 | 2017-12-15 16:29:35 -0800 | [diff] [blame] | 548 | |
| 549 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 550 | .. class:: ResourceLoader |
| 551 | |
| 552 | An abstract base class for a :term:`loader` which implements the optional |
| 553 | :pep:`302` protocol for loading arbitrary resources from the storage |
| 554 | back-end. |
| 555 | |
Brett Cannon | bca4218 | 2018-01-12 15:08:59 -0800 | [diff] [blame] | 556 | .. deprecated:: 3.7 |
| 557 | This ABC is deprecated in favour of supporting resource loading |
| 558 | through :class:`importlib.abc.ResourceReader`. |
| 559 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 560 | .. abstractmethod:: get_data(path) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 561 | |
| 562 | 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] | 563 | Loaders that have a file-like storage back-end |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 564 | that allows storing arbitrary data |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 565 | can implement this abstract method to give direct access |
Andrew Svetlov | 08af000 | 2014-04-01 01:13:30 +0300 | [diff] [blame] | 566 | to the data stored. :exc:`OSError` is to be raised if the *path* cannot |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 567 | 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] | 568 | :attr:`__file__` attribute or an item from a package's :attr:`__path__`. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 569 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 570 | .. versionchanged:: 3.4 |
Andrew Svetlov | 08af000 | 2014-04-01 01:13:30 +0300 | [diff] [blame] | 571 | Raises :exc:`OSError` instead of :exc:`NotImplementedError`. |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 572 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 573 | |
| 574 | .. class:: InspectLoader |
| 575 | |
| 576 | 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] | 577 | :pep:`302` protocol for loaders that inspect modules. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 578 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 579 | .. method:: get_code(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 580 | |
R David Murray | 0ae7ae1 | 2014-01-08 18:16:02 -0500 | [diff] [blame] | 581 | Return the code object for a module, or ``None`` if the module does not |
| 582 | have a code object (as would be the case, for example, for a built-in |
| 583 | module). Raise an :exc:`ImportError` if loader cannot find the |
| 584 | requested module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 585 | |
Brett Cannon | 3b62ca8 | 2013-05-27 21:11:04 -0400 | [diff] [blame] | 586 | .. note:: |
| 587 | While the method has a default implementation, it is suggested that |
| 588 | it be overridden if possible for performance. |
| 589 | |
R David Murray | 1b00f25 | 2012-08-15 10:43:58 -0400 | [diff] [blame] | 590 | .. index:: |
| 591 | single: universal newlines; importlib.abc.InspectLoader.get_source method |
| 592 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 593 | .. versionchanged:: 3.4 |
Brett Cannon | 3b62ca8 | 2013-05-27 21:11:04 -0400 | [diff] [blame] | 594 | No longer abstract and a concrete implementation is provided. |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 595 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 596 | .. abstractmethod:: get_source(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 597 | |
| 598 | 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] | 599 | a text string using :term:`universal newlines`, translating all |
R David Murray | ee0a945 | 2012-08-15 11:05:36 -0400 | [diff] [blame] | 600 | recognized line separators into ``'\n'`` characters. Returns ``None`` |
| 601 | if no source is available (e.g. a built-in module). Raises |
| 602 | :exc:`ImportError` if the loader cannot find the module specified. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 603 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 604 | .. versionchanged:: 3.4 |
| 605 | Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. |
| 606 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 607 | .. method:: is_package(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 608 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 609 | An abstract method to return a true value if the module is a package, a |
| 610 | false value otherwise. :exc:`ImportError` is raised if the |
| 611 | :term:`loader` cannot find the module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 612 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 613 | .. versionchanged:: 3.4 |
| 614 | Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. |
| 615 | |
Brett Cannon | 6eaac13 | 2014-05-09 12:28:22 -0400 | [diff] [blame] | 616 | .. staticmethod:: source_to_code(data, path='<string>') |
Brett Cannon | 9ffe85e | 2013-05-26 16:45:10 -0400 | [diff] [blame] | 617 | |
| 618 | Create a code object from Python source. |
| 619 | |
| 620 | The *data* argument can be whatever the :func:`compile` function |
| 621 | supports (i.e. string or bytes). The *path* argument should be |
| 622 | the "path" to where the source code originated from, which can be an |
| 623 | abstract concept (e.g. location in a zip file). |
| 624 | |
Brett Cannon | 6eaac13 | 2014-05-09 12:28:22 -0400 | [diff] [blame] | 625 | With the subsequent code object one can execute it in a module by |
| 626 | running ``exec(code, module.__dict__)``. |
| 627 | |
Brett Cannon | 9ffe85e | 2013-05-26 16:45:10 -0400 | [diff] [blame] | 628 | .. versionadded:: 3.4 |
| 629 | |
Brett Cannon | 6eaac13 | 2014-05-09 12:28:22 -0400 | [diff] [blame] | 630 | .. versionchanged:: 3.5 |
| 631 | Made the method static. |
| 632 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 633 | .. method:: exec_module(module) |
| 634 | |
| 635 | Implementation of :meth:`Loader.exec_module`. |
| 636 | |
| 637 | .. versionadded:: 3.4 |
| 638 | |
Brett Cannon | 0dbb4c7 | 2013-05-31 18:56:47 -0400 | [diff] [blame] | 639 | .. method:: load_module(fullname) |
| 640 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 641 | Implementation of :meth:`Loader.load_module`. |
| 642 | |
| 643 | .. deprecated:: 3.4 |
| 644 | use :meth:`exec_module` instead. |
Brett Cannon | 0dbb4c7 | 2013-05-31 18:56:47 -0400 | [diff] [blame] | 645 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 646 | |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 647 | .. class:: ExecutionLoader |
| 648 | |
| 649 | An abstract base class which inherits from :class:`InspectLoader` that, |
Brett Cannon | 2346029 | 2009-07-20 22:59:00 +0000 | [diff] [blame] | 650 | 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] | 651 | represents an optional :pep:`302` protocol. |
| 652 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 653 | .. abstractmethod:: get_filename(fullname) |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 654 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 655 | 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] | 656 | the specified module. If no path is available, :exc:`ImportError` is |
| 657 | raised. |
| 658 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 659 | If source code is available, then the method should return the path to |
| 660 | the source file, regardless of whether a bytecode was used to load the |
| 661 | module. |
| 662 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 663 | .. versionchanged:: 3.4 |
| 664 | Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. |
| 665 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 666 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 667 | .. class:: FileLoader(fullname, path) |
| 668 | |
| 669 | An abstract base class which inherits from :class:`ResourceLoader` and |
Andrew Svetlov | a60de4f | 2013-02-17 16:55:58 +0200 | [diff] [blame] | 670 | :class:`ExecutionLoader`, providing concrete implementations of |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 671 | :meth:`ResourceLoader.get_data` and :meth:`ExecutionLoader.get_filename`. |
| 672 | |
| 673 | The *fullname* argument is a fully resolved name of the module the loader is |
| 674 | to handle. The *path* argument is the path to the file for the module. |
| 675 | |
| 676 | .. versionadded:: 3.3 |
| 677 | |
| 678 | .. attribute:: name |
| 679 | |
| 680 | The name of the module the loader can handle. |
| 681 | |
| 682 | .. attribute:: path |
| 683 | |
| 684 | Path to the file of the module. |
| 685 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 686 | .. method:: load_module(fullname) |
Brett Cannon | c049952 | 2012-05-11 14:48:41 -0400 | [diff] [blame] | 687 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 688 | Calls super's ``load_module()``. |
Brett Cannon | c049952 | 2012-05-11 14:48:41 -0400 | [diff] [blame] | 689 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 690 | .. deprecated:: 3.4 |
| 691 | Use :meth:`Loader.exec_module` instead. |
| 692 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 693 | .. abstractmethod:: get_filename(fullname) |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 694 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 695 | Returns :attr:`path`. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 696 | |
Berker Peksag | 6e9d2e6 | 2015-12-08 12:14:50 +0200 | [diff] [blame] | 697 | .. abstractmethod:: get_data(path) |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 698 | |
Brett Cannon | 3b62ca8 | 2013-05-27 21:11:04 -0400 | [diff] [blame] | 699 | Reads *path* as a binary file and returns the bytes from it. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 700 | |
| 701 | |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 702 | .. class:: SourceLoader |
| 703 | |
| 704 | An abstract base class for implementing source (and optionally bytecode) |
| 705 | file loading. The class inherits from both :class:`ResourceLoader` and |
| 706 | :class:`ExecutionLoader`, requiring the implementation of: |
| 707 | |
| 708 | * :meth:`ResourceLoader.get_data` |
| 709 | * :meth:`ExecutionLoader.get_filename` |
Brett Cannon | 6dfbff3 | 2010-07-21 09:48:31 +0000 | [diff] [blame] | 710 | Should only return the path to the source file; sourceless |
Brett Cannon | a81d527 | 2013-06-16 19:17:12 -0400 | [diff] [blame] | 711 | loading is not supported. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 712 | |
| 713 | The abstract methods defined by this class are to add optional bytecode |
Brett Cannon | 5650e4f | 2012-11-18 10:03:31 -0500 | [diff] [blame] | 714 | file support. Not implementing these optional methods (or causing them to |
| 715 | raise :exc:`NotImplementedError`) causes the loader to |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 716 | only work with source code. Implementing the methods allows the loader to |
| 717 | work with source *and* bytecode files; it does not allow for *sourceless* |
| 718 | loading where only bytecode is provided. Bytecode files are an |
| 719 | optimization to speed up loading by removing the parsing step of Python's |
| 720 | compiler, and so no bytecode-specific API is exposed. |
| 721 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 722 | .. method:: path_stats(path) |
Antoine Pitrou | 5136ac0 | 2012-01-13 18:52:16 +0100 | [diff] [blame] | 723 | |
| 724 | Optional abstract method which returns a :class:`dict` containing |
Martin Panter | eb99570 | 2016-07-28 01:11:04 +0000 | [diff] [blame] | 725 | metadata about the specified path. Supported dictionary keys are: |
Antoine Pitrou | 5136ac0 | 2012-01-13 18:52:16 +0100 | [diff] [blame] | 726 | |
| 727 | - ``'mtime'`` (mandatory): an integer or floating-point number |
| 728 | representing the modification time of the source code; |
| 729 | - ``'size'`` (optional): the size in bytes of the source code. |
| 730 | |
| 731 | Any other keys in the dictionary are ignored, to allow for future |
Andrew Svetlov | 08af000 | 2014-04-01 01:13:30 +0300 | [diff] [blame] | 732 | extensions. If the path cannot be handled, :exc:`OSError` is raised. |
Antoine Pitrou | 5136ac0 | 2012-01-13 18:52:16 +0100 | [diff] [blame] | 733 | |
| 734 | .. versionadded:: 3.3 |
| 735 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 736 | .. versionchanged:: 3.4 |
Andrew Svetlov | 08af000 | 2014-04-01 01:13:30 +0300 | [diff] [blame] | 737 | Raise :exc:`OSError` instead of :exc:`NotImplementedError`. |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 738 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 739 | .. method:: path_mtime(path) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 740 | |
| 741 | Optional abstract method which returns the modification time for the |
| 742 | specified path. |
| 743 | |
Antoine Pitrou | 5136ac0 | 2012-01-13 18:52:16 +0100 | [diff] [blame] | 744 | .. deprecated:: 3.3 |
| 745 | This method is deprecated in favour of :meth:`path_stats`. You don't |
| 746 | have to implement it, but it is still available for compatibility |
Andrew Svetlov | 08af000 | 2014-04-01 01:13:30 +0300 | [diff] [blame] | 747 | purposes. Raise :exc:`OSError` if the path cannot be handled. |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 748 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 749 | .. versionchanged:: 3.4 |
Andrew Svetlov | 08af000 | 2014-04-01 01:13:30 +0300 | [diff] [blame] | 750 | Raise :exc:`OSError` instead of :exc:`NotImplementedError`. |
Antoine Pitrou | 5136ac0 | 2012-01-13 18:52:16 +0100 | [diff] [blame] | 751 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 752 | .. method:: set_data(path, data) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 753 | |
| 754 | Optional abstract method which writes the specified bytes to a file |
Brett Cannon | 61b1425 | 2010-07-03 21:48:25 +0000 | [diff] [blame] | 755 | path. Any intermediate directories which do not exist are to be created |
| 756 | automatically. |
| 757 | |
| 758 | When writing to the path fails because the path is read-only |
Brett Cannon | 2cefb3c | 2013-05-25 11:26:11 -0400 | [diff] [blame] | 759 | (:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the |
| 760 | exception. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 761 | |
Brett Cannon | 100883f | 2013-04-09 16:59:39 -0400 | [diff] [blame] | 762 | .. versionchanged:: 3.4 |
| 763 | No longer raises :exc:`NotImplementedError` when called. |
| 764 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 765 | .. method:: get_code(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 766 | |
| 767 | Concrete implementation of :meth:`InspectLoader.get_code`. |
| 768 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 769 | .. method:: exec_module(module) |
| 770 | |
| 771 | Concrete implementation of :meth:`Loader.exec_module`. |
| 772 | |
Andrés Delfino | 65b5ef0 | 2018-08-12 03:50:46 -0300 | [diff] [blame] | 773 | .. versionadded:: 3.4 |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 774 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 775 | .. method:: load_module(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 776 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 777 | Concrete implementation of :meth:`Loader.load_module`. |
| 778 | |
| 779 | .. deprecated:: 3.4 |
| 780 | Use :meth:`exec_module` instead. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 781 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 782 | .. method:: get_source(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 783 | |
| 784 | Concrete implementation of :meth:`InspectLoader.get_source`. |
| 785 | |
Brett Cannon | 773468f | 2012-08-02 17:35:34 -0400 | [diff] [blame] | 786 | .. method:: is_package(fullname) |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 787 | |
| 788 | Concrete implementation of :meth:`InspectLoader.is_package`. A module |
Brett Cannon | ea0b823 | 2012-06-15 20:00:53 -0400 | [diff] [blame] | 789 | is determined to be a package if its file path (as provided by |
| 790 | :meth:`ExecutionLoader.get_filename`) is a file named |
| 791 | ``__init__`` when the file extension is removed **and** the module name |
| 792 | itself does not end in ``__init__``. |
Brett Cannon | f23e374 | 2010-06-27 23:57:46 +0000 | [diff] [blame] | 793 | |
Brett Cannon | 6919427 | 2009-07-20 04:23:48 +0000 | [diff] [blame] | 794 | |
Barry Warsaw | deae6b4 | 2017-12-30 15:18:06 -0500 | [diff] [blame] | 795 | :mod:`importlib.resources` -- Resources |
| 796 | --------------------------------------- |
| 797 | |
| 798 | .. module:: importlib.resources |
| 799 | :synopsis: Package resource reading, opening, and access |
| 800 | |
| 801 | **Source code:** :source:`Lib/importlib/resources.py` |
| 802 | |
| 803 | -------------- |
| 804 | |
| 805 | .. versionadded:: 3.7 |
| 806 | |
| 807 | This module leverages Python's import system to provide access to *resources* |
| 808 | within *packages*. If you can import a package, you can access resources |
| 809 | within that package. Resources can be opened or read, in either binary or |
| 810 | text mode. |
| 811 | |
| 812 | Resources are roughly akin to files inside directories, though it's important |
| 813 | to keep in mind that this is just a metaphor. Resources and packages **do |
| 814 | not** have to exist as physical files and directories on the file system. |
| 815 | |
Barry Warsaw | 997b8c1 | 2018-02-16 10:45:39 -0500 | [diff] [blame] | 816 | .. note:: |
| 817 | |
| 818 | This module provides functionality similar to `pkg_resources |
| 819 | <https://setuptools.readthedocs.io/en/latest/pkg_resources.html>`_ `Basic |
| 820 | Resource Access |
| 821 | <http://setuptools.readthedocs.io/en/latest/pkg_resources.html#basic-resource-access>`_ |
| 822 | without the performance overhead of that package. This makes reading |
| 823 | resources included in packages easier, with more stable and consistent |
| 824 | semantics. |
| 825 | |
| 826 | The standalone backport of this module provides more information |
| 827 | on `using importlib.resources |
| 828 | <http://importlib-resources.readthedocs.io/en/latest/using.html>`_ and |
| 829 | `migrating from pkg_resources to importlib.resources |
| 830 | <http://importlib-resources.readthedocs.io/en/latest/migration.html>`_. |
| 831 | |
| 832 | Loaders that wish to support resource reading should implement a |
| 833 | ``get_resource_reader(fullname)`` method as specified by |
| 834 | :class:`importlib.abc.ResourceReader`. |
Barry Warsaw | deae6b4 | 2017-12-30 15:18:06 -0500 | [diff] [blame] | 835 | |
| 836 | The following types are defined. |
| 837 | |
| 838 | .. data:: Package |
| 839 | |
| 840 | The ``Package`` type is defined as ``Union[str, ModuleType]``. This means |
| 841 | that where the function describes accepting a ``Package``, you can pass in |
| 842 | either a string or a module. Module objects must have a resolvable |
| 843 | ``__spec__.submodule_search_locations`` that is not ``None``. |
| 844 | |
| 845 | .. data:: Resource |
| 846 | |
| 847 | This type describes the resource names passed into the various functions |
| 848 | in this package. This is defined as ``Union[str, os.PathLike]``. |
| 849 | |
| 850 | |
| 851 | The following functions are available. |
| 852 | |
| 853 | .. function:: open_binary(package, resource) |
| 854 | |
| 855 | Open for binary reading the *resource* within *package*. |
| 856 | |
| 857 | *package* is either a name or a module object which conforms to the |
| 858 | ``Package`` requirements. *resource* is the name of the resource to open |
| 859 | within *package*; it may not contain path separators and it may not have |
| 860 | sub-resources (i.e. it cannot be a directory). This function returns a |
| 861 | ``typing.BinaryIO`` instance, a binary I/O stream open for reading. |
| 862 | |
| 863 | |
| 864 | .. function:: open_text(package, resource, encoding='utf-8', errors='strict') |
| 865 | |
| 866 | Open for text reading the *resource* within *package*. By default, the |
| 867 | resource is opened for reading as UTF-8. |
| 868 | |
| 869 | *package* is either a name or a module object which conforms to the |
| 870 | ``Package`` requirements. *resource* is the name of the resource to open |
| 871 | within *package*; it may not contain path separators and it may not have |
| 872 | sub-resources (i.e. it cannot be a directory). *encoding* and *errors* |
| 873 | have the same meaning as with built-in :func:`open`. |
| 874 | |
| 875 | This function returns a ``typing.TextIO`` instance, a text I/O stream open |
| 876 | for reading. |
| 877 | |
| 878 | |
| 879 | .. function:: read_binary(package, resource) |
| 880 | |
| 881 | Read and return the contents of the *resource* within *package* as |
| 882 | ``bytes``. |
| 883 | |
| 884 | *package* is either a name or a module object which conforms to the |
| 885 | ``Package`` requirements. *resource* is the name of the resource to open |
| 886 | within *package*; it may not contain path separators and it may not have |
| 887 | sub-resources (i.e. it cannot be a directory). This function returns the |
| 888 | contents of the resource as :class:`bytes`. |
| 889 | |
| 890 | |
| 891 | .. function:: read_text(package, resource, encoding='utf-8', errors='strict') |
| 892 | |
| 893 | Read and return the contents of *resource* within *package* as a ``str``. |
| 894 | By default, the contents are read as strict UTF-8. |
| 895 | |
| 896 | *package* is either a name or a module object which conforms to the |
| 897 | ``Package`` requirements. *resource* is the name of the resource to open |
| 898 | within *package*; it may not contain path separators and it may not have |
| 899 | sub-resources (i.e. it cannot be a directory). *encoding* and *errors* |
| 900 | have the same meaning as with built-in :func:`open`. This function |
| 901 | returns the contents of the resource as :class:`str`. |
| 902 | |
| 903 | |
| 904 | .. function:: path(package, resource) |
| 905 | |
| 906 | Return the path to the *resource* as an actual file system path. This |
| 907 | function returns a context manager for use in a :keyword:`with` statement. |
| 908 | The context manager provides a :class:`pathlib.Path` object. |
| 909 | |
| 910 | Exiting the context manager cleans up any temporary file created when the |
| 911 | resource needs to be extracted from e.g. a zip file. |
| 912 | |
| 913 | *package* is either a name or a module object which conforms to the |
| 914 | ``Package`` requirements. *resource* is the name of the resource to open |
| 915 | within *package*; it may not contain path separators and it may not have |
| 916 | sub-resources (i.e. it cannot be a directory). |
| 917 | |
| 918 | |
| 919 | .. function:: is_resource(package, name) |
| 920 | |
| 921 | Return ``True`` if there is a resource named *name* in the package, |
| 922 | otherwise ``False``. Remember that directories are *not* resources! |
| 923 | *package* is either a name or a module object which conforms to the |
| 924 | ``Package`` requirements. |
| 925 | |
| 926 | |
| 927 | .. function:: contents(package) |
| 928 | |
Brett Cannon | 3ab9365 | 2018-04-30 11:31:45 -0700 | [diff] [blame] | 929 | Return an iterable over the named items within the package. The iterable |
Barry Warsaw | deae6b4 | 2017-12-30 15:18:06 -0500 | [diff] [blame] | 930 | returns :class:`str` resources (e.g. files) and non-resources |
Brett Cannon | 3ab9365 | 2018-04-30 11:31:45 -0700 | [diff] [blame] | 931 | (e.g. directories). The iterable does not recurse into subdirectories. |
Barry Warsaw | deae6b4 | 2017-12-30 15:18:06 -0500 | [diff] [blame] | 932 | |
| 933 | *package* is either a name or a module object which conforms to the |
| 934 | ``Package`` requirements. |
| 935 | |
| 936 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 937 | :mod:`importlib.machinery` -- Importers and path hooks |
| 938 | ------------------------------------------------------ |
| 939 | |
| 940 | .. module:: importlib.machinery |
| 941 | :synopsis: Importers and path hooks |
| 942 | |
Terry Jan Reedy | dcb6c88 | 2016-06-22 22:46:34 -0400 | [diff] [blame] | 943 | **Source code:** :source:`Lib/importlib/machinery.py` |
| 944 | |
| 945 | -------------- |
| 946 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 947 | This module contains the various objects that help :keyword:`import` |
| 948 | find and load modules. |
| 949 | |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 950 | .. attribute:: SOURCE_SUFFIXES |
| 951 | |
| 952 | A list of strings representing the recognized file suffixes for source |
| 953 | modules. |
| 954 | |
| 955 | .. versionadded:: 3.3 |
| 956 | |
| 957 | .. attribute:: DEBUG_BYTECODE_SUFFIXES |
| 958 | |
| 959 | A list of strings representing the file suffixes for non-optimized bytecode |
| 960 | modules. |
| 961 | |
| 962 | .. versionadded:: 3.3 |
| 963 | |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 964 | .. deprecated:: 3.5 |
| 965 | Use :attr:`BYTECODE_SUFFIXES` instead. |
| 966 | |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 967 | .. attribute:: OPTIMIZED_BYTECODE_SUFFIXES |
| 968 | |
| 969 | A list of strings representing the file suffixes for optimized bytecode |
| 970 | modules. |
| 971 | |
| 972 | .. versionadded:: 3.3 |
| 973 | |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 974 | .. deprecated:: 3.5 |
| 975 | Use :attr:`BYTECODE_SUFFIXES` instead. |
| 976 | |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 977 | .. attribute:: BYTECODE_SUFFIXES |
| 978 | |
| 979 | A list of strings representing the recognized file suffixes for bytecode |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 980 | modules (including the leading dot). |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 981 | |
| 982 | .. versionadded:: 3.3 |
| 983 | |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 984 | .. versionchanged:: 3.5 |
| 985 | The value is no longer dependent on ``__debug__``. |
| 986 | |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 987 | .. attribute:: EXTENSION_SUFFIXES |
| 988 | |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 989 | A list of strings representing the recognized file suffixes for |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 990 | extension modules. |
| 991 | |
| 992 | .. versionadded:: 3.3 |
| 993 | |
Nick Coghlan | c5afd42 | 2012-07-18 23:59:08 +1000 | [diff] [blame] | 994 | .. function:: all_suffixes() |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 995 | |
| 996 | Returns a combined list of strings representing all file suffixes for |
Nick Coghlan | c5afd42 | 2012-07-18 23:59:08 +1000 | [diff] [blame] | 997 | modules recognized by the standard import machinery. This is a |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 998 | helper for code which simply needs to know if a filesystem path |
Nick Coghlan | c5afd42 | 2012-07-18 23:59:08 +1000 | [diff] [blame] | 999 | potentially refers to a module without needing any details on the kind |
Martin Panter | d21e0b5 | 2015-10-10 10:36:22 +0000 | [diff] [blame] | 1000 | of module (for example, :func:`inspect.getmodulename`). |
Nick Coghlan | 76e0770 | 2012-07-18 23:14:57 +1000 | [diff] [blame] | 1001 | |
| 1002 | .. versionadded:: 3.3 |
| 1003 | |
| 1004 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 1005 | .. class:: BuiltinImporter |
| 1006 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 1007 | An :term:`importer` for built-in modules. All known built-in modules are |
| 1008 | listed in :data:`sys.builtin_module_names`. This class implements the |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 1009 | :class:`importlib.abc.MetaPathFinder` and |
| 1010 | :class:`importlib.abc.InspectLoader` ABCs. |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 1011 | |
| 1012 | Only class methods are defined by this class to alleviate the need for |
| 1013 | instantiation. |
| 1014 | |
Nick Coghlan | d5cacbb | 2015-05-23 22:24:10 +1000 | [diff] [blame] | 1015 | .. versionchanged:: 3.5 |
| 1016 | As part of :pep:`489`, the builtin importer now implements |
| 1017 | :meth:`Loader.create_module` and :meth:`Loader.exec_module` |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1018 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 1019 | |
| 1020 | .. class:: FrozenImporter |
| 1021 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 1022 | An :term:`importer` for frozen modules. This class implements the |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 1023 | :class:`importlib.abc.MetaPathFinder` and |
| 1024 | :class:`importlib.abc.InspectLoader` ABCs. |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 1025 | |
| 1026 | Only class methods are defined by this class to alleviate the need for |
| 1027 | instantiation. |
| 1028 | |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 1029 | |
Nick Coghlan | ff79486 | 2012-08-02 21:45:24 +1000 | [diff] [blame] | 1030 | .. class:: WindowsRegistryFinder |
| 1031 | |
| 1032 | :term:`Finder` for modules declared in the Windows registry. This class |
Himanshu Lakhara | 5cbb841 | 2018-03-24 02:56:35 +0530 | [diff] [blame] | 1033 | implements the :class:`importlib.abc.MetaPathFinder` ABC. |
Nick Coghlan | ff79486 | 2012-08-02 21:45:24 +1000 | [diff] [blame] | 1034 | |
| 1035 | Only class methods are defined by this class to alleviate the need for |
| 1036 | instantiation. |
| 1037 | |
| 1038 | .. versionadded:: 3.3 |
| 1039 | |
Steve Dower | 2036742 | 2016-12-07 13:02:27 -0800 | [diff] [blame] | 1040 | .. deprecated:: 3.6 |
| 1041 | Use :mod:`site` configuration instead. Future versions of Python may |
| 1042 | not enable this finder by default. |
| 1043 | |
Nick Coghlan | ff79486 | 2012-08-02 21:45:24 +1000 | [diff] [blame] | 1044 | |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 1045 | .. class:: PathFinder |
| 1046 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 1047 | A :term:`Finder` for :data:`sys.path` and package ``__path__`` attributes. |
| 1048 | This class implements the :class:`importlib.abc.MetaPathFinder` ABC. |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 1049 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 1050 | Only class methods are defined by this class to alleviate the need for |
| 1051 | instantiation. |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 1052 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1053 | .. classmethod:: find_spec(fullname, path=None, target=None) |
| 1054 | |
| 1055 | Class method that attempts to find a :term:`spec <module spec>` |
| 1056 | for the module specified by *fullname* on :data:`sys.path` or, if |
| 1057 | defined, on *path*. For each path entry that is searched, |
| 1058 | :data:`sys.path_importer_cache` is checked. If a non-false object |
| 1059 | is found then it is used as the :term:`path entry finder` to look |
| 1060 | for the module being searched for. If no entry is found in |
| 1061 | :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is |
| 1062 | searched for a finder for the path entry and, if found, is stored |
| 1063 | in :data:`sys.path_importer_cache` along with being queried about |
| 1064 | the module. If no finder is ever found then ``None`` is both |
| 1065 | stored in the cache and returned. |
| 1066 | |
| 1067 | .. versionadded:: 3.4 |
| 1068 | |
Brett Cannon | b6e2556 | 2014-11-21 12:19:28 -0500 | [diff] [blame] | 1069 | .. versionchanged:: 3.5 |
| 1070 | If the current working directory -- represented by an empty string -- |
| 1071 | is no longer valid then ``None`` is returned but no value is cached |
| 1072 | in :data:`sys.path_importer_cache`. |
| 1073 | |
Brett Cannon | 1b79918 | 2012-08-17 14:08:24 -0400 | [diff] [blame] | 1074 | .. classmethod:: find_module(fullname, path=None) |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 1075 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1076 | A legacy wrapper around :meth:`find_spec`. |
| 1077 | |
| 1078 | .. deprecated:: 3.4 |
| 1079 | Use :meth:`find_spec` instead. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1080 | |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 1081 | .. classmethod:: invalidate_caches() |
| 1082 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1083 | Calls :meth:`importlib.abc.PathEntryFinder.invalidate_caches` on all |
Brett Cannon | 9e2be60 | 2018-04-06 16:10:18 -0700 | [diff] [blame] | 1084 | finders stored in :data:`sys.path_importer_cache` that define the method. |
| 1085 | Otherwise entries in :data:`sys.path_importer_cache` set to ``None`` are |
| 1086 | deleted. |
| 1087 | |
| 1088 | .. versionchanged:: 3.7 |
| 1089 | Entries of ``None`` in :data:`sys.path_importer_cache` are deleted. |
Brett Cannon | f4dc920 | 2012-08-10 12:21:12 -0400 | [diff] [blame] | 1090 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1091 | .. versionchanged:: 3.4 |
| 1092 | Calls objects in :data:`sys.path_hooks` with the current working |
| 1093 | directory for ``''`` (i.e. the empty string). |
Brett Cannon | 27e27f7 | 2013-10-18 11:39:04 -0400 | [diff] [blame] | 1094 | |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1095 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1096 | .. class:: FileFinder(path, \*loader_details) |
| 1097 | |
Nick Coghlan | 8a9080f | 2012-08-02 21:26:03 +1000 | [diff] [blame] | 1098 | A concrete implementation of :class:`importlib.abc.PathEntryFinder` which |
| 1099 | caches results from the file system. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1100 | |
| 1101 | The *path* argument is the directory for which the finder is in charge of |
| 1102 | searching. |
| 1103 | |
Brett Cannon | ac9f2f3 | 2012-08-10 13:47:54 -0400 | [diff] [blame] | 1104 | The *loader_details* argument is a variable number of 2-item tuples each |
| 1105 | containing a loader and a sequence of file suffixes the loader recognizes. |
Brett Cannon | 29b2f17 | 2013-06-21 18:31:55 -0400 | [diff] [blame] | 1106 | The loaders are expected to be callables which accept two arguments of |
| 1107 | the module's name and the path to the file found. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1108 | |
| 1109 | The finder will cache the directory contents as necessary, making stat calls |
| 1110 | for each module search to verify the cache is not outdated. Because cache |
| 1111 | staleness relies upon the granularity of the operating system's state |
| 1112 | information of the file system, there is a potential race condition of |
| 1113 | searching for a module, creating a new file, and then searching for the |
| 1114 | module the new file represents. If the operations happen fast enough to fit |
| 1115 | within the granularity of stat calls, then the module search will fail. To |
| 1116 | prevent this from happening, when you create a module dynamically, make sure |
| 1117 | to call :func:`importlib.invalidate_caches`. |
| 1118 | |
| 1119 | .. versionadded:: 3.3 |
| 1120 | |
| 1121 | .. attribute:: path |
| 1122 | |
| 1123 | The path the finder will search in. |
| 1124 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1125 | .. method:: find_spec(fullname, target=None) |
| 1126 | |
| 1127 | Attempt to find the spec to handle *fullname* within :attr:`path`. |
| 1128 | |
| 1129 | .. versionadded:: 3.4 |
| 1130 | |
Brett Cannon | 1d75382 | 2013-06-16 19:06:55 -0400 | [diff] [blame] | 1131 | .. method:: find_loader(fullname) |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1132 | |
| 1133 | Attempt to find the loader to handle *fullname* within :attr:`path`. |
| 1134 | |
| 1135 | .. method:: invalidate_caches() |
| 1136 | |
| 1137 | Clear out the internal cache. |
| 1138 | |
| 1139 | .. classmethod:: path_hook(\*loader_details) |
| 1140 | |
| 1141 | A class method which returns a closure for use on :attr:`sys.path_hooks`. |
| 1142 | An instance of :class:`FileFinder` is returned by the closure using the |
| 1143 | path argument given to the closure directly and *loader_details* |
| 1144 | indirectly. |
| 1145 | |
| 1146 | If the argument to the closure is not an existing directory, |
| 1147 | :exc:`ImportError` is raised. |
| 1148 | |
| 1149 | |
| 1150 | .. class:: SourceFileLoader(fullname, path) |
| 1151 | |
| 1152 | A concrete implementation of :class:`importlib.abc.SourceLoader` by |
| 1153 | subclassing :class:`importlib.abc.FileLoader` and providing some concrete |
| 1154 | implementations of other methods. |
| 1155 | |
| 1156 | .. versionadded:: 3.3 |
| 1157 | |
| 1158 | .. attribute:: name |
| 1159 | |
| 1160 | The name of the module that this loader will handle. |
| 1161 | |
| 1162 | .. attribute:: path |
| 1163 | |
| 1164 | The path to the source file. |
| 1165 | |
| 1166 | .. method:: is_package(fullname) |
| 1167 | |
| 1168 | Return true if :attr:`path` appears to be for a package. |
| 1169 | |
| 1170 | .. method:: path_stats(path) |
| 1171 | |
| 1172 | Concrete implementation of :meth:`importlib.abc.SourceLoader.path_stats`. |
| 1173 | |
| 1174 | .. method:: set_data(path, data) |
| 1175 | |
| 1176 | Concrete implementation of :meth:`importlib.abc.SourceLoader.set_data`. |
| 1177 | |
Brett Cannon | 062fcac | 2014-05-09 11:55:49 -0400 | [diff] [blame] | 1178 | .. method:: load_module(name=None) |
| 1179 | |
| 1180 | Concrete implementation of :meth:`importlib.abc.Loader.load_module` where |
| 1181 | specifying the name of the module to load is optional. |
| 1182 | |
Brett Cannon | eae3079 | 2015-12-28 17:55:27 -0800 | [diff] [blame] | 1183 | .. deprecated:: 3.6 |
| 1184 | |
| 1185 | Use :meth:`importlib.abc.Loader.exec_module` instead. |
| 1186 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1187 | |
Marc-Andre Lemburg | 4fe29c9 | 2012-04-25 02:31:37 +0200 | [diff] [blame] | 1188 | .. class:: SourcelessFileLoader(fullname, path) |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1189 | |
| 1190 | A concrete implementation of :class:`importlib.abc.FileLoader` which can |
| 1191 | import bytecode files (i.e. no source code files exist). |
| 1192 | |
Marc-Andre Lemburg | 4fe29c9 | 2012-04-25 02:31:37 +0200 | [diff] [blame] | 1193 | Please note that direct use of bytecode files (and thus not source code |
| 1194 | files) inhibits your modules from being usable by all Python |
| 1195 | implementations or new versions of Python which change the bytecode |
| 1196 | format. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1197 | |
| 1198 | .. versionadded:: 3.3 |
| 1199 | |
| 1200 | .. attribute:: name |
| 1201 | |
| 1202 | The name of the module the loader will handle. |
| 1203 | |
| 1204 | .. attribute:: path |
| 1205 | |
| 1206 | The path to the bytecode file. |
| 1207 | |
| 1208 | .. method:: is_package(fullname) |
| 1209 | |
| 1210 | Determines if the module is a package based on :attr:`path`. |
| 1211 | |
| 1212 | .. method:: get_code(fullname) |
| 1213 | |
| 1214 | Returns the code object for :attr:`name` created from :attr:`path`. |
| 1215 | |
| 1216 | .. method:: get_source(fullname) |
| 1217 | |
| 1218 | Returns ``None`` as bytecode files have no source when this loader is |
| 1219 | used. |
| 1220 | |
Brett Cannon | 062fcac | 2014-05-09 11:55:49 -0400 | [diff] [blame] | 1221 | .. method:: load_module(name=None) |
| 1222 | |
| 1223 | Concrete implementation of :meth:`importlib.abc.Loader.load_module` where |
| 1224 | specifying the name of the module to load is optional. |
| 1225 | |
Brett Cannon | eae3079 | 2015-12-28 17:55:27 -0800 | [diff] [blame] | 1226 | .. deprecated:: 3.6 |
| 1227 | |
| 1228 | Use :meth:`importlib.abc.Loader.exec_module` instead. |
| 1229 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1230 | |
| 1231 | .. class:: ExtensionFileLoader(fullname, path) |
| 1232 | |
Eric Snow | 5179445 | 2013-10-03 12:08:55 -0600 | [diff] [blame] | 1233 | A concrete implementation of :class:`importlib.abc.ExecutionLoader` for |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1234 | extension modules. |
| 1235 | |
| 1236 | The *fullname* argument specifies the name of the module the loader is to |
| 1237 | support. The *path* argument is the path to the extension module's file. |
| 1238 | |
| 1239 | .. versionadded:: 3.3 |
| 1240 | |
| 1241 | .. attribute:: name |
| 1242 | |
| 1243 | Name of the module the loader supports. |
| 1244 | |
| 1245 | .. attribute:: path |
| 1246 | |
| 1247 | Path to the extension module. |
| 1248 | |
Nick Coghlan | d5cacbb | 2015-05-23 22:24:10 +1000 | [diff] [blame] | 1249 | .. method:: create_module(spec) |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1250 | |
Nick Coghlan | d5cacbb | 2015-05-23 22:24:10 +1000 | [diff] [blame] | 1251 | Creates the module object from the given specification in accordance |
| 1252 | with :pep:`489`. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1253 | |
Nick Coghlan | d5cacbb | 2015-05-23 22:24:10 +1000 | [diff] [blame] | 1254 | .. versionadded:: 3.5 |
| 1255 | |
| 1256 | .. method:: exec_module(module) |
| 1257 | |
| 1258 | Initializes the given module object in accordance with :pep:`489`. |
| 1259 | |
| 1260 | .. versionadded:: 3.5 |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1261 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1262 | .. method:: is_package(fullname) |
| 1263 | |
Brett Cannon | ac9f2f3 | 2012-08-10 13:47:54 -0400 | [diff] [blame] | 1264 | Returns ``True`` if the file path points to a package's ``__init__`` |
| 1265 | module based on :attr:`EXTENSION_SUFFIXES`. |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1266 | |
| 1267 | .. method:: get_code(fullname) |
| 1268 | |
| 1269 | Returns ``None`` as extension modules lack a code object. |
| 1270 | |
| 1271 | .. method:: get_source(fullname) |
| 1272 | |
| 1273 | Returns ``None`` as extension modules do not have source code. |
| 1274 | |
Eric Snow | 5179445 | 2013-10-03 12:08:55 -0600 | [diff] [blame] | 1275 | .. method:: get_filename(fullname) |
| 1276 | |
| 1277 | Returns :attr:`path`. |
| 1278 | |
Eric Snow | dcd01b4 | 2013-10-04 20:35:34 -0600 | [diff] [blame] | 1279 | .. versionadded:: 3.4 |
| 1280 | |
Brett Cannon | 938d44d | 2012-04-22 19:58:33 -0400 | [diff] [blame] | 1281 | |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1282 | .. class:: ModuleSpec(name, loader, *, origin=None, loader_state=None, is_package=None) |
| 1283 | |
Barry Warsaw | 191e313 | 2017-10-17 15:52:38 -0400 | [diff] [blame] | 1284 | A specification for a module's import-system-related state. This is |
| 1285 | typically exposed as the module's ``__spec__`` attribute. In the |
| 1286 | descriptions below, the names in parentheses give the corresponding |
| 1287 | attribute available directly on the module object. |
| 1288 | E.g. ``module.__spec__.origin == module.__file__``. Note however that |
| 1289 | while the *values* are usually equivalent, they can differ since there is |
| 1290 | no synchronization between the two objects. Thus it is possible to update |
| 1291 | the module's ``__path__`` at runtime, and this will not be automatically |
| 1292 | reflected in ``__spec__.submodule_search_locations``. |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1293 | |
| 1294 | .. versionadded:: 3.4 |
| 1295 | |
| 1296 | .. attribute:: name |
| 1297 | |
| 1298 | (``__name__``) |
| 1299 | |
| 1300 | A string for the fully-qualified name of the module. |
| 1301 | |
| 1302 | .. attribute:: loader |
| 1303 | |
| 1304 | (``__loader__``) |
| 1305 | |
| 1306 | The loader to use for loading. For namespace packages this should be |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 1307 | set to ``None``. |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1308 | |
| 1309 | .. attribute:: origin |
| 1310 | |
| 1311 | (``__file__``) |
| 1312 | |
| 1313 | Name of the place from which the module is loaded, e.g. "builtin" for |
| 1314 | built-in modules and the filename for modules loaded from source. |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 1315 | Normally "origin" should be set, but it may be ``None`` (the default) |
Barry Warsaw | bbbcf86 | 2018-02-02 15:15:58 -0500 | [diff] [blame] | 1316 | which indicates it is unspecified (e.g. for namespace packages). |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1317 | |
| 1318 | .. attribute:: submodule_search_locations |
| 1319 | |
| 1320 | (``__path__``) |
| 1321 | |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 1322 | List of strings for where to find submodules, if a package (``None`` |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1323 | otherwise). |
| 1324 | |
| 1325 | .. attribute:: loader_state |
| 1326 | |
| 1327 | Container of extra module-specific data for use during loading (or |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 1328 | ``None``). |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1329 | |
| 1330 | .. attribute:: cached |
| 1331 | |
| 1332 | (``__cached__``) |
| 1333 | |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 1334 | String for where the compiled module should be stored (or ``None``). |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1335 | |
| 1336 | .. attribute:: parent |
| 1337 | |
| 1338 | (``__package__``) |
| 1339 | |
| 1340 | (Read-only) Fully-qualified name of the package to which the module |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 1341 | belongs as a submodule (or ``None``). |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1342 | |
| 1343 | .. attribute:: has_location |
| 1344 | |
Eric Snow | b282b3d | 2013-12-10 22:16:41 -0700 | [diff] [blame] | 1345 | Boolean indicating whether or not the module's "origin" |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1346 | attribute refers to a loadable location. |
| 1347 | |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1348 | :mod:`importlib.util` -- Utility code for importers |
| 1349 | --------------------------------------------------- |
| 1350 | |
| 1351 | .. module:: importlib.util |
Brett Cannon | 75321e8 | 2012-03-02 11:58:25 -0500 | [diff] [blame] | 1352 | :synopsis: Utility code for importers |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1353 | |
Terry Jan Reedy | dcb6c88 | 2016-06-22 22:46:34 -0400 | [diff] [blame] | 1354 | |
| 1355 | **Source code:** :source:`Lib/importlib/util.py` |
| 1356 | |
| 1357 | -------------- |
| 1358 | |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1359 | This module contains the various objects that help in the construction of |
| 1360 | an :term:`importer`. |
| 1361 | |
Brett Cannon | 05a647d | 2013-06-14 19:02:34 -0400 | [diff] [blame] | 1362 | .. attribute:: MAGIC_NUMBER |
| 1363 | |
| 1364 | The bytes which represent the bytecode version number. If you need help with |
| 1365 | loading/writing bytecode then consider :class:`importlib.abc.SourceLoader`. |
| 1366 | |
| 1367 | .. versionadded:: 3.4 |
| 1368 | |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 1369 | .. function:: cache_from_source(path, debug_override=None, *, optimization=None) |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 1370 | |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 1371 | Return the :pep:`3147`/:pep:`488` path to the byte-compiled file associated |
| 1372 | with the source *path*. For example, if *path* is ``/foo/bar/baz.py`` the return |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 1373 | value would be ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2. |
| 1374 | The ``cpython-32`` string comes from the current magic tag (see |
| 1375 | :func:`get_tag`; if :attr:`sys.implementation.cache_tag` is not defined then |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 1376 | :exc:`NotImplementedError` will be raised). |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 1377 | |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 1378 | The *optimization* parameter is used to specify the optimization level of the |
| 1379 | bytecode file. An empty string represents no optimization, so |
| 1380 | ``/foo/bar/baz.py`` with an *optimization* of ``''`` will result in a |
| 1381 | bytecode path of ``/foo/bar/__pycache__/baz.cpython-32.pyc``. ``None`` causes |
| 1382 | the interpter's optimization level to be used. Any other value's string |
| 1383 | representation being used, so ``/foo/bar/baz.py`` with an *optimization* of |
| 1384 | ``2`` will lead to the bytecode path of |
| 1385 | ``/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc``. The string representation |
| 1386 | of *optimization* can only be alphanumeric, else :exc:`ValueError` is raised. |
| 1387 | |
| 1388 | The *debug_override* parameter is deprecated and can be used to override |
| 1389 | the system's value for ``__debug__``. A ``True`` value is the equivalent of |
| 1390 | setting *optimization* to the empty string. A ``False`` value is the same as |
| 1391 | setting *optimization* to ``1``. If both *debug_override* an *optimization* |
| 1392 | are not ``None`` then :exc:`TypeError` is raised. |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 1393 | |
| 1394 | .. versionadded:: 3.4 |
| 1395 | |
Berker Peksag | fe5f614 | 2016-01-30 19:30:06 +0200 | [diff] [blame] | 1396 | .. versionchanged:: 3.5 |
Brett Cannon | f299abd | 2015-04-13 14:21:02 -0400 | [diff] [blame] | 1397 | The *optimization* parameter was added and the *debug_override* parameter |
| 1398 | was deprecated. |
| 1399 | |
Brett Cannon | 035a100 | 2016-09-07 18:39:18 -0700 | [diff] [blame] | 1400 | .. versionchanged:: 3.6 |
| 1401 | Accepts a :term:`path-like object`. |
| 1402 | |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 1403 | |
| 1404 | .. function:: source_from_cache(path) |
| 1405 | |
| 1406 | Given the *path* to a :pep:`3147` file name, return the associated source code |
| 1407 | file path. For example, if *path* is |
| 1408 | ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be |
| 1409 | ``/foo/bar/baz.py``. *path* need not exist, however if it does not conform |
Larry Hastings | 770ce20 | 2015-04-19 13:50:12 -0700 | [diff] [blame] | 1410 | to :pep:`3147` or :pep:`488` format, a ``ValueError`` is raised. If |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 1411 | :attr:`sys.implementation.cache_tag` is not defined, |
| 1412 | :exc:`NotImplementedError` is raised. |
| 1413 | |
| 1414 | .. versionadded:: 3.4 |
| 1415 | |
Brett Cannon | 035a100 | 2016-09-07 18:39:18 -0700 | [diff] [blame] | 1416 | .. versionchanged:: 3.6 |
| 1417 | Accepts a :term:`path-like object`. |
| 1418 | |
Brett Cannon | f24fecd | 2013-06-16 18:37:53 -0400 | [diff] [blame] | 1419 | .. function:: decode_source(source_bytes) |
| 1420 | |
| 1421 | Decode the given bytes representing source code and return it as a string |
| 1422 | with universal newlines (as required by |
| 1423 | :meth:`importlib.abc.InspectLoader.get_source`). |
| 1424 | |
| 1425 | .. versionadded:: 3.4 |
| 1426 | |
Brett Cannon | d200bf5 | 2012-05-13 13:45:09 -0400 | [diff] [blame] | 1427 | .. function:: resolve_name(name, package) |
| 1428 | |
| 1429 | Resolve a relative module name to an absolute one. |
| 1430 | |
| 1431 | If **name** has no leading dots, then **name** is simply returned. This |
| 1432 | allows for usage such as |
| 1433 | ``importlib.util.resolve_name('sys', __package__)`` without doing a |
| 1434 | check to see if the **package** argument is needed. |
| 1435 | |
| 1436 | :exc:`ValueError` is raised if **name** is a relative module name but |
| 1437 | package is a false value (e.g. ``None`` or the empty string). |
| 1438 | :exc:`ValueError` is also raised a relative name would escape its containing |
| 1439 | package (e.g. requesting ``..bacon`` from within the ``spam`` package). |
| 1440 | |
| 1441 | .. versionadded:: 3.3 |
| 1442 | |
Eric Snow | 6029e08 | 2014-01-25 15:32:46 -0700 | [diff] [blame] | 1443 | .. function:: find_spec(name, package=None) |
| 1444 | |
| 1445 | Find the :term:`spec <module spec>` for a module, optionally relative to |
| 1446 | the specified **package** name. If the module is in :attr:`sys.modules`, |
| 1447 | then ``sys.modules[name].__spec__`` is returned (unless the spec would be |
| 1448 | ``None`` or is not set, in which case :exc:`ValueError` is raised). |
| 1449 | Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is |
| 1450 | returned if no spec is found. |
| 1451 | |
| 1452 | If **name** is for a submodule (contains a dot), the parent module is |
| 1453 | automatically imported. |
| 1454 | |
| 1455 | **name** and **package** work the same as for :func:`import_module`. |
| 1456 | |
| 1457 | .. versionadded:: 3.4 |
| 1458 | |
Milan Oberkirch | 8c3f05e | 2017-06-15 07:34:50 +1000 | [diff] [blame] | 1459 | .. versionchanged:: 3.7 |
| 1460 | Raises :exc:`ModuleNotFoundError` instead of :exc:`AttributeError` if |
| 1461 | **package** is in fact not a package (i.e. lacks a :attr:`__path__` |
| 1462 | attribute). |
| 1463 | |
Brett Cannon | 2a17bde | 2014-05-30 14:55:29 -0400 | [diff] [blame] | 1464 | .. function:: module_from_spec(spec) |
| 1465 | |
Brett Cannon | 696c35e | 2016-06-25 10:58:17 -0700 | [diff] [blame] | 1466 | Create a new module based on **spec** and |
| 1467 | :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>`. |
Brett Cannon | 2a17bde | 2014-05-30 14:55:29 -0400 | [diff] [blame] | 1468 | |
Brett Cannon | 696c35e | 2016-06-25 10:58:17 -0700 | [diff] [blame] | 1469 | If :meth:`spec.loader.create_module <importlib.abc.Loader.create_module>` |
| 1470 | does not return ``None``, then any pre-existing attributes will not be reset. |
| 1471 | Also, no :exc:`AttributeError` will be raised if triggered while accessing |
| 1472 | **spec** or setting an attribute on the module. |
Brett Cannon | 2a17bde | 2014-05-30 14:55:29 -0400 | [diff] [blame] | 1473 | |
| 1474 | This function is preferred over using :class:`types.ModuleType` to create a |
| 1475 | new module as **spec** is used to set as many import-controlled attributes on |
| 1476 | the module as possible. |
| 1477 | |
| 1478 | .. versionadded:: 3.5 |
| 1479 | |
Georg Brandl | 8a1caa2 | 2010-07-29 16:01:11 +0000 | [diff] [blame] | 1480 | .. decorator:: module_for_loader |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1481 | |
Brett Cannon | a22faca | 2013-05-28 17:50:14 -0400 | [diff] [blame] | 1482 | A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 1483 | to handle selecting the proper |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1484 | 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] | 1485 | signature taking two positional arguments |
| 1486 | (e.g. ``load_module(self, module)``) for which the second argument |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 1487 | will be the module **object** to be used by the loader. |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 1488 | Note that the decorator will not work on static methods because of the |
| 1489 | assumption of two arguments. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1490 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 1491 | The decorated method will take in the **name** of the module to be loaded |
| 1492 | as expected for a :term:`loader`. If the module is not found in |
Brett Cannon | 3dc48d6 | 2013-05-28 18:35:54 -0400 | [diff] [blame] | 1493 | :data:`sys.modules` then a new one is constructed. Regardless of where the |
| 1494 | module came from, :attr:`__loader__` set to **self** and :attr:`__package__` |
| 1495 | is set based on what :meth:`importlib.abc.InspectLoader.is_package` returns |
| 1496 | (if available). These attributes are set unconditionally to support |
| 1497 | reloading. |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 1498 | |
| 1499 | If an exception is raised by the decorated method and a module was added to |
Brett Cannon | a87e31c | 2013-09-13 16:52:19 -0400 | [diff] [blame] | 1500 | :data:`sys.modules`, then the module will be removed to prevent a partially |
| 1501 | initialized module from being in left in :data:`sys.modules`. If the module |
| 1502 | was already in :data:`sys.modules` then it is left alone. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 1503 | |
Brett Cannon | efad00d | 2012-04-27 17:27:14 -0400 | [diff] [blame] | 1504 | .. versionchanged:: 3.3 |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 1505 | :attr:`__loader__` and :attr:`__package__` are automatically set |
| 1506 | (when possible). |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 1507 | |
Brett Cannon | 3dc48d6 | 2013-05-28 18:35:54 -0400 | [diff] [blame] | 1508 | .. versionchanged:: 3.4 |
Brett Cannon | 0dbb4c7 | 2013-05-31 18:56:47 -0400 | [diff] [blame] | 1509 | Set :attr:`__name__`, :attr:`__loader__` :attr:`__package__` |
| 1510 | unconditionally to support reloading. |
| 1511 | |
| 1512 | .. deprecated:: 3.4 |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1513 | The import machinery now directly performs all the functionality |
| 1514 | provided by this function. |
Brett Cannon | 3dc48d6 | 2013-05-28 18:35:54 -0400 | [diff] [blame] | 1515 | |
Georg Brandl | 8a1caa2 | 2010-07-29 16:01:11 +0000 | [diff] [blame] | 1516 | .. decorator:: set_loader |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 1517 | |
Brett Cannon | a22faca | 2013-05-28 17:50:14 -0400 | [diff] [blame] | 1518 | A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` |
| 1519 | to set the :attr:`__loader__` |
| 1520 | attribute on the returned module. If the attribute is already set the |
| 1521 | decorator does nothing. It is assumed that the first positional argument to |
| 1522 | the wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set |
| 1523 | to. |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 1524 | |
Brett Cannon | 4802bec | 2013-03-13 10:41:36 -0700 | [diff] [blame] | 1525 | .. versionchanged:: 3.4 |
Brett Cannon | 4c14b5d | 2013-05-04 13:56:58 -0400 | [diff] [blame] | 1526 | Set ``__loader__`` if set to ``None``, as if the attribute does not |
Brett Cannon | 4802bec | 2013-03-13 10:41:36 -0700 | [diff] [blame] | 1527 | exist. |
| 1528 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1529 | .. deprecated:: 3.4 |
| 1530 | The import machinery takes care of this automatically. |
| 1531 | |
Georg Brandl | 8a1caa2 | 2010-07-29 16:01:11 +0000 | [diff] [blame] | 1532 | .. decorator:: set_package |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 1533 | |
Brett Cannon | 696c35e | 2016-06-25 10:58:17 -0700 | [diff] [blame] | 1534 | A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` to set the |
| 1535 | :attr:`__package__` attribute on the returned module. If :attr:`__package__` |
Brett Cannon | a22faca | 2013-05-28 17:50:14 -0400 | [diff] [blame] | 1536 | is set and has a value other than ``None`` it will not be changed. |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 1537 | |
Eric Snow | ca2d854 | 2013-12-16 23:06:52 -0700 | [diff] [blame] | 1538 | .. deprecated:: 3.4 |
| 1539 | The import machinery takes care of this automatically. |
| 1540 | |
Eric Snow | b523f84 | 2013-11-22 09:05:39 -0700 | [diff] [blame] | 1541 | .. function:: spec_from_loader(name, loader, *, origin=None, is_package=None) |
| 1542 | |
| 1543 | A factory function for creating a :class:`ModuleSpec` instance based |
| 1544 | on a loader. The parameters have the same meaning as they do for |
| 1545 | ModuleSpec. The function uses available :term:`loader` APIs, such as |
| 1546 | :meth:`InspectLoader.is_package`, to fill in any missing |
| 1547 | information on the spec. |
| 1548 | |
| 1549 | .. versionadded:: 3.4 |
| 1550 | |
| 1551 | .. function:: spec_from_file_location(name, location, *, loader=None, submodule_search_locations=None) |
| 1552 | |
| 1553 | A factory function for creating a :class:`ModuleSpec` instance based |
| 1554 | on the path to a file. Missing information will be filled in on the |
| 1555 | spec by making use of loader APIs and by the implication that the |
| 1556 | module will be file-based. |
| 1557 | |
| 1558 | .. versionadded:: 3.4 |
Brett Cannon | a04dbe4 | 2014-04-04 13:53:38 -0400 | [diff] [blame] | 1559 | |
Brett Cannon | 035a100 | 2016-09-07 18:39:18 -0700 | [diff] [blame] | 1560 | .. versionchanged:: 3.6 |
| 1561 | Accepts a :term:`path-like object`. |
| 1562 | |
Benjamin Peterson | 42aa93b | 2017-12-09 10:26:52 -0800 | [diff] [blame] | 1563 | .. function:: source_hash(source_bytes) |
| 1564 | |
| 1565 | Return the hash of *source_bytes* as bytes. A hash-based ``.pyc`` file embeds |
| 1566 | the :func:`source_hash` of the corresponding source file's contents in its |
| 1567 | header. |
| 1568 | |
| 1569 | .. versionadded:: 3.7 |
| 1570 | |
Brett Cannon | a04dbe4 | 2014-04-04 13:53:38 -0400 | [diff] [blame] | 1571 | .. class:: LazyLoader(loader) |
| 1572 | |
| 1573 | A class which postpones the execution of the loader of a module until the |
| 1574 | module has an attribute accessed. |
| 1575 | |
| 1576 | This class **only** works with loaders that define |
Brett Cannon | 02d8454 | 2015-01-09 11:39:21 -0500 | [diff] [blame] | 1577 | :meth:`~importlib.abc.Loader.exec_module` as control over what module type |
| 1578 | is used for the module is required. For those same reasons, the loader's |
Brett Cannon | 696c35e | 2016-06-25 10:58:17 -0700 | [diff] [blame] | 1579 | :meth:`~importlib.abc.Loader.create_module` method must return ``None`` or a |
| 1580 | type for which its ``__class__`` attribute can be mutated along with not |
| 1581 | using :term:`slots <__slots__>`. Finally, modules which substitute the object |
| 1582 | placed into :attr:`sys.modules` will not work as there is no way to properly |
| 1583 | replace the module references throughout the interpreter safely; |
| 1584 | :exc:`ValueError` is raised if such a substitution is detected. |
Brett Cannon | a04dbe4 | 2014-04-04 13:53:38 -0400 | [diff] [blame] | 1585 | |
| 1586 | .. note:: |
| 1587 | For projects where startup time is critical, this class allows for |
| 1588 | potentially minimizing the cost of loading a module if it is never used. |
| 1589 | For projects where startup time is not essential then use of this class is |
| 1590 | **heavily** discouraged due to error messages created during loading being |
| 1591 | postponed and thus occurring out of context. |
| 1592 | |
| 1593 | .. versionadded:: 3.5 |
| 1594 | |
Brett Cannon | 696c35e | 2016-06-25 10:58:17 -0700 | [diff] [blame] | 1595 | .. versionchanged:: 3.6 |
| 1596 | Began calling :meth:`~importlib.abc.Loader.create_module`, removing the |
| 1597 | compatibility warning for :class:`importlib.machinery.BuiltinImporter` and |
| 1598 | :class:`importlib.machinery.ExtensionFileLoader`. |
| 1599 | |
Brett Cannon | a04dbe4 | 2014-04-04 13:53:38 -0400 | [diff] [blame] | 1600 | .. classmethod:: factory(loader) |
| 1601 | |
| 1602 | A static method which returns a callable that creates a lazy loader. This |
| 1603 | is meant to be used in situations where the loader is passed by class |
| 1604 | instead of by instance. |
| 1605 | :: |
| 1606 | |
| 1607 | suffixes = importlib.machinery.SOURCE_SUFFIXES |
| 1608 | loader = importlib.machinery.SourceFileLoader |
| 1609 | lazy_loader = importlib.util.LazyLoader.factory(loader) |
Brett Cannon | 3bf1d87 | 2016-01-22 14:03:27 -0800 | [diff] [blame] | 1610 | finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes)) |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1611 | |
| 1612 | .. _importlib-examples: |
| 1613 | |
| 1614 | Examples |
| 1615 | -------- |
| 1616 | |
Brett Cannon | 2376316 | 2016-09-08 10:12:47 -0700 | [diff] [blame] | 1617 | Importing programmatically |
| 1618 | '''''''''''''''''''''''''' |
| 1619 | |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1620 | To programmatically import a module, use :func:`importlib.import_module`. |
| 1621 | :: |
| 1622 | |
| 1623 | import importlib |
| 1624 | |
| 1625 | itertools = importlib.import_module('itertools') |
| 1626 | |
Brett Cannon | 2376316 | 2016-09-08 10:12:47 -0700 | [diff] [blame] | 1627 | |
| 1628 | Checking if a module can be imported |
| 1629 | '''''''''''''''''''''''''''''''''''' |
| 1630 | |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1631 | If you need to find out if a module can be imported without actually doing the |
| 1632 | import, then you should use :func:`importlib.util.find_spec`. |
| 1633 | :: |
| 1634 | |
| 1635 | import importlib.util |
| 1636 | import sys |
| 1637 | |
| 1638 | # For illustrative purposes. |
| 1639 | name = 'itertools' |
| 1640 | |
| 1641 | spec = importlib.util.find_spec(name) |
| 1642 | if spec is None: |
| 1643 | print("can't find the itertools module") |
| 1644 | else: |
Brett Cannon | 5936313 | 2016-03-18 11:54:22 -0700 | [diff] [blame] | 1645 | # If you chose to perform the actual import ... |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1646 | module = importlib.util.module_from_spec(spec) |
| 1647 | spec.loader.exec_module(module) |
| 1648 | # Adding the module to sys.modules is optional. |
| 1649 | sys.modules[name] = module |
| 1650 | |
Brett Cannon | 2376316 | 2016-09-08 10:12:47 -0700 | [diff] [blame] | 1651 | |
| 1652 | Importing a source file directly |
| 1653 | '''''''''''''''''''''''''''''''' |
| 1654 | |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1655 | To import a Python source file directly, use the following recipe |
| 1656 | (Python 3.4 and newer only):: |
| 1657 | |
| 1658 | import importlib.util |
| 1659 | import sys |
| 1660 | |
| 1661 | # For illustrative purposes. |
| 1662 | import tokenize |
| 1663 | file_path = tokenize.__file__ |
| 1664 | module_name = tokenize.__name__ |
| 1665 | |
| 1666 | spec = importlib.util.spec_from_file_location(module_name, file_path) |
| 1667 | module = importlib.util.module_from_spec(spec) |
| 1668 | spec.loader.exec_module(module) |
| 1669 | # Optional; only necessary if you want to be able to import the module |
| 1670 | # by name later. |
| 1671 | sys.modules[module_name] = module |
| 1672 | |
Brett Cannon | 2376316 | 2016-09-08 10:12:47 -0700 | [diff] [blame] | 1673 | |
| 1674 | Setting up an importer |
| 1675 | '''''''''''''''''''''' |
| 1676 | |
Brett Cannon | 5936313 | 2016-03-18 11:54:22 -0700 | [diff] [blame] | 1677 | For deep customizations of import, you typically want to implement an |
| 1678 | :term:`importer`. This means managing both the :term:`finder` and :term:`loader` |
| 1679 | side of things. For finders there are two flavours to choose from depending on |
| 1680 | your needs: a :term:`meta path finder` or a :term:`path entry finder`. The |
| 1681 | former is what you would put on :attr:`sys.meta_path` while the latter is what |
| 1682 | you create using a :term:`path entry hook` on :attr:`sys.path_hooks` which works |
| 1683 | with :attr:`sys.path` entries to potentially create a finder. This example will |
| 1684 | show you how to register your own importers so that import will use them (for |
| 1685 | creating an importer for yourself, read the documentation for the appropriate |
| 1686 | classes defined within this package):: |
| 1687 | |
| 1688 | import importlib.machinery |
| 1689 | import sys |
| 1690 | |
| 1691 | # For illustrative purposes only. |
| 1692 | SpamMetaPathFinder = importlib.machinery.PathFinder |
| 1693 | SpamPathEntryFinder = importlib.machinery.FileFinder |
| 1694 | loader_details = (importlib.machinery.SourceFileLoader, |
| 1695 | importlib.machinery.SOURCE_SUFFIXES) |
| 1696 | |
| 1697 | # Setting up a meta path finder. |
| 1698 | # Make sure to put the finder in the proper location in the list in terms of |
| 1699 | # priority. |
| 1700 | sys.meta_path.append(SpamMetaPathFinder) |
| 1701 | |
| 1702 | # Setting up a path entry finder. |
| 1703 | # Make sure to put the path hook in the proper location in the list in terms |
| 1704 | # of priority. |
| 1705 | sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details)) |
| 1706 | |
Brett Cannon | 2376316 | 2016-09-08 10:12:47 -0700 | [diff] [blame] | 1707 | |
| 1708 | Approximating :func:`importlib.import_module` |
| 1709 | ''''''''''''''''''''''''''''''''''''''''''''' |
| 1710 | |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1711 | Import itself is implemented in Python code, making it possible to |
| 1712 | expose most of the import machinery through importlib. The following |
| 1713 | helps illustrate the various APIs that importlib exposes by providing an |
| 1714 | approximate implementation of |
Brett Cannon | 5936313 | 2016-03-18 11:54:22 -0700 | [diff] [blame] | 1715 | :func:`importlib.import_module` (Python 3.4 and newer for the importlib usage, |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1716 | Python 3.6 and newer for other parts of the code). |
| 1717 | :: |
| 1718 | |
| 1719 | import importlib.util |
| 1720 | import sys |
| 1721 | |
| 1722 | def import_module(name, package=None): |
| 1723 | """An approximate implementation of import.""" |
| 1724 | absolute_name = importlib.util.resolve_name(name, package) |
| 1725 | try: |
| 1726 | return sys.modules[absolute_name] |
| 1727 | except KeyError: |
| 1728 | pass |
| 1729 | |
| 1730 | path = None |
| 1731 | if '.' in absolute_name: |
| 1732 | parent_name, _, child_name = absolute_name.rpartition('.') |
| 1733 | parent_module = import_module(parent_name) |
| 1734 | path = parent_module.spec.submodule_search_locations |
| 1735 | for finder in sys.meta_path: |
| 1736 | spec = finder.find_spec(absolute_name, path) |
| 1737 | if spec is not None: |
| 1738 | break |
| 1739 | else: |
| 1740 | raise ImportError(f'No module named {absolute_name!r}') |
Brett Cannon | 86a8be0 | 2016-02-20 18:47:09 -0800 | [diff] [blame] | 1741 | module = importlib.util.module_from_spec(spec) |
Brett Cannon | a85e927 | 2016-01-08 14:33:09 -0800 | [diff] [blame] | 1742 | spec.loader.exec_module(module) |
| 1743 | sys.modules[absolute_name] = module |
| 1744 | if path is not None: |
| 1745 | setattr(parent_module, child_name, module) |
| 1746 | return module |