Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | |
| 34 | |
| 35 | .. function:: find_module(name[, path]) |
| 36 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 37 | Try to find the module *name* on the search path *path*. If *path* is a list |
| 38 | of directory names, each directory is searched for files with any of the |
| 39 | suffixes returned by :func:`get_suffixes` above. Invalid names in the list |
| 40 | are silently ignored (but all list items must be strings). If *path* is |
| 41 | omitted or ``None``, the list of directory names given by ``sys.path`` is |
| 42 | searched, but first it searches a few special places: it tries to find a |
| 43 | built-in module with the given name (:const:`C_BUILTIN`), then a frozen |
| 44 | module (:const:`PY_FROZEN`), and on some systems some other places are looked |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame^] | 45 | in as well (on Windows, it looks in the registry which may point to a |
| 46 | specific file). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 47 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 48 | If search is successful, the return value is a 3-element tuple ``(file, |
| 49 | pathname, description)``: |
| 50 | |
| 51 | *file* is an open file object positioned at the beginning, *pathname* is the |
| 52 | 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] | 53 | 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] | 54 | module found. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 55 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 56 | If the module does not live in a file, the returned *file* is ``None``, |
| 57 | *pathname* is the empty string, and the *description* tuple contains empty |
| 58 | strings for its suffix and mode; the module type is indicated as given in |
| 59 | parentheses above. If the search is unsuccessful, :exc:`ImportError` is |
| 60 | raised. Other exceptions indicate problems with the arguments or |
| 61 | environment. |
| 62 | |
| 63 | If the module is a package, *file* is ``None``, *pathname* is the package |
| 64 | path and the last item in the *description* tuple is :const:`PKG_DIRECTORY`. |
| 65 | |
| 66 | This function does not handle hierarchical module names (names containing |
| 67 | 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] | 68 | :func:`find_module` and :func:`load_module` to find and load package *P*, and |
| 69 | then use :func:`find_module` with the *path* argument set to ``P.__path__``. |
| 70 | When *P* itself has a dotted name, apply this recipe recursively. |
| 71 | |
| 72 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 73 | .. function:: load_module(name, file, pathname, description) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
| 75 | Load a module that was previously found by :func:`find_module` (or by an |
| 76 | otherwise conducted search yielding compatible results). This function does |
| 77 | 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] | 78 | reload the module! The *name* argument indicates the full |
| 79 | module name (including the package name, if this is a submodule of a |
| 80 | package). The *file* argument is an open file, and *pathname* is the |
| 81 | corresponding file name; these can be ``None`` and ``''``, respectively, when |
| 82 | the module is a package or not being loaded from a file. The *description* |
| 83 | argument is a tuple, as would be returned by :func:`get_suffixes`, describing |
| 84 | what kind of module must be loaded. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 86 | If the load is successful, the return value is the module object; otherwise, |
| 87 | an exception (usually :exc:`ImportError`) is raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 89 | **Important:** the caller is responsible for closing the *file* argument, if |
| 90 | it was not ``None``, even when an exception is raised. This is best done |
| 91 | using a :keyword:`try` ... :keyword:`finally` statement. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
| 93 | |
| 94 | .. function:: new_module(name) |
| 95 | |
| 96 | Return a new empty module object called *name*. This object is *not* inserted |
| 97 | in ``sys.modules``. |
| 98 | |
| 99 | |
| 100 | .. function:: lock_held() |
| 101 | |
| 102 | Return ``True`` if the import lock is currently held, else ``False``. On |
| 103 | platforms without threads, always return ``False``. |
| 104 | |
| 105 | On platforms with threads, a thread executing an import holds an internal lock |
| 106 | until the import is complete. This lock blocks other threads from doing an |
| 107 | import until the original import completes, which in turn prevents other threads |
| 108 | from seeing incomplete module objects constructed by the original thread while |
| 109 | in the process of completing its import (and the imports, if any, triggered by |
| 110 | that). |
| 111 | |
| 112 | |
| 113 | .. function:: acquire_lock() |
| 114 | |
Alexandre Vassalotti | a79e33e | 2008-05-15 22:51:26 +0000 | [diff] [blame] | 115 | Acquire the interpreter's import lock for the current thread. This lock should |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 116 | be used by import hooks to ensure thread-safety when importing modules. On |
| 117 | platforms without threads, this function does nothing. |
| 118 | |
Alexandre Vassalotti | a79e33e | 2008-05-15 22:51:26 +0000 | [diff] [blame] | 119 | Once a thread has acquired the import lock, the same thread may acquire it |
| 120 | again without blocking; the thread must release it once for each time it has |
| 121 | acquired it. |
| 122 | |
| 123 | On platforms without threads, this function does nothing. |
| 124 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | |
| 126 | .. function:: release_lock() |
| 127 | |
| 128 | Release the interpreter's import lock. On platforms without threads, this |
| 129 | function does nothing. |
| 130 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
Christian Heimes | 043d6f6 | 2008-01-07 17:19:16 +0000 | [diff] [blame] | 132 | .. function:: reload(module) |
| 133 | |
| 134 | Reload a previously imported *module*. The argument must be a module object, so |
| 135 | it must have been successfully imported before. This is useful if you have |
| 136 | edited the module source file using an external editor and want to try out the |
| 137 | new version without leaving the Python interpreter. The return value is the |
| 138 | module object (the same as the *module* argument). |
| 139 | |
| 140 | When ``reload(module)`` is executed: |
| 141 | |
| 142 | * Python modules' code is recompiled and the module-level code reexecuted, |
| 143 | defining a new set of objects which are bound to names in the module's |
| 144 | dictionary. The ``init`` function of extension modules is not called a second |
| 145 | time. |
| 146 | |
| 147 | * As with all other objects in Python the old objects are only reclaimed after |
| 148 | their reference counts drop to zero. |
| 149 | |
| 150 | * The names in the module namespace are updated to point to any new or changed |
| 151 | objects. |
| 152 | |
| 153 | * Other references to the old objects (such as names external to the module) are |
| 154 | not rebound to refer to the new objects and must be updated in each namespace |
| 155 | where they occur if that is desired. |
| 156 | |
| 157 | There are a number of other caveats: |
| 158 | |
| 159 | If a module is syntactically correct but its initialization fails, the first |
| 160 | :keyword:`import` statement for it does not bind its name locally, but does |
| 161 | store a (partially initialized) module object in ``sys.modules``. To reload the |
| 162 | module you must first :keyword:`import` it again (this will bind the name to the |
| 163 | partially initialized module object) before you can :func:`reload` it. |
| 164 | |
| 165 | When a module is reloaded, its dictionary (containing the module's global |
| 166 | variables) is retained. Redefinitions of names will override the old |
| 167 | definitions, so this is generally not a problem. If the new version of a module |
| 168 | does not define a name that was defined by the old version, the old definition |
| 169 | remains. This feature can be used to the module's advantage if it maintains a |
| 170 | global table or cache of objects --- with a :keyword:`try` statement it can test |
| 171 | for the table's presence and skip its initialization if desired:: |
| 172 | |
| 173 | try: |
| 174 | cache |
| 175 | except NameError: |
| 176 | cache = {} |
| 177 | |
| 178 | It is legal though generally not very useful to reload built-in or dynamically |
| 179 | loaded modules, except for :mod:`sys`, :mod:`__main__` and :mod:`__builtin__`. |
| 180 | In many cases, however, extension modules are not designed to be initialized |
| 181 | more than once, and may fail in arbitrary ways when reloaded. |
| 182 | |
| 183 | If a module imports objects from another module using :keyword:`from` ... |
| 184 | :keyword:`import` ..., calling :func:`reload` for the other module does not |
| 185 | redefine the objects imported from it --- one way around this is to re-execute |
| 186 | the :keyword:`from` statement, another is to use :keyword:`import` and qualified |
| 187 | names (*module*.*name*) instead. |
| 188 | |
| 189 | If a module instantiates instances of a class, reloading the module that defines |
| 190 | the class does not affect the method definitions of the instances --- they |
| 191 | continue to use the old class definition. The same is true for derived classes. |
| 192 | |
| 193 | |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 194 | .. function:: acquire_lock() |
| 195 | |
| 196 | Acquires the interpreter's import lock for the current thread. This lock should |
| 197 | be used by import hooks to ensure thread-safety when importing modules. On |
| 198 | platforms without threads, this function does nothing. |
| 199 | |
| 200 | |
| 201 | .. function:: release_lock() |
| 202 | |
| 203 | Release the interpreter's import lock. On platforms without threads, this |
| 204 | function does nothing. |
| 205 | |
| 206 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 207 | The following constants with integer values, defined in this module, are used to |
| 208 | indicate the search result of :func:`find_module`. |
| 209 | |
| 210 | |
| 211 | .. data:: PY_SOURCE |
| 212 | |
| 213 | The module was found as a source file. |
| 214 | |
| 215 | |
| 216 | .. data:: PY_COMPILED |
| 217 | |
| 218 | The module was found as a compiled code object file. |
| 219 | |
| 220 | |
| 221 | .. data:: C_EXTENSION |
| 222 | |
| 223 | The module was found as dynamically loadable shared library. |
| 224 | |
| 225 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 226 | .. data:: PKG_DIRECTORY |
| 227 | |
| 228 | The module was found as a package directory. |
| 229 | |
| 230 | |
| 231 | .. data:: C_BUILTIN |
| 232 | |
| 233 | The module was found as a built-in module. |
| 234 | |
| 235 | |
| 236 | .. data:: PY_FROZEN |
| 237 | |
| 238 | The module was found as a frozen module (see :func:`init_frozen`). |
| 239 | |
| 240 | The following constant and functions are obsolete; their functionality is |
| 241 | available through :func:`find_module` or :func:`load_module`. They are kept |
| 242 | around for backward compatibility: |
| 243 | |
| 244 | |
| 245 | .. data:: SEARCH_ERROR |
| 246 | |
| 247 | Unused. |
| 248 | |
| 249 | |
| 250 | .. function:: init_builtin(name) |
| 251 | |
| 252 | Initialize the built-in module called *name* and return its module object along |
| 253 | with storing it in ``sys.modules``. If the module was already initialized, it |
| 254 | will be initialized *again*. Re-initialization involves the copying of the |
| 255 | built-in module's ``__dict__`` from the cached module over the module's entry in |
| 256 | ``sys.modules``. If there is no built-in module called *name*, ``None`` is |
| 257 | returned. |
| 258 | |
| 259 | |
| 260 | .. function:: init_frozen(name) |
| 261 | |
| 262 | Initialize the frozen module called *name* and return its module object. If |
| 263 | the module was already initialized, it will be initialized *again*. If there |
| 264 | is no frozen module called *name*, ``None`` is returned. (Frozen modules are |
| 265 | modules written in Python whose compiled byte-code object is incorporated |
| 266 | into a custom-built Python interpreter by Python's :program:`freeze` |
| 267 | utility. See :file:`Tools/freeze/` for now.) |
| 268 | |
| 269 | |
| 270 | .. function:: is_builtin(name) |
| 271 | |
| 272 | Return ``1`` if there is a built-in module called *name* which can be |
| 273 | initialized again. Return ``-1`` if there is a built-in module called *name* |
| 274 | which cannot be initialized again (see :func:`init_builtin`). Return ``0`` if |
| 275 | there is no built-in module called *name*. |
| 276 | |
| 277 | |
| 278 | .. function:: is_frozen(name) |
| 279 | |
| 280 | Return ``True`` if there is a frozen module (see :func:`init_frozen`) called |
| 281 | *name*, or ``False`` if there is no such module. |
| 282 | |
| 283 | |
| 284 | .. function:: load_compiled(name, pathname, [file]) |
| 285 | |
| 286 | .. index:: pair: file; byte-code |
| 287 | |
| 288 | Load and initialize a module implemented as a byte-compiled code file and return |
| 289 | its module object. If the module was already initialized, it will be |
| 290 | initialized *again*. The *name* argument is used to create or access a module |
| 291 | object. The *pathname* argument points to the byte-compiled code file. The |
| 292 | *file* argument is the byte-compiled code file, open for reading in binary mode, |
| 293 | from the beginning. It must currently be a real file object, not a user-defined |
| 294 | class emulating a file. |
| 295 | |
| 296 | |
| 297 | .. function:: load_dynamic(name, pathname[, file]) |
| 298 | |
| 299 | Load and initialize a module implemented as a dynamically loadable shared |
| 300 | library and return its module object. If the module was already initialized, it |
| 301 | will be initialized *again*. Re-initialization involves copying the ``__dict__`` |
| 302 | attribute of the cached instance of the module over the value used in the module |
| 303 | cached in ``sys.modules``. The *pathname* argument must point to the shared |
| 304 | library. The *name* argument is used to construct the name of the |
| 305 | initialization function: an external C function called ``initname()`` in the |
| 306 | shared library is called. The optional *file* argument is ignored. (Note: |
| 307 | using shared libraries is highly system dependent, and not all systems support |
| 308 | it.) |
| 309 | |
| 310 | |
| 311 | .. function:: load_source(name, pathname[, file]) |
| 312 | |
| 313 | Load and initialize a module implemented as a Python source file and return its |
| 314 | module object. If the module was already initialized, it will be initialized |
| 315 | *again*. The *name* argument is used to create or access a module object. The |
| 316 | *pathname* argument points to the source file. The *file* argument is the |
| 317 | source file, open for reading as text, from the beginning. It must currently be |
| 318 | a real file object, not a user-defined class emulating a file. Note that if a |
| 319 | properly matching byte-compiled file (with suffix :file:`.pyc` or :file:`.pyo`) |
| 320 | exists, it will be used instead of parsing the given source file. |
| 321 | |
| 322 | |
| 323 | .. class:: NullImporter(path_string) |
| 324 | |
| 325 | The :class:`NullImporter` type is a :pep:`302` import hook that handles |
| 326 | non-directory path strings by failing to find any modules. Calling this type |
| 327 | with an existing directory or empty string raises :exc:`ImportError`. |
| 328 | Otherwise, a :class:`NullImporter` instance is returned. |
| 329 | |
| 330 | Python adds instances of this type to ``sys.path_importer_cache`` for any path |
| 331 | entries that are not directories and are not handled by any other path hooks on |
| 332 | ``sys.path_hooks``. Instances have only one method: |
| 333 | |
| 334 | |
| 335 | .. method:: NullImporter.find_module(fullname [, path]) |
| 336 | |
| 337 | This method always returns ``None``, indicating that the requested module could |
| 338 | not be found. |
| 339 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 340 | |
| 341 | .. _examples-imp: |
| 342 | |
| 343 | Examples |
| 344 | -------- |
| 345 | |
| 346 | The following function emulates what was the standard import statement up to |
| 347 | Python 1.4 (no hierarchical module names). (This *implementation* wouldn't work |
| 348 | in that version, since :func:`find_module` has been extended and |
| 349 | :func:`load_module` has been added in 1.4.) :: |
| 350 | |
| 351 | import imp |
| 352 | import sys |
| 353 | |
| 354 | def __import__(name, globals=None, locals=None, fromlist=None): |
| 355 | # Fast path: see if the module has already been imported. |
| 356 | try: |
| 357 | return sys.modules[name] |
| 358 | except KeyError: |
| 359 | pass |
| 360 | |
| 361 | # If any of the following calls raises an exception, |
| 362 | # there's a problem we can't handle -- let the caller handle it. |
| 363 | |
| 364 | fp, pathname, description = imp.find_module(name) |
| 365 | |
| 366 | try: |
| 367 | return imp.load_module(name, fp, pathname, description) |
| 368 | finally: |
| 369 | # Since we may exit via an exception, close fp explicitly. |
| 370 | if fp: |
| 371 | fp.close() |
| 372 | |
| 373 | .. index:: module: knee |
| 374 | |
| 375 | A more complete example that implements hierarchical module names and includes a |
| 376 | :func:`reload` function can be found in the module :mod:`knee`. The :mod:`knee` |
| 377 | module can be found in :file:`Demo/imputil/` in the Python source distribution. |
| 378 | |