R David Murray | 33a3c50 | 2013-04-17 18:50:12 -0400 | [diff] [blame] | 1 | :mod:`imp` --- Access the :ref:`import <importsystem>` internals |
| 2 | ================================================================ |
| 3 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 4 | .. module:: imp |
| 5 | :synopsis: Access the implementation of the import statement. |
Brett Cannon | 24f60b4 | 2014-01-17 12:06:28 -0500 | [diff] [blame] | 6 | :deprecated: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | |
Brett Cannon | 24f60b4 | 2014-01-17 12:06:28 -0500 | [diff] [blame] | 8 | .. deprecated:: 3.4 |
| 9 | The :mod:`imp` package is pending deprecation in favor of :mod:`importlib`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
| 11 | .. index:: statement: import |
| 12 | |
| 13 | This module provides an interface to the mechanisms used to implement the |
| 14 | :keyword:`import` statement. It defines the following constants and functions: |
| 15 | |
| 16 | |
| 17 | .. function:: get_magic() |
| 18 | |
| 19 | .. index:: pair: file; byte-code |
| 20 | |
| 21 | Return the magic string value used to recognize byte-compiled code files |
| 22 | (:file:`.pyc` files). (This value may be different for each Python version.) |
| 23 | |
Brett Cannon | 05a647d | 2013-06-14 19:02:34 -0400 | [diff] [blame] | 24 | .. deprecated:: 3.4 |
| 25 | Use :attr:`importlib.util.MAGIC_NUMBER` instead. |
| 26 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 27 | |
| 28 | .. function:: get_suffixes() |
| 29 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 30 | Return a list of 3-element tuples, each describing a particular type of |
| 31 | module. Each triple has the form ``(suffix, mode, type)``, where *suffix* is |
| 32 | a string to be appended to the module name to form the filename to search |
| 33 | for, *mode* is the mode string to pass to the built-in :func:`open` function |
| 34 | to open the file (this can be ``'r'`` for text files or ``'rb'`` for binary |
| 35 | files), and *type* is the file type, which has one of the values |
| 36 | :const:`PY_SOURCE`, :const:`PY_COMPILED`, or :const:`C_EXTENSION`, described |
| 37 | below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
Brett Cannon | cb66eb0 | 2012-05-11 12:58:42 -0400 | [diff] [blame] | 39 | .. deprecated:: 3.3 |
| 40 | Use the constants defined on :mod:`importlib.machinery` instead. |
| 41 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
| 43 | .. function:: find_module(name[, path]) |
| 44 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 45 | Try to find the module *name*. If *path* is omitted or ``None``, the list of |
| 46 | directory names given by ``sys.path`` is searched, but first a few special |
| 47 | places are searched: the function tries to find a built-in module with the |
| 48 | given name (:const:`C_BUILTIN`), then a frozen module (:const:`PY_FROZEN`), |
| 49 | and on some systems some other places are looked in as well (on Windows, it |
| 50 | looks in the registry which may point to a specific file). |
| 51 | |
| 52 | Otherwise, *path* must be a list of directory names; each directory is |
| 53 | searched for files with any of the suffixes returned by :func:`get_suffixes` |
| 54 | above. Invalid names in the list are silently ignored (but all list items |
| 55 | must be strings). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 57 | If search is successful, the return value is a 3-element tuple ``(file, |
| 58 | pathname, description)``: |
| 59 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 60 | *file* is an open :term:`file object` positioned at the beginning, *pathname* |
| 61 | is the pathname of the file found, and *description* is a 3-element tuple as |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | contained in the list returned by :func:`get_suffixes` describing the kind of |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 63 | module found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 64 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 65 | If the module does not live in a file, the returned *file* is ``None``, |
| 66 | *pathname* is the empty string, and the *description* tuple contains empty |
| 67 | strings for its suffix and mode; the module type is indicated as given in |
| 68 | parentheses above. If the search is unsuccessful, :exc:`ImportError` is |
| 69 | raised. Other exceptions indicate problems with the arguments or |
| 70 | environment. |
| 71 | |
| 72 | If the module is a package, *file* is ``None``, *pathname* is the package |
| 73 | path and the last item in the *description* tuple is :const:`PKG_DIRECTORY`. |
| 74 | |
| 75 | This function does not handle hierarchical module names (names containing |
Senthil Kumaran | cc49790 | 2012-04-10 19:51:00 +0800 | [diff] [blame] | 76 | dots). In order to find *P.M*, that is, submodule *M* of package *P*, use |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | :func:`find_module` and :func:`load_module` to find and load package *P*, and |
| 78 | then use :func:`find_module` with the *path* argument set to ``P.__path__``. |
| 79 | When *P* itself has a dotted name, apply this recipe recursively. |
| 80 | |
Brett Cannon | 62961dd | 2012-05-13 13:04:21 -0400 | [diff] [blame] | 81 | .. deprecated:: 3.3 |
Brett Cannon | f26702b | 2014-05-09 10:37:31 -0400 | [diff] [blame] | 82 | Use :func:`importlib.util.find_spec` instead unless Python 3.3 |
| 83 | compatibility is required, in which case use |
| 84 | :func:`importlib.find_loader`. |
Brett Cannon | 62961dd | 2012-05-13 13:04:21 -0400 | [diff] [blame] | 85 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 87 | .. function:: load_module(name, file, pathname, description) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
| 89 | Load a module that was previously found by :func:`find_module` (or by an |
| 90 | otherwise conducted search yielding compatible results). This function does |
| 91 | more than importing the module: if the module was already imported, it will |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 92 | reload the module! The *name* argument indicates the full |
| 93 | module name (including the package name, if this is a submodule of a |
| 94 | package). The *file* argument is an open file, and *pathname* is the |
| 95 | corresponding file name; these can be ``None`` and ``''``, respectively, when |
| 96 | the module is a package or not being loaded from a file. The *description* |
| 97 | argument is a tuple, as would be returned by :func:`get_suffixes`, describing |
| 98 | what kind of module must be loaded. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 100 | If the load is successful, the return value is the module object; otherwise, |
| 101 | an exception (usually :exc:`ImportError`) is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 103 | **Important:** the caller is responsible for closing the *file* argument, if |
| 104 | it was not ``None``, even when an exception is raised. This is best done |
| 105 | using a :keyword:`try` ... :keyword:`finally` statement. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 106 | |
Brett Cannon | 62961dd | 2012-05-13 13:04:21 -0400 | [diff] [blame] | 107 | .. deprecated:: 3.3 |
Brett Cannon | 89df7b4 | 2013-06-18 20:49:55 -0400 | [diff] [blame] | 108 | If previously used in conjunction with :func:`imp.find_module` then |
Brett Cannon | f26702b | 2014-05-09 10:37:31 -0400 | [diff] [blame] | 109 | consider using :func:`importlib.import_module`, otherwise use the loader |
| 110 | returned by the replacement you chose for :func:`imp.find_module`. If you |
| 111 | called :func:`imp.load_module` and related functions directly then use the |
| 112 | classes in :mod:`importlib.machinery`, e.g. |
| 113 | ``importlib.machinery.SourceFileLoader(name, path).load_module()``. |
Brett Cannon | 62961dd | 2012-05-13 13:04:21 -0400 | [diff] [blame] | 114 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | |
| 116 | .. function:: new_module(name) |
| 117 | |
| 118 | Return a new empty module object called *name*. This object is *not* inserted |
| 119 | in ``sys.modules``. |
| 120 | |
Brett Cannon | 2d77204 | 2013-06-14 19:19:57 -0400 | [diff] [blame] | 121 | .. deprecated:: 3.4 |
| 122 | Use :class:`types.ModuleType` instead. |
| 123 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 124 | |
Christian Heimes | 043d6f6 | 2008-01-07 17:19:16 +0000 | [diff] [blame] | 125 | .. function:: reload(module) |
| 126 | |
| 127 | Reload a previously imported *module*. The argument must be a module object, so |
| 128 | it must have been successfully imported before. This is useful if you have |
| 129 | edited the module source file using an external editor and want to try out the |
| 130 | new version without leaving the Python interpreter. The return value is the |
| 131 | module object (the same as the *module* argument). |
| 132 | |
| 133 | When ``reload(module)`` is executed: |
| 134 | |
| 135 | * Python modules' code is recompiled and the module-level code reexecuted, |
| 136 | defining a new set of objects which are bound to names in the module's |
| 137 | dictionary. The ``init`` function of extension modules is not called a second |
| 138 | time. |
| 139 | |
| 140 | * As with all other objects in Python the old objects are only reclaimed after |
| 141 | their reference counts drop to zero. |
| 142 | |
| 143 | * The names in the module namespace are updated to point to any new or changed |
| 144 | objects. |
| 145 | |
| 146 | * Other references to the old objects (such as names external to the module) are |
| 147 | not rebound to refer to the new objects and must be updated in each namespace |
| 148 | where they occur if that is desired. |
| 149 | |
| 150 | There are a number of other caveats: |
| 151 | |
| 152 | If a module is syntactically correct but its initialization fails, the first |
| 153 | :keyword:`import` statement for it does not bind its name locally, but does |
| 154 | store a (partially initialized) module object in ``sys.modules``. To reload the |
| 155 | module you must first :keyword:`import` it again (this will bind the name to the |
| 156 | partially initialized module object) before you can :func:`reload` it. |
| 157 | |
| 158 | When a module is reloaded, its dictionary (containing the module's global |
| 159 | variables) is retained. Redefinitions of names will override the old |
| 160 | definitions, so this is generally not a problem. If the new version of a module |
| 161 | does not define a name that was defined by the old version, the old definition |
| 162 | remains. This feature can be used to the module's advantage if it maintains a |
| 163 | global table or cache of objects --- with a :keyword:`try` statement it can test |
| 164 | for the table's presence and skip its initialization if desired:: |
| 165 | |
| 166 | try: |
| 167 | cache |
| 168 | except NameError: |
| 169 | cache = {} |
| 170 | |
| 171 | It is legal though generally not very useful to reload built-in or dynamically |
Andrew Kuchling | 1d7d580 | 2013-06-20 21:17:41 -0400 | [diff] [blame] | 172 | loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`builtins`. |
Christian Heimes | 043d6f6 | 2008-01-07 17:19:16 +0000 | [diff] [blame] | 173 | In many cases, however, extension modules are not designed to be initialized |
| 174 | more than once, and may fail in arbitrary ways when reloaded. |
| 175 | |
| 176 | If a module imports objects from another module using :keyword:`from` ... |
| 177 | :keyword:`import` ..., calling :func:`reload` for the other module does not |
| 178 | redefine the objects imported from it --- one way around this is to re-execute |
| 179 | the :keyword:`from` statement, another is to use :keyword:`import` and qualified |
| 180 | names (*module*.*name*) instead. |
| 181 | |
| 182 | If a module instantiates instances of a class, reloading the module that defines |
| 183 | the class does not affect the method definitions of the instances --- they |
| 184 | continue to use the old class definition. The same is true for derived classes. |
| 185 | |
Brett Cannon | 6fd25c3 | 2013-10-25 13:46:15 -0400 | [diff] [blame] | 186 | .. versionchanged:: 3.3 |
| 187 | Relies on both ``__name__`` and ``__loader__`` being defined on the module |
| 188 | being reloaded instead of just ``__name__``. |
| 189 | |
Brett Cannon | 3fe35e6 | 2013-06-14 15:04:26 -0400 | [diff] [blame] | 190 | .. deprecated:: 3.4 |
| 191 | Use :func:`importlib.reload` instead. |
| 192 | |
Christian Heimes | 043d6f6 | 2008-01-07 17:19:16 +0000 | [diff] [blame] | 193 | |
Éric Araujo | 930df31 | 2010-12-16 06:28:48 +0000 | [diff] [blame] | 194 | The following functions are conveniences for handling :pep:`3147` byte-compiled |
| 195 | file paths. |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 196 | |
| 197 | .. versionadded:: 3.2 |
| 198 | |
| 199 | .. function:: cache_from_source(path, debug_override=None) |
| 200 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 201 | Return the :pep:`3147` path to the byte-compiled file associated with the |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 202 | source *path*. For example, if *path* is ``/foo/bar/baz.py`` the return |
| 203 | value would be ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2. |
| 204 | The ``cpython-32`` string comes from the current magic tag (see |
Brett Cannon | 19a2f59 | 2012-07-09 13:58:07 -0400 | [diff] [blame] | 205 | :func:`get_tag`; if :attr:`sys.implementation.cache_tag` is not defined then |
| 206 | :exc:`NotImplementedError` will be raised). The returned path will end in |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 207 | ``.pyc`` when ``__debug__`` is ``True`` or ``.pyo`` for an optimized Python |
| 208 | (i.e. ``__debug__`` is ``False``). By passing in ``True`` or ``False`` for |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 209 | *debug_override* you can override the system's value for ``__debug__`` for |
| 210 | extension selection. |
| 211 | |
| 212 | *path* need not exist. |
| 213 | |
Brett Cannon | 19a2f59 | 2012-07-09 13:58:07 -0400 | [diff] [blame] | 214 | .. versionchanged:: 3.3 |
| 215 | If :attr:`sys.implementation.cache_tag` is ``None``, then |
| 216 | :exc:`NotImplementedError` is raised. |
| 217 | |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 218 | .. deprecated:: 3.4 |
| 219 | Use :func:`importlib.util.cache_from_source` instead. |
| 220 | |
Benjamin Peterson | 0f4dd9a | 2010-09-13 01:31:57 +0000 | [diff] [blame] | 221 | |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 222 | .. function:: source_from_cache(path) |
| 223 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 224 | Given the *path* to a :pep:`3147` file name, return the associated source code |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 225 | file path. For example, if *path* is |
| 226 | ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be |
| 227 | ``/foo/bar/baz.py``. *path* need not exist, however if it does not conform |
Brett Cannon | 19a2f59 | 2012-07-09 13:58:07 -0400 | [diff] [blame] | 228 | to :pep:`3147` format, a ``ValueError`` is raised. If |
| 229 | :attr:`sys.implementation.cache_tag` is not defined, |
| 230 | :exc:`NotImplementedError` is raised. |
| 231 | |
| 232 | .. versionchanged:: 3.3 |
| 233 | Raise :exc:`NotImplementedError` when |
| 234 | :attr:`sys.implementation.cache_tag` is not defined. |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 235 | |
Brett Cannon | a3c9615 | 2013-06-14 22:26:30 -0400 | [diff] [blame] | 236 | .. deprecated:: 3.4 |
| 237 | Use :func:`importlib.util.source_from_cache` instead. |
| 238 | |
Benjamin Peterson | 0f4dd9a | 2010-09-13 01:31:57 +0000 | [diff] [blame] | 239 | |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 240 | .. function:: get_tag() |
| 241 | |
Victor Stinner | 766ad36 | 2010-05-14 14:36:18 +0000 | [diff] [blame] | 242 | Return the :pep:`3147` magic tag string matching this version of Python's |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 243 | magic number, as returned by :func:`get_magic`. |
| 244 | |
Brett Cannon | e4f41de | 2013-06-16 13:13:40 -0400 | [diff] [blame] | 245 | .. deprecated:: 3.4 |
Brett Cannon | 89df7b4 | 2013-06-18 20:49:55 -0400 | [diff] [blame] | 246 | Use :attr:`sys.implementation.cache_tag` directly starting |
Brett Cannon | 19a2f59 | 2012-07-09 13:58:07 -0400 | [diff] [blame] | 247 | in Python 3.3. |
| 248 | |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 249 | |
Antoine Pitrou | 6c6d3a2 | 2012-05-17 19:00:35 +0200 | [diff] [blame] | 250 | The following functions help interact with the import system's internal |
| 251 | locking mechanism. Locking semantics of imports are an implementation |
| 252 | detail which may vary from release to release. However, Python ensures |
| 253 | that circular imports work without any deadlocks. |
| 254 | |
Antoine Pitrou | 6c6d3a2 | 2012-05-17 19:00:35 +0200 | [diff] [blame] | 255 | |
| 256 | .. function:: lock_held() |
| 257 | |
| 258 | Return ``True`` if the global import lock is currently held, else |
| 259 | ``False``. On platforms without threads, always return ``False``. |
| 260 | |
| 261 | On platforms with threads, a thread executing an import first holds a |
| 262 | global import lock, then sets up a per-module lock for the rest of the |
| 263 | import. This blocks other threads from importing the same module until |
| 264 | the original import completes, preventing other threads from seeing |
| 265 | incomplete module objects constructed by the original thread. An |
| 266 | exception is made for circular imports, which by construction have to |
| 267 | expose an incomplete module object at some point. |
| 268 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 269 | .. versionchanged:: 3.3 |
| 270 | The locking scheme has changed to per-module locks for |
| 271 | the most part. A global import lock is kept for some critical tasks, |
| 272 | such as initializing the per-module locks. |
Brett Cannon | d104eef | 2012-07-13 11:26:19 -0400 | [diff] [blame] | 273 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 274 | .. deprecated:: 3.4 |
Brett Cannon | 89df7b4 | 2013-06-18 20:49:55 -0400 | [diff] [blame] | 275 | |
Brett Cannon | d104eef | 2012-07-13 11:26:19 -0400 | [diff] [blame] | 276 | |
Antoine Pitrou | 6c6d3a2 | 2012-05-17 19:00:35 +0200 | [diff] [blame] | 277 | .. function:: acquire_lock() |
| 278 | |
| 279 | Acquire the interpreter's global import lock for the current thread. |
| 280 | This lock should be used by import hooks to ensure thread-safety when |
| 281 | importing modules. |
| 282 | |
| 283 | Once a thread has acquired the import lock, the same thread may acquire it |
| 284 | again without blocking; the thread must release it once for each time it has |
| 285 | acquired it. |
| 286 | |
| 287 | On platforms without threads, this function does nothing. |
| 288 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 289 | .. versionchanged:: 3.3 |
| 290 | The locking scheme has changed to per-module locks for |
| 291 | the most part. A global import lock is kept for some critical tasks, |
| 292 | such as initializing the per-module locks. |
Brett Cannon | d104eef | 2012-07-13 11:26:19 -0400 | [diff] [blame] | 293 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 294 | .. deprecated:: 3.4 |
Brett Cannon | 89df7b4 | 2013-06-18 20:49:55 -0400 | [diff] [blame] | 295 | |
Antoine Pitrou | 6c6d3a2 | 2012-05-17 19:00:35 +0200 | [diff] [blame] | 296 | |
| 297 | .. function:: release_lock() |
| 298 | |
| 299 | Release the interpreter's global import lock. On platforms without |
| 300 | threads, this function does nothing. |
| 301 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 302 | .. versionchanged:: 3.3 |
| 303 | The locking scheme has changed to per-module locks for |
| 304 | the most part. A global import lock is kept for some critical tasks, |
| 305 | such as initializing the per-module locks. |
Brett Cannon | d104eef | 2012-07-13 11:26:19 -0400 | [diff] [blame] | 306 | |
Georg Brandl | df48b97 | 2014-03-24 09:06:18 +0100 | [diff] [blame] | 307 | .. deprecated:: 3.4 |
Brett Cannon | 89df7b4 | 2013-06-18 20:49:55 -0400 | [diff] [blame] | 308 | |
Antoine Pitrou | 6c6d3a2 | 2012-05-17 19:00:35 +0200 | [diff] [blame] | 309 | |
Barry Warsaw | 28a691b | 2010-04-17 00:19:56 +0000 | [diff] [blame] | 310 | The following constants with integer values, defined in this module, are used |
| 311 | to indicate the search result of :func:`find_module`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 312 | |
| 313 | |
| 314 | .. data:: PY_SOURCE |
| 315 | |
| 316 | The module was found as a source file. |
| 317 | |
Brett Cannon | 0c59b03 | 2012-05-11 14:27:29 -0400 | [diff] [blame] | 318 | .. deprecated:: 3.3 |
| 319 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 320 | |
| 321 | .. data:: PY_COMPILED |
| 322 | |
| 323 | The module was found as a compiled code object file. |
| 324 | |
Brett Cannon | 0c59b03 | 2012-05-11 14:27:29 -0400 | [diff] [blame] | 325 | .. deprecated:: 3.3 |
| 326 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 327 | |
| 328 | .. data:: C_EXTENSION |
| 329 | |
| 330 | The module was found as dynamically loadable shared library. |
| 331 | |
Brett Cannon | 0c59b03 | 2012-05-11 14:27:29 -0400 | [diff] [blame] | 332 | .. deprecated:: 3.3 |
| 333 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 334 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 335 | .. data:: PKG_DIRECTORY |
| 336 | |
| 337 | The module was found as a package directory. |
| 338 | |
Brett Cannon | 0c59b03 | 2012-05-11 14:27:29 -0400 | [diff] [blame] | 339 | .. deprecated:: 3.3 |
| 340 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 341 | |
| 342 | .. data:: C_BUILTIN |
| 343 | |
| 344 | The module was found as a built-in module. |
| 345 | |
Brett Cannon | 0c59b03 | 2012-05-11 14:27:29 -0400 | [diff] [blame] | 346 | .. deprecated:: 3.3 |
| 347 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 348 | |
| 349 | .. data:: PY_FROZEN |
| 350 | |
R David Murray | 1623aff | 2012-03-18 20:50:03 -0400 | [diff] [blame] | 351 | The module was found as a frozen module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 352 | |
Brett Cannon | 0c59b03 | 2012-05-11 14:27:29 -0400 | [diff] [blame] | 353 | .. deprecated:: 3.3 |
| 354 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 355 | |
| 356 | .. class:: NullImporter(path_string) |
| 357 | |
| 358 | The :class:`NullImporter` type is a :pep:`302` import hook that handles |
| 359 | non-directory path strings by failing to find any modules. Calling this type |
| 360 | with an existing directory or empty string raises :exc:`ImportError`. |
| 361 | Otherwise, a :class:`NullImporter` instance is returned. |
| 362 | |
Brett Cannon | 2514b48 | 2013-03-13 10:46:22 -0700 | [diff] [blame] | 363 | Instances have only one method: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | |
| 365 | .. method:: NullImporter.find_module(fullname [, path]) |
| 366 | |
| 367 | This method always returns ``None``, indicating that the requested module could |
| 368 | not be found. |
| 369 | |
Brett Cannon | 2514b48 | 2013-03-13 10:46:22 -0700 | [diff] [blame] | 370 | .. versionchanged:: 3.3 |
| 371 | ``None`` is inserted into ``sys.path_importer_cache`` instead of an |
| 372 | instance of :class:`NullImporter`. |
| 373 | |
Brett Cannon | e4f41de | 2013-06-16 13:13:40 -0400 | [diff] [blame] | 374 | .. deprecated:: 3.4 |
| 375 | Insert ``None`` into ``sys.path_importer_cache`` instead. |
| 376 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 377 | |
| 378 | .. _examples-imp: |
| 379 | |
| 380 | Examples |
| 381 | -------- |
| 382 | |
| 383 | The following function emulates what was the standard import statement up to |
| 384 | Python 1.4 (no hierarchical module names). (This *implementation* wouldn't work |
| 385 | in that version, since :func:`find_module` has been extended and |
| 386 | :func:`load_module` has been added in 1.4.) :: |
| 387 | |
| 388 | import imp |
| 389 | import sys |
| 390 | |
| 391 | def __import__(name, globals=None, locals=None, fromlist=None): |
| 392 | # Fast path: see if the module has already been imported. |
| 393 | try: |
| 394 | return sys.modules[name] |
| 395 | except KeyError: |
| 396 | pass |
| 397 | |
| 398 | # If any of the following calls raises an exception, |
| 399 | # there's a problem we can't handle -- let the caller handle it. |
| 400 | |
| 401 | fp, pathname, description = imp.find_module(name) |
| 402 | |
| 403 | try: |
| 404 | return imp.load_module(name, fp, pathname, description) |
| 405 | finally: |
| 406 | # Since we may exit via an exception, close fp explicitly. |
| 407 | if fp: |
| 408 | fp.close() |