Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 1 | :mod:`importlib` -- An implementation of :keyword:`import` |
| 2 | ========================================================== |
| 3 | |
| 4 | .. module:: importlib |
| 5 | :synopsis: An implementation of the import machinery. |
| 6 | |
| 7 | .. moduleauthor:: Brett Cannon <brett@python.org> |
| 8 | .. sectionauthor:: Brett Cannon <brett@python.org> |
| 9 | |
| 10 | .. versionadded:: 3.1 |
| 11 | |
| 12 | |
| 13 | Introduction |
| 14 | ------------ |
| 15 | |
| 16 | The purpose of the :mod:`importlib` package is two-fold. One is to provide an |
| 17 | implementation of the :keyword:`import` statement (and thus, by extension, the |
| 18 | :func:`__import__` function) in Python source code. This provides an |
Tarek Ziadé | 434caaa | 2009-05-14 12:48:09 +0000 | [diff] [blame] | 19 | implementation of :keyword:`import` which is portable to any Python |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 20 | interpreter. This also provides a reference implementation which is easier to |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 21 | comprehend than one in a programming language other than Python. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 22 | |
| 23 | Two, the components to implement :keyword:`import` can be exposed in this |
| 24 | package, making it easier for users to create their own custom objects (known |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 25 | generically as an :term:`importer`) to participate in the import process. |
| 26 | Details on providing custom importers can be found in :pep:`302`. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 27 | |
| 28 | .. seealso:: |
| 29 | |
| 30 | :ref:`import` |
| 31 | The language reference for the :keyword:`import` statement. |
| 32 | |
| 33 | `Packages specification <http://www.python.org/doc/essays/packages.html>`__ |
| 34 | Original specification of packages. Some semantics have changed since |
| 35 | the writing of this document (e.g. redirecting based on :keyword:`None` |
| 36 | in :data:`sys.modules`). |
| 37 | |
| 38 | The :func:`.__import__` function |
| 39 | The built-in function for which the :keyword:`import` statement is |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 40 | syntactic sugar. |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 41 | |
| 42 | :pep:`235` |
| 43 | Import on Case-Insensitive Platforms |
| 44 | |
| 45 | :pep:`263` |
| 46 | Defining Python Source Code Encodings |
| 47 | |
| 48 | :pep:`302` |
| 49 | New Import Hooks. |
| 50 | |
| 51 | :pep:`328` |
| 52 | Imports: Multi-Line and Absolute/Relative |
| 53 | |
| 54 | :pep:`366` |
| 55 | Main module explicit relative imports |
| 56 | |
| 57 | :pep:`3128` |
| 58 | Using UTF-8 as the Default Source Encoding |
| 59 | |
| 60 | |
| 61 | Functions |
| 62 | --------- |
| 63 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 64 | .. function:: __import__(name, globals={}, locals={}, fromlist=list(), level=0) |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 65 | |
| 66 | An implementation of the built-in :func:`__import__` function. See the |
| 67 | built-in function's documentation for usage instructions. |
| 68 | |
| 69 | .. function:: import_module(name, package=None) |
| 70 | |
Brett Cannon | 33418c8 | 2009-01-22 18:37:20 +0000 | [diff] [blame] | 71 | Import a module. The *name* argument specifies what module to |
Brett Cannon | afccd63 | 2009-01-20 02:21:27 +0000 | [diff] [blame] | 72 | import in absolute or relative terms |
| 73 | (e.g. either ``pkg.mod`` or ``..mod``). If the name is |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 74 | specified in relative terms, then the *package* argument must be set to |
| 75 | 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] | 76 | package name (e.g. ``import_module('..mod', 'pkg.subpkg')`` will import |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 77 | ``pkg.mod``). |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 78 | |
Brett Cannon | 2c318a1 | 2009-02-07 01:15:27 +0000 | [diff] [blame] | 79 | The :func:`import_module` function acts as a simplifying wrapper around |
Brett Cannon | 9f4cb1c | 2009-04-01 23:26:47 +0000 | [diff] [blame] | 80 | :func:`importlib.__import__`. This means all semantics of the function are |
| 81 | derived from :func:`importlib.__import__`, including requiring the package |
| 82 | from which an import is occurring to have been previously imported |
| 83 | (i.e., *package* must already be imported). The most important difference |
| 84 | is that :func:`import_module` returns the most nested package or module |
| 85 | that was imported (e.g. ``pkg.mod``), while :func:`__import__` returns the |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 86 | top-level package or module (e.g. ``pkg``). |
| 87 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 88 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 89 | :mod:`importlib.abc` -- Abstract base classes related to import |
| 90 | --------------------------------------------------------------- |
| 91 | |
| 92 | .. module:: importlib.abc |
| 93 | :synopsis: Abstract base classes related to import |
| 94 | |
| 95 | The :mod:`importlib.abc` module contains all of the core abstract base classes |
| 96 | used by :keyword:`import`. Some subclasses of the core abstract base classes |
| 97 | are also provided to help in implementing the core ABCs. |
| 98 | |
| 99 | |
| 100 | .. class:: Finder |
| 101 | |
| 102 | An abstract base class representing a :term:`finder`. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 103 | See :pep:`302` for the exact definition for a finder. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 104 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 105 | .. method:: find_module(fullname, path=None) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 106 | |
| 107 | An abstract method for finding a :term:`loader` for the specified |
| 108 | module. If the :term:`finder` is found on :data:`sys.meta_path` and the |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 109 | module to be searched for is a subpackage or module then *path* will |
| 110 | be the value of :attr:`__path__` from the parent package. If a loader |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 111 | cannot be found, :keyword:`None` is returned. |
| 112 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 113 | |
| 114 | .. class:: Loader |
| 115 | |
| 116 | An abstract base class for a :term:`loader`. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 117 | See :pep:`302` for the exact definition for a loader. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 118 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 119 | .. method:: load_module(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 120 | |
| 121 | An abstract method for loading a module. If the module cannot be |
| 122 | loaded, :exc:`ImportError` is raised, otherwise the loaded module is |
| 123 | returned. |
| 124 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 125 | If the requested module already exists in :data:`sys.modules`, that |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 126 | module should be used and reloaded. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 127 | Otherwise the loader should create a new module and insert it into |
| 128 | :data:`sys.modules` before any loading begins, to prevent recursion |
| 129 | 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] | 130 | must be removed by the loader from :data:`sys.modules`; modules already |
| 131 | in :data:`sys.modules` before the loader began execution should be left |
| 132 | alone. The :func:`importlib.util.module_for_loader` decorator handles |
| 133 | all of these details. |
| 134 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 135 | The loader should set several attributes on the module. |
| 136 | (Note that some of these attributes can change when a module is |
| 137 | reloaded.) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 138 | |
| 139 | - :attr:`__name__` |
| 140 | The name of the module. |
| 141 | |
| 142 | - :attr:`__file__` |
| 143 | The path to where the module data is stored (not set for built-in |
| 144 | modules). |
| 145 | |
| 146 | - :attr:`__path__` |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 147 | A list of strings specifying the search path within a |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 148 | package. This attribute is not set on modules. |
| 149 | |
| 150 | - :attr:`__package__` |
| 151 | The parent package for the module/package. If the module is |
| 152 | top-level then it has a value of the empty string. The |
| 153 | :func:`importlib.util.set_package` decorator can handle the details |
| 154 | for :attr:`__package__`. |
| 155 | |
| 156 | - :attr:`__loader__` |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 157 | The loader used to load the module. |
| 158 | (This is not set by the built-in import machinery, |
| 159 | but it should be set whenever a :term:`loader` is used.) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 160 | |
| 161 | |
| 162 | .. class:: ResourceLoader |
| 163 | |
| 164 | An abstract base class for a :term:`loader` which implements the optional |
| 165 | :pep:`302` protocol for loading arbitrary resources from the storage |
| 166 | back-end. |
| 167 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 168 | .. method:: get_data(path) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 169 | |
| 170 | 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] | 171 | Loaders that have a file-like storage back-end |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 172 | that allows storing arbitrary data |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 173 | can implement this abstract method to give direct access |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 174 | to the data stored. :exc:`IOError` is to be raised if the *path* cannot |
| 175 | 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] | 176 | :attr:`__file__` attribute or an item from a package's :attr:`__path__`. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 177 | |
| 178 | |
| 179 | .. class:: InspectLoader |
| 180 | |
| 181 | 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] | 182 | :pep:`302` protocol for loaders that inspect modules. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 183 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 184 | .. method:: get_code(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 185 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 186 | An abstract method to return the :class:`code` object for a module. |
| 187 | :keyword:`None` is returned if the module does not have a code object |
| 188 | (e.g. built-in module). :exc:`ImportError` is raised if loader cannot |
| 189 | find the requested module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 190 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 191 | .. method:: get_source(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 192 | |
| 193 | An abstract method to return the source of a module. It is returned as |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 194 | a text string with universal newlines. Returns :keyword:`None` if no |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 195 | source is available (e.g. a built-in module). Raises :exc:`ImportError` |
| 196 | if the loader cannot find the module specified. |
| 197 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 198 | .. method:: is_package(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 199 | |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 200 | An abstract method to return a true value if the module is a package, a |
| 201 | false value otherwise. :exc:`ImportError` is raised if the |
| 202 | :term:`loader` cannot find the module. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 203 | |
| 204 | |
| 205 | .. class:: PyLoader |
| 206 | |
| 207 | An abstract base class inheriting from :class:`importlib.abc.InspectLoader` |
| 208 | and :class:`importlib.abc.ResourceLoader` designed to ease the loading of |
| 209 | Python source modules (bytecode is not handled; see |
| 210 | :class:`importlib.abc.PyPycLoader` for a source/bytecode ABC). A subclass |
| 211 | implementing this ABC will only need to worry about exposing how the source |
| 212 | code is stored; all other details for loading Python source code will be |
| 213 | handled by the concrete implementations of key methods. |
| 214 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 215 | .. method:: source_path(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 216 | |
| 217 | An abstract method that returns the path to the source code for a |
| 218 | module. Should return :keyword:`None` if there is no source code. |
| 219 | :exc:`ImportError` if the module cannot be found. |
| 220 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 221 | .. method:: load_module(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 222 | |
| 223 | A concrete implementation of :meth:`importlib.abc.Loader.load_module` |
Brett Cannon | ad876c7 | 2009-03-09 07:53:09 +0000 | [diff] [blame] | 224 | that loads Python source code. All needed information comes from the |
| 225 | abstract methods required by this ABC. The only pertinent assumption |
| 226 | made by this method is that when loading a package |
| 227 | :attr:`__path__` is set to ``[os.path.dirname(__file__)]``. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 228 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 229 | .. method:: get_code(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 230 | |
| 231 | A concrete implementation of |
| 232 | :meth:`importlib.abc.InspectLoader.get_code` that creates code objects |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 233 | from Python source code, by requesting the source code (using |
| 234 | :meth:`source_path` and :meth:`get_data`), converting it to standard |
| 235 | newlines, and compiling it with the built-in :func:`compile` function. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 236 | |
Brett Cannon | d43b30b | 2009-03-10 03:29:23 +0000 | [diff] [blame] | 237 | .. method:: get_source(fullname) |
| 238 | |
| 239 | A concrete implementation of |
| 240 | :meth:`importlib.abc.InspectLoader.get_source`. Uses |
| 241 | :meth:`importlib.abc.InspectLoader.get_data` and :meth:`source_path` to |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 242 | get the source code. It tries to guess the source encoding using |
| 243 | :func:`tokenize.detect_encoding`. |
Brett Cannon | d43b30b | 2009-03-10 03:29:23 +0000 | [diff] [blame] | 244 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 245 | |
| 246 | .. class:: PyPycLoader |
| 247 | |
| 248 | An abstract base class inheriting from :class:`importlib.abc.PyLoader`. |
| 249 | This ABC is meant to help in creating loaders that support both Python |
| 250 | source and bytecode. |
| 251 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 252 | .. method:: source_mtime(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 253 | |
| 254 | An abstract method which returns the modification time for the source |
| 255 | code of the specified module. The modification time should be an |
| 256 | integer. If there is no source code, return :keyword:`None. If the |
| 257 | module cannot be found then :exc:`ImportError` is raised. |
| 258 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 259 | .. method:: bytecode_path(fullname) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 260 | |
| 261 | An abstract method which returns the path to the bytecode for the |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 262 | specified module, if it exists. It returns :keyword:`None` |
| 263 | if no bytecode exists (yet). |
| 264 | Raises :exc:`ImportError` if the module is not found. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 265 | |
Brett Cannon | 9c751b7 | 2009-03-09 16:28:16 +0000 | [diff] [blame] | 266 | .. method:: write_bytecode(fullname, bytecode) |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 267 | |
| 268 | An abstract method which has the loader write *bytecode* for future |
| 269 | use. If the bytecode is written, return :keyword:`True`. Return |
| 270 | :keyword:`False` if the bytecode could not be written. This method |
| 271 | should not be called if :data:`sys.dont_write_bytecode` is true. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 272 | The *bytecode* argument should be a bytes string or bytes array. |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 273 | |
| 274 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 275 | :mod:`importlib.machinery` -- Importers and path hooks |
| 276 | ------------------------------------------------------ |
| 277 | |
| 278 | .. module:: importlib.machinery |
| 279 | :synopsis: Importers and path hooks |
| 280 | |
| 281 | This module contains the various objects that help :keyword:`import` |
| 282 | find and load modules. |
| 283 | |
| 284 | .. class:: BuiltinImporter |
| 285 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 286 | An :term:`importer` for built-in modules. All known built-in modules are |
| 287 | listed in :data:`sys.builtin_module_names`. This class implements the |
Brett Cannon | a113ac5 | 2009-03-15 01:41:33 +0000 | [diff] [blame] | 288 | :class:`importlib.abc.Finder` and :class:`importlib.abc.InspectLoader` |
| 289 | ABCs. |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 290 | |
| 291 | Only class methods are defined by this class to alleviate the need for |
| 292 | instantiation. |
| 293 | |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 294 | |
| 295 | .. class:: FrozenImporter |
| 296 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 297 | An :term:`importer` for frozen modules. This class implements the |
Brett Cannon | 8d11013 | 2009-03-15 02:20:16 +0000 | [diff] [blame] | 298 | :class:`importlib.abc.Finder` and :class:`importlib.abc.InspectLoader` |
| 299 | ABCs. |
Brett Cannon | 78246b6 | 2009-01-25 04:56:30 +0000 | [diff] [blame] | 300 | |
| 301 | Only class methods are defined by this class to alleviate the need for |
| 302 | instantiation. |
| 303 | |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 304 | |
| 305 | .. class:: PathFinder |
| 306 | |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 307 | :term:`Finder` for :data:`sys.path`. This class implements the |
| 308 | :class:`importlib.abc.Finder` ABC. |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 309 | |
| 310 | This class does not perfectly mirror the semantics of :keyword:`import` in |
| 311 | terms of :data:`sys.path`. No implicit path hooks are assumed for |
| 312 | simplification of the class and its semantics. |
| 313 | |
| 314 | Only class method are defined by this class to alleviate the need for |
| 315 | instantiation. |
| 316 | |
| 317 | .. classmethod:: find_module(fullname, path=None) |
| 318 | |
| 319 | Class method that attempts to find a :term:`loader` for the module |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 320 | specified by *fullname* on :data:`sys.path` or, if defined, on |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 321 | *path*. For each path entry that is searched, |
| 322 | :data:`sys.path_importer_cache` is checked. If an non-false object is |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 323 | found then it is used as the :term:`finder` to look for the module |
| 324 | being searched for. If no entry is found in |
Brett Cannon | debb98d | 2009-02-16 04:18:01 +0000 | [diff] [blame] | 325 | :data:`sys.path_importer_cache`, then :data:`sys.path_hooks` is |
| 326 | searched for a finder for the path entry and, if found, is stored in |
| 327 | :data:`sys.path_importer_cache` along with being queried about the |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 328 | module. If no finder is ever found then :keyword:`None` is returned. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 329 | |
| 330 | |
| 331 | :mod:`importlib.util` -- Utility code for importers |
| 332 | --------------------------------------------------- |
| 333 | |
| 334 | .. module:: importlib.util |
| 335 | :synopsis: Importers and path hooks |
| 336 | |
| 337 | This module contains the various objects that help in the construction of |
| 338 | an :term:`importer`. |
| 339 | |
| 340 | .. function:: module_for_loader(method) |
| 341 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 342 | A :term:`decorator` for a :term:`loader` method, |
| 343 | to handle selecting the proper |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 344 | 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] | 345 | signature taking two positional arguments |
| 346 | (e.g. ``load_module(self, module)``) for which the second argument |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 347 | will be the module **object** to be used by the loader. |
| 348 | Note that the decorator |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 349 | will not work on static methods because of the assumption of two |
Brett Cannon | 2a922ed | 2009-03-09 03:35:50 +0000 | [diff] [blame] | 350 | arguments. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 351 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 352 | The decorated method will take in the **name** of the module to be loaded |
| 353 | as expected for a :term:`loader`. If the module is not found in |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 354 | :data:`sys.modules` then a new one is constructed with its |
| 355 | :attr:`__name__` attribute set. Otherwise the module found in |
| 356 | :data:`sys.modules` will be passed into the method. If an |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 357 | exception is raised by the decorated method and a module was added to |
| 358 | :data:`sys.modules` it will be removed to prevent a partially initialized |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 359 | module from being in left in :data:`sys.modules`. If the module was already |
| 360 | in :data:`sys.modules` then it is left alone. |
Brett Cannon | d2e7b33 | 2009-02-17 02:45:03 +0000 | [diff] [blame] | 361 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 362 | Use of this decorator handles all the details of which module object a |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 363 | loader should initialize as specified by :pep:`302`. |
| 364 | |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 365 | .. function:: set_loader(fxn) |
| 366 | |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 367 | A :term:`decorator` for a :term:`loader` method, |
| 368 | to set the :attr:`__loader__` |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 369 | attribute on loaded modules. If the attribute is already set the decorator |
| 370 | does nothing. It is assumed that the first positional argument to the |
| 371 | wrapped method is what :attr:`__loader__` should be set to. |
| 372 | |
Brett Cannon | 2cf03a8 | 2009-03-10 05:17:37 +0000 | [diff] [blame] | 373 | .. function:: set_package(fxn) |
Brett Cannon | 57b46f5 | 2009-03-02 14:38:26 +0000 | [diff] [blame] | 374 | |
| 375 | A :term:`decorator` for a :term:`loader` to set the :attr:`__package__` |
| 376 | attribute on the module returned by the loader. If :attr:`__package__` is |
| 377 | set and has a value other than :keyword:`None` it will not be changed. |
| 378 | Note that the module returned by the loader is what has the attribute |
| 379 | set on and not the module found in :data:`sys.modules`. |
Guido van Rossum | 0961354 | 2009-03-30 20:34:57 +0000 | [diff] [blame] | 380 | |
Brett Cannon | 16248a4 | 2009-04-01 20:47:14 +0000 | [diff] [blame] | 381 | Reliance on this decorator is discouraged when it is possible to set |
| 382 | :attr:`__package__` before the execution of the code is possible. By |
| 383 | setting it before the code for the module is executed it allows the |
| 384 | attribute to be used at the global level of the module during |
| 385 | initialization. |
| 386 | |
Brett Cannon | 9f4cb1c | 2009-04-01 23:26:47 +0000 | [diff] [blame] | 387 | |
| 388 | Example |
| 389 | ------- |
| 390 | |
Brett Cannon | bc6c2b5 | 2009-04-01 23:36:48 +0000 | [diff] [blame] | 391 | Below is an example meta path importer that uses a dict for back-end storage |
| 392 | for source code. While not an optimal solution -- manipulations of |
| 393 | :attr:`__path__` on packages does not influence import -- it does illustrate |
| 394 | what little is required to implement an importer. |
| 395 | |
Brett Cannon | 9f4cb1c | 2009-04-01 23:26:47 +0000 | [diff] [blame] | 396 | .. testcode:: |
| 397 | |
| 398 | """An importer where source is stored in a dict.""" |
| 399 | from importlib import abc |
| 400 | |
| 401 | |
| 402 | class DictImporter(abc.Finder, abc.PyLoader): |
| 403 | |
| 404 | """A meta path importer that stores source code in a dict. |
| 405 | |
| 406 | The keys are the module names -- packages must end in ``.__init__``. |
| 407 | The values must be something that can be passed to 'bytes'. |
| 408 | |
| 409 | """ |
| 410 | |
| 411 | def __init__(self, memory): |
| 412 | """Store the dict.""" |
| 413 | self.memory = memory |
| 414 | |
| 415 | def contains(self, name): |
| 416 | """See if a module or package is in the dict.""" |
| 417 | if name in self.memory: |
| 418 | return name |
| 419 | package_name = '{}.__init__'.format(name) |
| 420 | if package_name in self.memory: |
| 421 | return package_name |
| 422 | return False |
| 423 | |
| 424 | __contains__ = contains # Convenience. |
| 425 | |
| 426 | def find_module(self, fullname, path=None): |
| 427 | """Find the module in the dict.""" |
| 428 | if fullname in self: |
| 429 | return self |
| 430 | return None |
| 431 | |
| 432 | def source_path(self, fullname): |
| 433 | """Return the module name if the module is in the dict.""" |
| 434 | if not fullname in self: |
| 435 | raise ImportError |
| 436 | return fullname |
| 437 | |
| 438 | def get_data(self, path): |
| 439 | """Return the bytes for the source. |
| 440 | |
| 441 | The value found in the dict is passed through 'bytes' before being |
| 442 | returned. |
| 443 | |
| 444 | """ |
| 445 | name = self.contains(path) |
| 446 | if not name: |
| 447 | raise IOError |
| 448 | return bytes(self.memory[name]) |
| 449 | |
| 450 | def is_package(self, fullname): |
| 451 | """Tell if module is a package based on whether the dict contains the |
| 452 | name with ``.__init__`` appended to it.""" |
| 453 | if fullname not in self: |
| 454 | raise ImportError |
| 455 | if fullname in self.memory: |
| 456 | return False |
| 457 | # If name is in this importer but not as it is then it must end in |
| 458 | # ``__init__``. |
| 459 | else: |
| 460 | return True |
| 461 | |
| 462 | .. testcode:: |
| 463 | :hide: |
| 464 | |
| 465 | import importlib |
| 466 | import sys |
| 467 | |
| 468 | |
| 469 | # Build the dict; keys of name, value of __package__. |
| 470 | names = {'_top_level': '', '_pkg.__init__': '_pkg', '_pkg.mod': '_pkg'} |
| 471 | source = {name: "name = {!r}".format(name).encode() for name in names} |
| 472 | |
| 473 | # Register the meta path importer. |
| 474 | importer = DictImporter(source) |
| 475 | sys.meta_path.append(importer) |
| 476 | |
| 477 | # Sanity check. |
| 478 | for name in names: |
| 479 | module = importlib.import_module(name) |
| 480 | assert module.__name__ == name |
| 481 | assert getattr(module, 'name') == name |
| 482 | assert module.__loader__ is importer |
| 483 | assert module.__package__ == names[name] |