1 2 :mod:`imp` --- Access the :keyword:`import` internals 3 ===================================================== 4 5 .. module:: imp 6 :synopsis: Access the implementation of the import statement. 7 8 9 .. index:: statement: import 10 11 This module provides an interface to the mechanisms used to implement the 12 :keyword:`import` statement. It defines the following constants and functions: 13 14 15 .. function:: get_magic() 16 17 .. index:: pair: file; byte-code 18 19 Return the magic string value used to recognize byte-compiled code files 20 (:file:`.pyc` files). (This value may be different for each Python version.) 21 22 23 .. function:: get_suffixes() 24 25 Return a list of 3-element tuples, each describing a particular type of 26 module. Each triple has the form ``(suffix, mode, type)``, where *suffix* is 27 a string to be appended to the module name to form the filename to search 28 for, *mode* is the mode string to pass to the built-in :func:`open` function 29 to open the file (this can be ``'r'`` for text files or ``'rb'`` for binary 30 files), and *type* is the file type, which has one of the values 31 :const:`PY_SOURCE`, :const:`PY_COMPILED`, or :const:`C_EXTENSION`, described 32 below. 33 34 35 .. function:: find_module(name[, path]) 36 37 Try to find the module *name*. If *path* is omitted or ``None``, the list of 38 directory names given by ``sys.path`` is searched, but first a few special 39 places are searched: the function tries to find a built-in module with the 40 given name (:const:`C_BUILTIN`), then a frozen module (:const:`PY_FROZEN`), 41 and on some systems some other places are looked in as well (on Windows, it 42 looks in the registry which may point to a specific file). 43 44 Otherwise, *path* must be a list of directory names; each directory is 45 searched for files with any of the suffixes returned by :func:`get_suffixes` 46 above. Invalid names in the list are silently ignored (but all list items 47 must be strings). 48 49 If search is successful, the return value is a 3-element tuple ``(file, 50 pathname, description)``: 51 52 *file* is an open file object positioned at the beginning, *pathname* is the 53 pathname of the file found, and *description* is a 3-element tuple as 54 contained in the list returned by :func:`get_suffixes` describing the kind of 55 module found. 56 57 If the module does not live in a file, the returned *file* is ``None``, 58 *pathname* is the empty string, and the *description* tuple contains empty 59 strings for its suffix and mode; the module type is indicated as given in 60 parentheses above. If the search is unsuccessful, :exc:`ImportError` is 61 raised. Other exceptions indicate problems with the arguments or 62 environment. 63 64 If the module is a package, *file* is ``None``, *pathname* is the package 65 path and the last item in the *description* tuple is :const:`PKG_DIRECTORY`. 66 67 This function does not handle hierarchical module names (names containing 68 dots). In order to find *P.M*, that is, submodule *M* of package *P*, use 69 :func:`find_module` and :func:`load_module` to find and load package *P*, and 70 then use :func:`find_module` with the *path* argument set to ``P.__path__``. 71 When *P* itself has a dotted name, apply this recipe recursively. 72 73 74 .. function:: load_module(name, file, pathname, description) 75 76 .. index:: builtin: reload 77 78 Load a module that was previously found by :func:`find_module` (or by an 79 otherwise conducted search yielding compatible results). This function does 80 more than importing the module: if the module was already imported, it is 81 equivalent to a :func:`reload`! The *name* argument indicates the full 82 module name (including the package name, if this is a submodule of a 83 package). The *file* argument is an open file, and *pathname* is the 84 corresponding file name; these can be ``None`` and ``''``, respectively, when 85 the module is a package or not being loaded from a file. The *description* 86 argument is a tuple, as would be returned by :func:`get_suffixes`, describing 87 what kind of module must be loaded. 88 89 If the load is successful, the return value is the module object; otherwise, 90 an exception (usually :exc:`ImportError`) is raised. 91 92 **Important:** the caller is responsible for closing the *file* argument, if 93 it was not ``None``, even when an exception is raised. This is best done 94 using a :keyword:`try` ... :keyword:`finally` statement. 95 96 97 .. function:: new_module(name) 98 99 Return a new empty module object called *name*. This object is *not* inserted 100 in ``sys.modules``. 101 102 103 .. function:: lock_held() 104 105 Return ``True`` if the import lock is currently held, else ``False``. On 106 platforms without threads, always return ``False``. 107 108 On platforms with threads, a thread executing an import holds an internal lock 109 until the import is complete. This lock blocks other threads from doing an 110 import until the original import completes, which in turn prevents other threads 111 from seeing incomplete module objects constructed by the original thread while 112 in the process of completing its import (and the imports, if any, triggered by 113 that). 114 115 116 .. function:: acquire_lock() 117 118 Acquire the interpreter's import lock for the current thread. This lock should 119 be used by import hooks to ensure thread-safety when importing modules. 120 121 Once a thread has acquired the import lock, the same thread may acquire it 122 again without blocking; the thread must release it once for each time it has 123 acquired it. 124 125 On platforms without threads, this function does nothing. 126 127 .. versionadded:: 2.3 128 129 130 .. function:: release_lock() 131 132 Release the interpreter's import lock. On platforms without threads, this 133 function does nothing. 134 135 .. versionadded:: 2.3 136 137 The following constants with integer values, defined in this module, are used to 138 indicate the search result of :func:`find_module`. 139 140 141 .. data:: PY_SOURCE 142 143 The module was found as a source file. 144 145 146 .. data:: PY_COMPILED 147 148 The module was found as a compiled code object file. 149 150 151 .. data:: C_EXTENSION 152 153 The module was found as dynamically loadable shared library. 154 155 156 .. data:: PKG_DIRECTORY 157 158 The module was found as a package directory. 159 160 161 .. data:: C_BUILTIN 162 163 The module was found as a built-in module. 164 165 166 .. data:: PY_FROZEN 167 168 The module was found as a frozen module (see :func:`init_frozen`). 169 170 The following constant and functions are obsolete; their functionality is 171 available through :func:`find_module` or :func:`load_module`. They are kept 172 around for backward compatibility: 173 174 175 .. data:: SEARCH_ERROR 176 177 Unused. 178 179 180 .. function:: init_builtin(name) 181 182 Initialize the built-in module called *name* and return its module object along 183 with storing it in ``sys.modules``. If the module was already initialized, it 184 will be initialized *again*. Re-initialization involves the copying of the 185 built-in module's ``__dict__`` from the cached module over the module's entry in 186 ``sys.modules``. If there is no built-in module called *name*, ``None`` is 187 returned. 188 189 190 .. function:: init_frozen(name) 191 192 Initialize the frozen module called *name* and return its module object. If 193 the module was already initialized, it will be initialized *again*. If there 194 is no frozen module called *name*, ``None`` is returned. (Frozen modules are 195 modules written in Python whose compiled byte-code object is incorporated 196 into a custom-built Python interpreter by Python's :program:`freeze` 197 utility. See :file:`Tools/freeze/` for now.) 198 199 200 .. function:: is_builtin(name) 201 202 Return ``1`` if there is a built-in module called *name* which can be 203 initialized again. Return ``-1`` if there is a built-in module called *name* 204 which cannot be initialized again (see :func:`init_builtin`). Return ``0`` if 205 there is no built-in module called *name*. 206 207 208 .. function:: is_frozen(name) 209 210 Return ``True`` if there is a frozen module (see :func:`init_frozen`) called 211 *name*, or ``False`` if there is no such module. 212 213 214 .. function:: load_compiled(name, pathname, [file]) 215 216 .. index:: pair: file; byte-code 217 218 Load and initialize a module implemented as a byte-compiled code file and return 219 its module object. If the module was already initialized, it will be 220 initialized *again*. The *name* argument is used to create or access a module 221 object. The *pathname* argument points to the byte-compiled code file. The 222 *file* argument is the byte-compiled code file, open for reading in binary mode, 223 from the beginning. It must currently be a real file object, not a user-defined 224 class emulating a file. 225 226 227 .. function:: load_dynamic(name, pathname[, file]) 228 229 Load and initialize a module implemented as a dynamically loadable shared 230 library and return its module object. If the module was already initialized, it 231 will be initialized *again*. Re-initialization involves copying the ``__dict__`` 232 attribute of the cached instance of the module over the value used in the module 233 cached in ``sys.modules``. The *pathname* argument must point to the shared 234 library. The *name* argument is used to construct the name of the 235 initialization function: an external C function called ``initname()`` in the 236 shared library is called. The optional *file* argument is ignored. (Note: 237 using shared libraries is highly system dependent, and not all systems support 238 it.) 239 240 .. impl-detail:: 241 242 The import internals identify extension modules by filename, so doing 243 ``foo = load_dynamic("foo", "mod.so")`` and 244 ``bar = load_dynamic("bar", "mod.so")`` will result in both foo and bar 245 referring to the same module, regardless of whether or not 246 ``mod.so`` exports an ``initbar`` function. On systems which 247 support them, symlinks can be used to import multiple modules from 248 the same shared library, as each reference to the module will use 249 a different file name. 250 251 252 .. function:: load_source(name, pathname[, file]) 253 254 Load and initialize a module implemented as a Python source file and return its 255 module object. If the module was already initialized, it will be initialized 256 *again*. The *name* argument is used to create or access a module object. The 257 *pathname* argument points to the source file. The *file* argument is the 258 source file, open for reading as text, from the beginning. It must currently be 259 a real file object, not a user-defined class emulating a file. Note that if a 260 properly matching byte-compiled file (with suffix :file:`.pyc` or :file:`.pyo`) 261 exists, it will be used instead of parsing the given source file. 262 263 264 .. class:: NullImporter(path_string) 265 266 The :class:`NullImporter` type is a :pep:`302` import hook that handles 267 non-directory path strings by failing to find any modules. Calling this type 268 with an existing directory or empty string raises :exc:`ImportError`. 269 Otherwise, a :class:`NullImporter` instance is returned. 270 271 Python adds instances of this type to ``sys.path_importer_cache`` for any path 272 entries that are not directories and are not handled by any other path hooks on 273 ``sys.path_hooks``. Instances have only one method: 274 275 276 .. method:: NullImporter.find_module(fullname [, path]) 277 278 This method always returns ``None``, indicating that the requested module could 279 not be found. 280 281 .. versionadded:: 2.5 282 283 284 .. _examples-imp: 285 286 Examples 287 -------- 288 289 The following function emulates what was the standard import statement up to 290 Python 1.4 (no hierarchical module names). (This *implementation* wouldn't work 291 in that version, since :func:`find_module` has been extended and 292 :func:`load_module` has been added in 1.4.) :: 293 294 import imp 295 import sys 296 297 def __import__(name, globals=None, locals=None, fromlist=None): 298 # Fast path: see if the module has already been imported. 299 try: 300 return sys.modules[name] 301 except KeyError: 302 pass 303 304 # If any of the following calls raises an exception, 305 # there's a problem we can't handle -- let the caller handle it. 306 307 fp, pathname, description = imp.find_module(name) 308 309 try: 310 return imp.load_module(name, fp, pathname, description) 311 finally: 312 # Since we may exit via an exception, close fp explicitly. 313 if fp: 314 fp.close() 315 316 .. index:: 317 builtin: reload 318 module: knee 319 320 A more complete example that implements hierarchical module names and includes a 321 :func:`reload` function can be found in the module :mod:`knee`. The :mod:`knee` 322 module can be found in :file:`Demo/imputil/` in the Python source distribution. 323 324
