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