| .. index:: pair: file; byte-code |
| |
| Return the magic string value used to recognize byte-compiled code files |
| (:file:`.pyc` files). (This value may be different for each Python version.) |
| |
| |
| .. function:: get_suffixes() |
| |
n | Return a list of triples, each describing a particular type of module. Each |
n | Return a list of 3-element tuples, each describing a particular type of |
| triple has the form ``(suffix, mode, type)``, where *suffix* is a string to be |
| module. Each triple has the form ``(suffix, mode, type)``, where *suffix* is |
| appended to the module name to form the filename to search for, *mode* is the |
| a string to be appended to the module name to form the filename to search |
| mode string to pass to the built-in :func:`open` function to open the file (this |
| for, *mode* is the mode string to pass to the built-in :func:`open` function |
| can be ``'r'`` for text files or ``'rb'`` for binary files), and *type* is the |
| to open the file (this can be ``'r'`` for text files or ``'rb'`` for binary |
| file type, which has one of the values :const:`PY_SOURCE`, :const:`PY_COMPILED`, |
| files), and *type* is the file type, which has one of the values |
| or :const:`C_EXTENSION`, described below. |
| :const:`PY_SOURCE`, :const:`PY_COMPILED`, or :const:`C_EXTENSION`, described |
| below. |
| |
| |
| .. function:: find_module(name[, path]) |
| |
n | Try to find the module *name* on the search path *path*. If *path* is a list of |
n | Try to find the module *name* on the search path *path*. If *path* is a list |
| directory names, each directory is searched for files with any of the suffixes |
| of directory names, each directory is searched for files with any of the |
| returned by :func:`get_suffixes` above. Invalid names in the list are silently |
| suffixes returned by :func:`get_suffixes` above. Invalid names in the list |
| ignored (but all list items must be strings). If *path* is omitted or ``None``, |
| are silently ignored (but all list items must be strings). If *path* is |
| the list of directory names given by ``sys.path`` is searched, but first it |
| omitted or ``None``, the list of directory names given by ``sys.path`` is |
| searches a few special places: it tries to find a built-in module with the given |
| searched, but first it searches a few special places: it tries to find a |
| name (:const:`C_BUILTIN`), then a frozen module (:const:`PY_FROZEN`), and on |
| built-in module with the given name (:const:`C_BUILTIN`), then a frozen |
| some systems some other places are looked in as well (on the Mac, it looks for a |
| module (:const:`PY_FROZEN`), and on some systems some other places are looked |
| resource (:const:`PY_RESOURCE`); on Windows, it looks in the registry which may |
| in as well (on Windows, it looks in the registry which may point to a |
| point to a specific file). |
| specific file). |
| |
n | If search is successful, the return value is a triple ``(file, pathname, |
n | If search is successful, the return value is a 3-element tuple ``(file, |
| pathname, description)``: |
| |
| description)`` where *file* is an open file object positioned at the beginning, |
| *file* is an open file object positioned at the beginning, *pathname* is the |
| *pathname* is the pathname of the file found, and *description* is a triple as |
| pathname of the file found, and *description* is a 3-element tuple as |
| contained in the list returned by :func:`get_suffixes` describing the kind of |
n | module found. |
| |
| module found. If the module does not live in a file, the returned *file* is |
| If the module does not live in a file, the returned *file* is ``None``, |
| ``None``, *filename* is the empty string, and the *description* tuple contains |
| *pathname* is the empty string, and the *description* tuple contains empty |
| empty strings for its suffix and mode; the module type is as indicate in |
| strings for its suffix and mode; the module type is indicated as given in |
| parentheses above. If the search is unsuccessful, :exc:`ImportError` is raised. |
| parentheses above. If the search is unsuccessful, :exc:`ImportError` is |
| Other exceptions indicate problems with the arguments or environment. |
| raised. Other exceptions indicate problems with the arguments or |
| environment. |
| |
n | If the module is a package, *file* is ``None``, *pathname* is the package |
| path and the last item in the *description* tuple is :const:`PKG_DIRECTORY`. |
| |
| This function does not handle hierarchical module names (names containing dots). |
| This function does not handle hierarchical module names (names containing |
| In order to find *P*.*M*, that is, submodule *M* of package *P*, use |
| dots). In order to find *P*.*M*, that is, submodule *M* of package *P*, use |
| :func:`find_module` and :func:`load_module` to find and load package *P*, and |
| then use :func:`find_module` with the *path* argument set to ``P.__path__``. |
| When *P* itself has a dotted name, apply this recipe recursively. |
| |
| |
n | .. function:: load_module(name, file, filename, description) |
n | .. function:: load_module(name, file, pathname, description) |
| |
| .. index:: builtin: reload |
| |
| Load a module that was previously found by :func:`find_module` (or by an |
| otherwise conducted search yielding compatible results). This function does |
| more than importing the module: if the module was already imported, it is |
n | equivalent to a :func:`reload`! The *name* argument indicates the full module |
n | equivalent to a :func:`reload`! The *name* argument indicates the full |
| name (including the package name, if this is a submodule of a package). The |
| module name (including the package name, if this is a submodule of a |
| *file* argument is an open file, and *filename* is the corresponding file name; |
| package). The *file* argument is an open file, and *pathname* is the |
| these can be ``None`` and ``''``, respectively, when the module is not being |
| corresponding file name; these can be ``None`` and ``''``, respectively, when |
| loaded from a file. The *description* argument is a tuple, as would be returned |
| the module is a package or not being loaded from a file. The *description* |
| by :func:`get_suffixes`, describing what kind of module must be loaded. |
| argument is a tuple, as would be returned by :func:`get_suffixes`, describing |
| what kind of module must be loaded. |
| |
n | If the load is successful, the return value is the module object; otherwise, an |
n | If the load is successful, the return value is the module object; otherwise, |
| exception (usually :exc:`ImportError`) is raised. |
| an exception (usually :exc:`ImportError`) is raised. |
| |
n | **Important:** the caller is responsible for closing the *file* argument, if it |
n | **Important:** the caller is responsible for closing the *file* argument, if |
| was not ``None``, even when an exception is raised. This is best done using a |
| it was not ``None``, even when an exception is raised. This is best done |
| :keyword:`try` ... :keyword:`finally` statement. |
| using a :keyword:`try` ... :keyword:`finally` statement. |
| |
| |
| .. function:: new_module(name) |
| |
| Return a new empty module object called *name*. This object is *not* inserted |
| in ``sys.modules``. |
| |
| |
| |
| .. data:: SEARCH_ERROR |
| |
| Unused. |
| |
| |
| .. function:: init_builtin(name) |
| |
n | Initialize the built-in module called *name* and return its module object. If |
n | Initialize the built-in module called *name* and return its module object along |
| the module was already initialized, it will be initialized *again*. A few |
| with storing it in ``sys.modules``. If the module was already initialized, it |
| modules cannot be initialized twice --- attempting to initialize these again |
| will be initialized *again*. Re-initialization involves the copying of the |
| will raise an :exc:`ImportError` exception. If there is no built-in module |
| built-in module's ``__dict__`` from the cached module over the module's entry in |
| called *name*, ``None`` is returned. |
| ``sys.modules``. If there is no built-in module called *name*, ``None`` is |
| returned. |
| |
| |
| .. function:: init_frozen(name) |
| |
n | Initialize the frozen module called *name* and return its module object. If the |
n | Initialize the frozen module called *name* and return its module object. If |
| module was already initialized, it will be initialized *again*. If there is no |
| the module was already initialized, it will be initialized *again*. If there |
| frozen module called *name*, ``None`` is returned. (Frozen modules are modules |
| is no frozen module called *name*, ``None`` is returned. (Frozen modules are |
| written in Python whose compiled byte-code object is incorporated into a custom- |
| modules written in Python whose compiled byte-code object is incorporated |
| built Python interpreter by Python's :program:`freeze` utility. See |
| into a custom-built Python interpreter by Python's :program:`freeze` |
| :file:`Tools/freeze/` for now.) |
| utility. See :file:`Tools/freeze/` for now.) |
| |
| |
| .. function:: is_builtin(name) |
| |
| Return ``1`` if there is a built-in module called *name* which can be |
| initialized again. Return ``-1`` if there is a built-in module called *name* |
| which cannot be initialized again (see :func:`init_builtin`). Return ``0`` if |
| there is no built-in module called *name*. |
| from the beginning. It must currently be a real file object, not a user-defined |
| class emulating a file. |
| |
| |
| .. function:: load_dynamic(name, pathname[, file]) |
| |
| Load and initialize a module implemented as a dynamically loadable shared |
| library and return its module object. If the module was already initialized, it |
n | will be initialized *again*. Some modules don't like that and may raise an |
n | will be initialized *again*. Re-initialization involves copying the ``__dict__`` |
| exception. The *pathname* argument must point to the shared library. The |
| attribute of the cached instance of the module over the value used in the module |
| *name* argument is used to construct the name of the initialization function: an |
| cached in ``sys.modules``. The *pathname* argument must point to the shared |
| external C function called ``initname()`` in the shared library is called. The |
| library. The *name* argument is used to construct the name of the |
| optional *file* argument is ignored. (Note: using shared libraries is highly |
| initialization function: an external C function called ``initname()`` in the |
| system dependent, and not all systems support it.) |
| shared library is called. The optional *file* argument is ignored. (Note: |
| using shared libraries is highly system dependent, and not all systems support |
| it.) |
| |
| |
| .. function:: load_source(name, pathname[, file]) |
| |
| Load and initialize a module implemented as a Python source file and return its |
| module object. If the module was already initialized, it will be initialized |
| *again*. The *name* argument is used to create or access a module object. The |
| *pathname* argument points to the source file. The *file* argument is the |
| source file, open for reading as text, from the beginning. It must currently be |
| a real file object, not a user-defined class emulating a file. Note that if a |
| properly matching byte-compiled file (with suffix :file:`.pyc` or :file:`.pyo`) |
| exists, it will be used instead of parsing the given source file. |
| |
| |
| .. class:: NullImporter(path_string) |
| |
t | The :class:`NullImporter` type is a :pep:`302` import hook that handles non- |
t | The :class:`NullImporter` type is a :pep:`302` import hook that handles |
| directory path strings by failing to find any modules. Calling this type with |
| non-directory path strings by failing to find any modules. Calling this type |
| an existing directory or empty string raises :exc:`ImportError`. Otherwise, a |
| with an existing directory or empty string raises :exc:`ImportError`. |
| :class:`NullImporter` instance is returned. |
| Otherwise, a :class:`NullImporter` instance is returned. |
| |
| Python adds instances of this type to ``sys.path_importer_cache`` for any path |
| entries that are not directories and are not handled by any other path hooks on |
| ``sys.path_hooks``. Instances have only one method: |
| |
| |
| .. method:: NullImporter.find_module(fullname [, path]) |
| |