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