Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 1 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 2 | .. _importsystem: |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 3 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 4 | ***************** |
| 5 | The import system |
| 6 | ***************** |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 7 | |
| 8 | .. index:: single: import machinery |
| 9 | |
| 10 | Python code in one :term:`module` gains access to the code in another module |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 11 | by the process of :term:`importing` it. The :keyword:`import` statement is |
| 12 | the most common way of invoking the import machinery, but it is not the only |
| 13 | way. Functions such as :func:`importlib.import_module` and built-in |
| 14 | :func:`__import__` can also be used to invoke the import machinery. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 15 | |
| 16 | The :keyword:`import` statement combines two operations; it searches for the |
| 17 | named module, then it binds the results of that search to a name in the local |
| 18 | scope. The search operation of the :keyword:`import` statement is defined as |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 19 | a call to the :func:`__import__` function, with the appropriate arguments. |
| 20 | The return value of :func:`__import__` is used to perform the name |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 21 | binding operation of the :keyword:`import` statement. See the |
| 22 | :keyword:`import` statement for the exact details of that name binding |
| 23 | operation. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 24 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 25 | A direct call to :func:`__import__` performs only the module search and, if |
| 26 | found, the module creation operation. While certain side-effects may occur, |
| 27 | such as the importing of parent packages, and the updating of various caches |
| 28 | (including :data:`sys.modules`), only the :keyword:`import` statement performs |
| 29 | a name binding operation. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 30 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 31 | When calling :func:`__import__` as part of an import statement, the |
| 32 | import system first checks the module global namespace for a function by |
| 33 | that name. If it is not found, then the standard builtin :func:`__import__` |
| 34 | is called. Other mechanisms for invoking the import system (such as |
| 35 | :func:`importlib.import_module`) do not perform this check and will always |
| 36 | use the standard import system. |
| 37 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 38 | When a module is first imported, Python searches for the module and if found, |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 39 | it creates a module object [#fnmo]_, initializing it. If the named module |
| 40 | cannot be found, an :exc:`ImportError` is raised. Python implements various |
| 41 | strategies to search for the named module when the import machinery is |
| 42 | invoked. These strategies can be modified and extended by using various hooks |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 43 | described in the sections below. |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 44 | |
| 45 | |
| 46 | :mod:`importlib` |
| 47 | ================ |
| 48 | |
| 49 | The :mod:`importlib` module provides a rich API for interacting with the |
| 50 | import system. For example :func:`importlib.import_module` provides a |
| 51 | recommended, simpler API than built-in :func:`__import__` for invoking the |
| 52 | import machinery. Refer to the :mod:`importlib` library documentation for |
| 53 | additional detail. |
| 54 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 55 | |
| 56 | |
| 57 | Packages |
| 58 | ======== |
| 59 | |
| 60 | .. index:: |
| 61 | single: package |
| 62 | |
| 63 | Python has only one type of module object, and all modules are of this type, |
| 64 | regardless of whether the module is implemented in Python, C, or something |
| 65 | else. To help organize modules and provide a naming hierarchy, Python has a |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 66 | concept of :term:`packages <package>`. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 67 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 68 | You can think of packages as the directories on a file system and modules as |
| 69 | files within directories, but don't take this analogy too literally since |
| 70 | packages and modules need not originate from the file system. For the |
| 71 | purposes of this documentation, we'll use this convenient analogy of |
| 72 | directories and files. Like file system directories, packages are organized |
| 73 | hierarchically, and packages may themselves contain subpackages, as well as |
| 74 | regular modules. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 75 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 76 | It's important to keep in mind that all packages are modules, but not all |
| 77 | modules are packages. Or put another way, packages are just a special kind of |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 78 | module. Specifically, any module that contains a ``__path__`` attribute is |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 79 | considered a package. |
| 80 | |
| 81 | All modules have a name. Subpackage names are separated from their parent |
| 82 | package name by dots, akin to Python's standard attribute access syntax. Thus |
| 83 | you might have a module called :mod:`sys` and a package called :mod:`email`, |
| 84 | which in turn has a subpackage called :mod:`email.mime` and a module within |
| 85 | that subpackage called :mod:`email.mime.text`. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 86 | |
| 87 | |
| 88 | Regular packages |
| 89 | ---------------- |
| 90 | |
| 91 | .. index:: |
| 92 | pair: package; regular |
| 93 | |
| 94 | Python defines two types of packages, :term:`regular packages <regular |
| 95 | package>` and :term:`namespace packages <namespace package>`. Regular |
| 96 | packages are traditional packages as they existed in Python 3.2 and earlier. |
| 97 | A regular package is typically implemented as a directory containing an |
| 98 | ``__init__.py`` file. When a regular package is imported, this |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 99 | ``__init__.py`` file is implicitly executed, and the objects it defines are |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 100 | bound to names in the package's namespace. The ``__init__.py`` file can |
| 101 | contain the same Python code that any other module can contain, and Python |
| 102 | will add some additional attributes to the module when it is imported. |
| 103 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 104 | For example, the following file system layout defines a top level ``parent`` |
| 105 | package with three subpackages:: |
| 106 | |
| 107 | parent/ |
| 108 | __init__.py |
| 109 | one/ |
| 110 | __init__.py |
| 111 | two/ |
| 112 | __init__.py |
| 113 | three/ |
| 114 | __init__.py |
| 115 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 116 | Importing ``parent.one`` will implicitly execute ``parent/__init__.py`` and |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 117 | ``parent/one/__init__.py``. Subsequent imports of ``parent.two`` or |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 118 | ``parent.three`` will execute ``parent/two/__init__.py`` and |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 119 | ``parent/three/__init__.py`` respectively. |
| 120 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 121 | |
| 122 | Namespace packages |
| 123 | ------------------ |
| 124 | |
| 125 | .. index:: |
| 126 | pair:: package; namespace |
| 127 | pair:: package; portion |
| 128 | |
| 129 | A namespace package is a composite of various :term:`portions <portion>`, |
| 130 | where each portion contributes a subpackage to the parent package. Portions |
| 131 | may reside in different locations on the file system. Portions may also be |
| 132 | found in zip files, on the network, or anywhere else that Python searches |
| 133 | during import. Namespace packages may or may not correspond directly to |
| 134 | objects on the file system; they may be virtual modules that have no concrete |
| 135 | representation. |
| 136 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 137 | Namespace packages do not use an ordinary list for their ``__path__`` |
| 138 | attribute. They instead use a custom iterable type which will automatically |
| 139 | perform a new search for package portions on the next import attempt within |
| 140 | that package if the path of their parent package (or :data:`sys.path` for a |
| 141 | top level package) changes. |
| 142 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 143 | With namespace packages, there is no ``parent/__init__.py`` file. In fact, |
| 144 | there may be multiple ``parent`` directories found during import search, where |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 145 | each one is provided by a different portion. Thus ``parent/one`` may not be |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 146 | physically located next to ``parent/two``. In this case, Python will create a |
| 147 | namespace package for the top-level ``parent`` package whenever it or one of |
| 148 | its subpackages is imported. |
| 149 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 150 | See also :pep:`420` for the namespace package specification. |
| 151 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 152 | |
| 153 | Searching |
| 154 | ========= |
| 155 | |
| 156 | To begin the search, Python needs the :term:`fully qualified <qualified name>` |
| 157 | name of the module (or package, but for the purposes of this discussion, the |
| 158 | difference is immaterial) being imported. This name may come from various |
| 159 | arguments to the :keyword:`import` statement, or from the parameters to the |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 160 | :func:`importlib.import_module` or :func:`__import__` functions. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 161 | |
| 162 | This name will be used in various phases of the import search, and it may be |
| 163 | the dotted path to a submodule, e.g. ``foo.bar.baz``. In this case, Python |
| 164 | first tries to import ``foo``, then ``foo.bar``, and finally ``foo.bar.baz``. |
| 165 | If any of the intermediate imports fail, an :exc:`ImportError` is raised. |
| 166 | |
| 167 | |
| 168 | The module cache |
| 169 | ---------------- |
| 170 | |
| 171 | .. index:: |
| 172 | single: sys.modules |
| 173 | |
| 174 | The first place checked during import search is :data:`sys.modules`. This |
| 175 | mapping serves as a cache of all modules that have been previously imported, |
| 176 | including the intermediate paths. So if ``foo.bar.baz`` was previously |
| 177 | imported, :data:`sys.modules` will contain entries for ``foo``, ``foo.bar``, |
| 178 | and ``foo.bar.baz``. Each key will have as its value the corresponding module |
| 179 | object. |
| 180 | |
| 181 | During import, the module name is looked up in :data:`sys.modules` and if |
| 182 | present, the associated value is the module satisfying the import, and the |
| 183 | process completes. However, if the value is ``None``, then an |
| 184 | :exc:`ImportError` is raised. If the module name is missing, Python will |
| 185 | continue searching for the module. |
| 186 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 187 | :data:`sys.modules` is writable. Deleting a key may not destroy the |
| 188 | associated module (as other modules may hold references to it), |
| 189 | but it will invalidate the cache entry for the named module, causing |
| 190 | Python to search anew for the named module upon its next |
| 191 | import. The key can also be assigned to ``None``, forcing the next import |
| 192 | of the module to result in an :exc:`ImportError`. |
| 193 | |
| 194 | Beware though, as if you keep a reference to the module object, |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 195 | invalidate its cache entry in :data:`sys.modules`, and then re-import the |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 196 | named module, the two module objects will *not* be the same. By contrast, |
| 197 | :func:`imp.reload` will reuse the *same* module object, and simply |
| 198 | reinitialise the module contents by rerunning the module's code. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 199 | |
| 200 | |
| 201 | Finders and loaders |
| 202 | ------------------- |
| 203 | |
| 204 | .. index:: |
| 205 | single: finder |
| 206 | single: loader |
| 207 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 208 | If the named module is not found in :data:`sys.modules`, then Python's import |
| 209 | protocol is invoked to find and load the module. This protocol consists of |
| 210 | two conceptual objects, :term:`finders <finder>` and :term:`loaders <loader>`. |
| 211 | A finder's job is to determine whether it can find the named module using |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 212 | whatever strategy it knows about. Objects that implement both of these |
| 213 | interfaces are referred to as :term:`importers <importer>` - they return |
| 214 | themselves when they find that they can load the requested module. |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 215 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 216 | By default, Python comes with several default finders and importers. One |
| 217 | knows how to locate frozen modules, and another knows how to locate |
| 218 | built-in modules. A third default finder searches an :term:`import path` |
| 219 | for modules. The :term:`import path` is a list of locations that may |
| 220 | name file system paths or zip files. It can also be extended to search |
| 221 | for any locatable resource, such as those identified by URLs. |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 222 | |
| 223 | The import machinery is extensible, so new finders can be added to extend the |
| 224 | range and scope of module searching. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 225 | |
| 226 | Finders do not actually load modules. If they can find the named module, they |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 227 | return a :term:`loader`, which the import machinery then invokes to load the |
| 228 | module and create the corresponding module object. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 229 | |
| 230 | The following sections describe the protocol for finders and loaders in more |
| 231 | detail, including how you can create and register new ones to extend the |
| 232 | import machinery. |
| 233 | |
| 234 | |
| 235 | Import hooks |
| 236 | ------------ |
| 237 | |
| 238 | .. index:: |
| 239 | single: import hooks |
| 240 | single: meta hooks |
| 241 | single: path hooks |
| 242 | pair: hooks; import |
| 243 | pair: hooks; meta |
| 244 | pair: hooks; path |
| 245 | |
| 246 | The import machinery is designed to be extensible; the primary mechanism for |
| 247 | this are the *import hooks*. There are two types of import hooks: *meta |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 248 | hooks* and *import path hooks*. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 249 | |
| 250 | Meta hooks are called at the start of import processing, before any other |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 251 | import processing has occurred, other than :data:`sys.modules` cache look up. |
| 252 | This allows meta hooks to override :data:`sys.path` processing, frozen |
| 253 | modules, or even built-in modules. Meta hooks are registered by adding new |
| 254 | finder objects to :data:`sys.meta_path`, as described below. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 255 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 256 | Import path hooks are called as part of :data:`sys.path` (or |
| 257 | ``package.__path__``) processing, at the point where their associated path |
| 258 | item is encountered. Import path hooks are registered by adding new callables |
| 259 | to :data:`sys.path_hooks` as described below. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 260 | |
| 261 | |
| 262 | The meta path |
| 263 | ------------- |
| 264 | |
| 265 | .. index:: |
| 266 | single: sys.meta_path |
| 267 | pair: finder; find_module |
| 268 | pair: finder; find_loader |
| 269 | |
| 270 | When the named module is not found in :data:`sys.modules`, Python next |
| 271 | searches :data:`sys.meta_path`, which contains a list of meta path finder |
| 272 | objects. These finders are queried in order to see if they know how to handle |
| 273 | the named module. Meta path finders must implement a method called |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 274 | :meth:`find_module()` which takes two arguments, a name and an import path. |
| 275 | The meta path finder can use any strategy it wants to determine whether it can |
| 276 | handle the named module or not. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 277 | |
| 278 | If the meta path finder knows how to handle the named module, it returns a |
| 279 | loader object. If it cannot handle the named module, it returns ``None``. If |
| 280 | :data:`sys.meta_path` processing reaches the end of its list without returning |
| 281 | a loader, then an :exc:`ImportError` is raised. Any other exceptions raised |
| 282 | are simply propagated up, aborting the import process. |
| 283 | |
| 284 | The :meth:`find_module()` method of meta path finders is called with two |
| 285 | arguments. The first is the fully qualified name of the module being |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 286 | imported, for example ``foo.bar.baz``. The second argument is the path |
| 287 | entries to use for the module search. For top-level modules, the second |
| 288 | argument is ``None``, but for submodules or subpackages, the second |
| 289 | argument is the value of the parent package's ``__path__`` attribute. If |
| 290 | the appropriate ``__path__`` attribute cannot be accessed, an |
| 291 | :exc:`ImportError` is raised. |
| 292 | |
| 293 | The meta path may be traversed multiple times for a single import request. |
| 294 | For example, assuming none of the modules involved has already been cached, |
| 295 | importing ``foo.bar.baz`` will first perform a top level import, calling |
| 296 | ``mpf.find_module("foo", None)`` on each meta path finder (``mpf``). After |
| 297 | ``foo`` has been imported, ``foo.bar`` will be imported by traversing the |
| 298 | meta path a second time, calling |
| 299 | ``mpf.find_module("foo.bar", foo.__path__)``. Once ``foo.bar`` has been |
| 300 | imported, the final traversal will call |
| 301 | ``mpf.find_module("foo.bar.baz", foo.bar.__path__)``. |
| 302 | |
| 303 | Some meta path finders only support top level imports. These importers will |
| 304 | always return ``None`` when anything other than ``None`` is passed as the |
| 305 | second argument. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 306 | |
| 307 | Python's default :data:`sys.meta_path` has three meta path finders, one that |
| 308 | knows how to import built-in modules, one that knows how to import frozen |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 309 | modules, and one that knows how to import modules from an :term:`import path` |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 310 | (i.e. the :term:`path importer`). |
| 311 | |
| 312 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 313 | Loaders |
| 314 | ======= |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 315 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 316 | If and when a module loader is found its |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 317 | :meth:`~importlib.abc.Loader.load_module` method is called, with a single |
| 318 | argument, the fully qualified name of the module being imported. This method |
| 319 | has several responsibilities, and should return the module object it has |
| 320 | loaded [#fnlo]_. If it cannot load the module, it should raise an |
| 321 | :exc:`ImportError`, although any other exception raised during |
| 322 | :meth:`load_module()` will be propagated. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 323 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 324 | In many cases, the finder and loader can be the same object; in such cases the |
| 325 | :meth:`finder.find_module()` would just return ``self``. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 326 | |
| 327 | Loaders must satisfy the following requirements: |
| 328 | |
| 329 | * If there is an existing module object with the given name in |
| 330 | :data:`sys.modules`, the loader must use that existing module. (Otherwise, |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 331 | :func:`imp.reload` will not work correctly.) If the named module does |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 332 | not exist in :data:`sys.modules`, the loader must create a new module |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 333 | object and add it to :data:`sys.modules`. |
| 334 | |
| 335 | Note that the module *must* exist in :data:`sys.modules` before the loader |
| 336 | executes the module code. This is crucial because the module code may |
| 337 | (directly or indirectly) import itself; adding it to :data:`sys.modules` |
| 338 | beforehand prevents unbounded recursion in the worst case and multiple |
| 339 | loading in the best. |
| 340 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 341 | If loading fails, the loader must remove any modules it has inserted into |
| 342 | :data:`sys.modules`, but it must remove **only** the failing module, and |
| 343 | only if the loader itself has loaded it explicitly. Any module already in |
| 344 | the :data:`sys.modules` cache, and any module that was successfully loaded |
| 345 | as a side-effect, must remain in the cache. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 346 | |
| 347 | * The loader may set the ``__file__`` attribute of the module. If set, this |
| 348 | attribute's value must be a string. The loader may opt to leave |
| 349 | ``__file__`` unset if it has no semantic meaning (e.g. a module loaded from |
| 350 | a database). |
| 351 | |
| 352 | * The loader may set the ``__name__`` attribute of the module. While not |
| 353 | required, setting this attribute is highly recommended so that the |
| 354 | :meth:`repr()` of the module is more informative. |
| 355 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 356 | * If the module is a package (either regular or namespace), the loader must |
| 357 | set the module object's ``__path__`` attribute. The value must be |
| 358 | iterable, but may be empty if ``__path__`` has no further significance |
| 359 | to the importer. If ``__path__`` is not empty, it must produce strings |
| 360 | when iterated over. More details on the semantics of ``__path__`` are |
| 361 | given :ref`below <package-path-rules>`. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 362 | |
| 363 | * The ``__loader__`` attribute must be set to the loader object that loaded |
| 364 | the module. This is mostly for introspection and reloading, but can be |
| 365 | used for additional importer-specific functionality, for example getting |
| 366 | data associated with an importer. |
| 367 | |
| 368 | * The module's ``__package__`` attribute should be set. Its value must be a |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 369 | string, but it can be the same value as its ``__name__``. If the attribute |
| 370 | is set to ``None`` or is missing, the import system will fill it in with a |
| 371 | more appropriate value. When the module is a package, its ``__package__`` |
| 372 | value should be set to its ``__name__``. When the module is not a package, |
| 373 | ``__package__`` should be set to the empty string for top-level modules, or |
| 374 | for submodules, to the parent package's name. See :pep:`366` for further |
| 375 | details. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 376 | |
| 377 | This attribute is used instead of ``__name__`` to calculate explicit |
| 378 | relative imports for main modules, as defined in :pep:`366`. |
| 379 | |
| 380 | * If the module is a Python module (as opposed to a built-in module or a |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 381 | dynamically loaded extension), the loader should execute the module's code |
| 382 | in the module's global name space (``module.__dict__``). |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 383 | |
| 384 | |
| 385 | Module reprs |
| 386 | ------------ |
| 387 | |
| 388 | By default, all modules have a usable repr, however depending on the |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 389 | attributes set above, and hooks in the loader, you can more explicitly control |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 390 | the repr of module objects. |
| 391 | |
| 392 | Loaders may implement a :meth:`module_repr()` method which takes a single |
| 393 | argument, the module object. When ``repr(module)`` is called for a module |
| 394 | with a loader supporting this protocol, whatever is returned from |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 395 | ``module.__loader__.module_repr(module)`` is returned as the module's repr |
| 396 | without further processing. This return value must be a string. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 397 | |
| 398 | If the module has no ``__loader__`` attribute, or the loader has no |
| 399 | :meth:`module_repr()` method, then the module object implementation itself |
| 400 | will craft a default repr using whatever information is available. It will |
| 401 | try to use the ``module.__name__``, ``module.__file__``, and |
| 402 | ``module.__loader__`` as input into the repr, with defaults for whatever |
| 403 | information is missing. |
| 404 | |
| 405 | Here are the exact rules used: |
| 406 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 407 | * If the module has a ``__loader__`` and that loader has a |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 408 | :meth:`module_repr()` method, call it with a single argument, which is the |
| 409 | module object. The value returned is used as the module's repr. |
| 410 | |
| 411 | * If an exception occurs in :meth:`module_repr()`, the exception is caught |
| 412 | and discarded, and the calculation of the module's repr continues as if |
| 413 | :meth:`module_repr()` did not exist. |
| 414 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 415 | * If the module has a ``__file__`` attribute, this is used as part of the |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 416 | module's repr. |
| 417 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 418 | * If the module has no ``__file__`` but does have a ``__loader__``, then the |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 419 | loader's repr is used as part of the module's repr. |
| 420 | |
| 421 | * Otherwise, just use the module's ``__name__`` in the repr. |
| 422 | |
| 423 | This example, from :pep:`420` shows how a loader can craft its own module |
| 424 | repr:: |
| 425 | |
| 426 | class NamespaceLoader: |
| 427 | @classmethod |
| 428 | def module_repr(cls, module): |
| 429 | return "<module '{}' (namespace)>".format(module.__name__) |
| 430 | |
| 431 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 432 | .. _package-path-rules: |
| 433 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 434 | module.__path__ |
| 435 | --------------- |
| 436 | |
| 437 | By definition, if a module has an ``__path__`` attribute, it is a package, |
| 438 | regardless of its value. |
| 439 | |
| 440 | A package's ``__path__`` attribute is used during imports of its subpackages. |
| 441 | Within the import machinery, it functions much the same as :data:`sys.path`, |
| 442 | i.e. providing a list of locations to search for modules during import. |
| 443 | However, ``__path__`` is typically much more constrained than |
| 444 | :data:`sys.path`. |
| 445 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 446 | ``__path__`` must be an iterable of strings, but it may be empty. |
| 447 | The same rules used for :data:`sys.path` also apply to a package's |
| 448 | ``__path__``, and :data:`sys.path_hooks` (described below) are |
| 449 | consulted when traversing a package's ``__path__``. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 450 | |
| 451 | A package's ``__init__.py`` file may set or alter the package's ``__path__`` |
| 452 | attribute, and this was typically the way namespace packages were implemented |
| 453 | prior to :pep:`420`. With the adoption of :pep:`420`, namespace packages no |
| 454 | longer need to supply ``__init__.py`` files containing only ``__path__`` |
| 455 | manipulation code; the namespace loader automatically sets ``__path__`` |
| 456 | correctly for the namespace package. |
| 457 | |
| 458 | |
| 459 | The Path Importer |
| 460 | ================= |
| 461 | |
| 462 | .. index:: |
| 463 | single: path importer |
| 464 | |
| 465 | As mentioned previously, Python comes with several default meta path finders. |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 466 | One of these, called the :term:`path importer`, searches an :term:`import |
| 467 | path`, which contains a list of :term:`path entries <path entry>`. Each path |
| 468 | entry names a location to search for modules. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 469 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 470 | The path importer itself doesn't know how to import anything. Instead, it |
| 471 | traverses the individual path entries, associating each of them with a |
| 472 | path entry finder that knows how to handle that particular kind of path. |
| 473 | |
| 474 | The default set of path entry finders implement all the semantics for finding |
| 475 | modules on the file system, handling special file types such as Python source |
| 476 | code (``.py`` files), Python byte code (``.pyc`` and ``.pyo`` files) and |
| 477 | shared libraries (e.g. ``.so`` files). When supported by the :mod:`zipimport` |
| 478 | module in the standard library, the default path entry finders also handle |
| 479 | loading all of these file types (other than shared libraries) from zipfiles. |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 480 | |
| 481 | Path entries need not be limited to file system locations. They can refer to |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 482 | the URLs, database queries, or any other location that can be specified as a |
| 483 | string. |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 484 | |
| 485 | The :term:`path importer` provides additional hooks and protocols so that you |
| 486 | can extend and customize the types of searchable path entries. For example, |
| 487 | if you wanted to support path entries as network URLs, you could write a hook |
| 488 | that implements HTTP semantics to find modules on the web. This hook (a |
| 489 | callable) would return a :term:`path entry finder` supporting the protocol |
| 490 | described below, which was then used to get a loader for the module from the |
| 491 | web. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 492 | |
| 493 | A word of warning: this section and the previous both use the term *finder*, |
| 494 | distinguishing between them by using the terms :term:`meta path finder` and |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 495 | :term:`path entry finder`. These two types of finders are very similar, |
| 496 | support similar protocols, and function in similar ways during the import |
| 497 | process, but it's important to keep in mind that they are subtly different. |
| 498 | In particular, meta path finders operate at the beginning of the import |
| 499 | process, as keyed off the :data:`sys.meta_path` traversal. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 500 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 501 | On the other hand, path entry finders are in a sense an implementation detail |
| 502 | of the :term:`path importer`, and in fact, if the path importer were to be |
| 503 | removed from :data:`sys.meta_path`, none of the path entry finder semantics |
| 504 | would be invoked. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 505 | |
| 506 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 507 | Path entry finders |
| 508 | ------------------ |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 509 | |
| 510 | .. index:: |
| 511 | single: sys.path |
| 512 | single: sys.path_hooks |
| 513 | single: sys.path_importer_cache |
| 514 | single: PYTHONPATH |
| 515 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 516 | The :term:`path importer` is responsible for finding and loading Python |
| 517 | modules and packages whose location is specified with a string :term:`path |
| 518 | entry`. Most path entries name locations in the file system, but they need |
| 519 | not be limited to this. |
| 520 | |
| 521 | As a meta path finder, the :term:`path importer` implements the |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 522 | :meth:`find_module()` protocol previously described, however it exposes |
| 523 | additional hooks that can be used to customize how modules are found and |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 524 | loaded from the :term:`import path`. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 525 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 526 | Three variables are used by the :term:`path importer`, :data:`sys.path`, |
| 527 | :data:`sys.path_hooks` and :data:`sys.path_importer_cache`. The ``__path__`` |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 528 | attributes on package objects are also used. These provide additional ways |
| 529 | that the import machinery can be customized. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 530 | |
| 531 | :data:`sys.path` contains a list of strings providing search locations for |
| 532 | modules and packages. It is initialized from the :data:`PYTHONPATH` |
| 533 | environment variable and various other installation- and |
| 534 | implementation-specific defaults. Entries in :data:`sys.path` can name |
| 535 | directories on the file system, zip files, and potentially other "locations" |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 536 | (see the :mod:`site` module) that should be searched for modules, such as |
| 537 | URLs, or database queries. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 538 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 539 | The :term:`path importer` is a :term:`meta path finder`, so the import |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 540 | machinery begins the :term:`import path` search by calling the path |
| 541 | importer's :meth:`find_module()` method as described previously. When |
| 542 | the ``path`` argument to :meth:`find_module()` is given, it will be a |
| 543 | list of string paths to traverse - typically a package's ``__path__`` |
| 544 | attribute for an import within that package. If the ``path`` argument |
| 545 | is ``None``, this indicates a top level import and :data:`sys.path` is used. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 546 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 547 | The :term:`path importer` iterates over every entry in the search path, and |
| 548 | for each of these, looks for an appropriate :term:`path entry finder` for the |
| 549 | path entry. Because this can be an expensive operation (e.g. there may be |
| 550 | `stat()` call overheads for this search), the :term:`path importer` maintains |
| 551 | a cache mapping path entries to path entry finders. This cache is maintained |
| 552 | in :data:`sys.path_importer_cache`. In this way, the expensive search for a |
| 553 | particular :term:`path entry` location's :term:`path entry finder` need only |
| 554 | be done once. User code is free to remove cache entries from |
| 555 | :data:`sys.path_importer_cache` forcing the :term:`path importer` to perform |
| 556 | the path entry search again [#fnpic]_. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 557 | |
| 558 | If the path entry is not present in the cache, the path importer iterates over |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 559 | every callable in :data:`sys.path_hooks`. Each of the :term:`path entry hooks |
| 560 | <path entry hook>` in this list is called with a single argument, the path |
| 561 | entry being searched. This callable may either return a :term:`path entry |
| 562 | finder` that can handle the path entry, or it may raise :exc:`ImportError`. |
| 563 | An :exc:`ImportError` is used by the path importer to signal that the hook |
| 564 | cannot find a :term:`path entry finder` for that :term:`path entry`. The |
| 565 | exception is ignored and :term:`import path` iteration continues. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 566 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 567 | If :data:`sys.path_hooks` iteration ends with no :term:`path entry finder` |
| 568 | being returned, then the path importer's :meth:`find_module()` method will |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 569 | store ``None`` in :data:`sys.path_importer_cache` (to indicate that there |
| 570 | is no finder for this path entry) and return ``None``, indicating that |
| 571 | this :term:`meta path finder` could not find the module. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 572 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 573 | If a :term:`path entry finder` *is* returned by one of the :term:`path entry |
| 574 | hook` callables on :data:`sys.path_hooks`, then the following protocol is used |
| 575 | to ask the finder for a module loader, which is then used to load the module. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 576 | |
| 577 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 578 | Path entry finder protocol |
| 579 | -------------------------- |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 580 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 581 | In order to support imports of modules and initialized packages and also to |
| 582 | contribute portions to namespace packages, path entry finders must implement |
| 583 | the :meth:`find_loader()` method. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 584 | |
| 585 | :meth:`find_loader()` takes one argument, the fully qualified name of the |
| 586 | module being imported. :meth:`find_loader()` returns a 2-tuple where the |
| 587 | first item is the loader and the second item is a namespace :term:`portion`. |
| 588 | When the first item (i.e. the loader) is ``None``, this means that while the |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 589 | path entry finder does not have a loader for the named module, it knows that the |
| 590 | path entry contributes to a namespace portion for the named module. This will |
| 591 | almost always be the case where Python is asked to import a namespace package |
| 592 | that has no physical presence on the file system. When a path entry finder |
| 593 | returns ``None`` for the loader, the second item of the 2-tuple return value |
| 594 | must be a sequence, although it can be empty. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 595 | |
| 596 | If :meth:`find_loader()` returns a non-``None`` loader value, the portion is |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 597 | ignored and the loader is returned from the path importer, terminating the |
| 598 | search through the path entries. |
| 599 | |
| 600 | For backwards compatibility with other implementations of the import |
| 601 | protocol, many path entry finders also support the same, |
| 602 | traditional :meth:`find_module()` method that meta path finders support. |
| 603 | However path entry finder :meth:`find_module()` methods are never called |
| 604 | with a ``path`` argument (they are expected to record the appropriate |
| 605 | path information from the initial call to the path hook). |
| 606 | |
| 607 | The :meth:`find_module()` method on path entry finders is deprecated, |
| 608 | as it does not allow the path entry finder to contribute portions to |
| 609 | namespace packages. Instead path entry finders should implement the |
| 610 | :meth:`find_loader()` method as described above. If it exists on the path |
| 611 | entry finder, the import system will always call :meth:`find_loader()` |
| 612 | in preference to :meth:`find_module()`. |
| 613 | |
| 614 | |
| 615 | Replacing the standard import system |
| 616 | ==================================== |
| 617 | |
| 618 | The most reliable mechanism for replacing the entire import system is to |
| 619 | delete the default contents of :data:`sys.meta_path`, replacing them |
| 620 | entirely with a custom meta path hook. |
| 621 | |
| 622 | If it is acceptable to only alter the behaviour of import statements |
| 623 | without affecting other APIs that access the import system, then replacing |
| 624 | the builtin :func:`__import__` function may be sufficient. This technique |
| 625 | may also be employed at the module level to only alter the behaviour of |
| 626 | import statements within that module. |
| 627 | |
| 628 | To selectively prevent import of some modules from a hook early on the |
| 629 | meta path (rather than disabling the standard import system entirely), |
| 630 | it is sufficient to raise :exc:`ImportError` directly from |
| 631 | :meth:`find_module` instead of returning ``None``. The latter indicates |
| 632 | that the meta path search should continue. while raising an exception |
| 633 | terminates it immediately. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 634 | |
| 635 | |
| 636 | Open issues |
| 637 | =========== |
| 638 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 639 | XXX It would be really nice to have a diagram. |
| 640 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 641 | XXX * (import_machinery.rst) how about a section devoted just to the |
| 642 | attributes of modules and packages, perhaps expanding upon or supplanting the |
| 643 | related entries in the data model reference page? |
| 644 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 645 | XXX runpy, pkgutil, et al in the library manual should all get "See Also" |
| 646 | links at the top pointing to the new import system section. |
| 647 | |
Nick Coghlan | 4941774 | 2012-08-02 23:03:58 +1000 | [diff] [blame^] | 648 | XXX The :term:`path importer` is not, in fact, an :term:`importer`. That's |
| 649 | why the corresponding implementation class is :class:`importlib.PathFinder`. |
| 650 | |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 651 | |
| 652 | References |
| 653 | ========== |
| 654 | |
| 655 | The import machinery has evolved considerably since Python's early days. The |
| 656 | original `specification for packages |
| 657 | <http://www.python.org/doc/essays/packages.html>`_ is still available to read, |
| 658 | although some details have changed since the writing of that document. |
| 659 | |
| 660 | The original specification for :data:`sys.meta_path` was :pep:`302`, with |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 661 | subsequent extension in :pep:`420`. |
| 662 | |
| 663 | :pep:`420` introduced :term:`namespace packages <namespace package>` for |
| 664 | Python 3.3. :pep:`420` also introduced the :meth:`find_loader` protocol as an |
| 665 | alternative to :meth:`find_module`. |
Barry Warsaw | d7d2194 | 2012-07-29 16:36:17 -0400 | [diff] [blame] | 666 | |
| 667 | :pep:`366` describes the addition of the ``__package__`` attribute for |
| 668 | explicit relative imports in main modules. |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 669 | |
Barry Warsaw | dadebab | 2012-07-31 16:03:09 -0400 | [diff] [blame] | 670 | :pep:`328` introduced absolute and relative imports and initially proposed |
| 671 | ``__name__`` for semantics :pep:`366` would eventually specify for |
| 672 | ``__package__``. |
| 673 | |
| 674 | :pep:`338` defines executing modules as scripts. |
| 675 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 676 | |
| 677 | Footnotes |
| 678 | ========= |
| 679 | |
| 680 | .. [#fnmo] See :class:`types.ModuleType`. |
| 681 | |
| 682 | .. [#fnlo] The importlib implementation appears not to use the return value |
| 683 | directly. Instead, it gets the module object by looking the module name up |
| 684 | in :data:`sys.modules`.) The indirect effect of this is that an imported |
| 685 | module may replace itself in :data:`sys.modules`. This is |
| 686 | implementation-specific behavior that is not guaranteed to work in other |
| 687 | Python implementations. |
| 688 | |
Barry Warsaw | c1e721b | 2012-07-30 16:24:12 -0400 | [diff] [blame] | 689 | .. [#fnpic] In legacy code, it is possible to find instances of |
| 690 | :class:`imp.NullImporter` in the :data:`sys.path_importer_cache`. It |
| 691 | recommended that code be changed to use ``None`` instead. See |
| 692 | :ref:`portingpythoncode` for more details. |