32.5. `importlib` — The implementation of `import`¶

3.1 版新加入.

Source code: Lib/importlib/__init__.py

32.5.1. 簡介¶

The purpose of the importlib package is two-fold. One is to provide the implementation of the import statement (and thus, by extension, the __import__() function) in Python source code. This provides an implementation of import which is portable to any Python interpreter. This also provides an implementation which is easier to comprehend than one implemented in a programming language other than Python.

Two, the components to implement import are exposed in this package, making it easier for users to create their own custom objects (known generically as an importer) to participate in the import process.

也參考

The import statement: The language reference for the import statement.
Packages specification: Original specification of packages. Some semantics have changed since the writing of this document (e.g. redirecting based on None in sys.modules).
The __import__() function: The import statement is syntactic sugar for this function.
PEP 235: Import on Case-Insensitive Platforms
PEP 263: Defining Python Source Code Encodings
PEP 302: New Import Hooks
PEP 328: Imports: Multi-Line and Absolute/Relative
PEP 366: Main module explicit relative imports
PEP 420: Implicit namespace packages
PEP 451: A ModuleSpec Type for the Import System
PEP 488: Elimination of PYO files
PEP 489: Multi-phase extension module initialization
PEP 552: Deterministic pycs
PEP 3120: Using UTF-8 as the Default Source Encoding
PEP 3147: PYC Repository Directories

32.5.2. Functions¶

importlib.__import__(name, globals=None, locals=None, fromlist=(), level=0)¶: An implementation of the built-in __import__() function.

備註

Programmatic importing of modules should use import_module() instead of this function.

importlib.import_module(name, package=None)¶

Import a module. The name argument specifies what module to import in absolute or relative terms (e.g. either pkg.mod or ..mod). If the name is specified in relative terms, then the package argument must be set to the name of the package which is to act as the anchor for resolving the package name (e.g. import_module('..mod', 'pkg.subpkg') will import pkg.mod).

The import_module() function acts as a simplifying wrapper around importlib.__import__(). This means all semantics of the function are derived from importlib.__import__(). The most important difference between these two functions is that import_module() returns the specified package or module (e.g. pkg.mod), while __import__() returns the top-level package or module (e.g. pkg).

If you are dynamically importing a module that was created since the interpreter began execution (e.g., created a Python source file), you may need to call invalidate_caches() in order for the new module to be noticed by the import system.

3.3 版更變: Parent packages are automatically imported.

importlib.find_loader(name, path=None)¶

Find the loader for a module, optionally within the specified path. If the module is in sys.modules, then sys.modules[name].__loader__ is returned (unless the loader would be None or is not set, in which case ValueError is raised). Otherwise a search using sys.meta_path is done. None is returned if no loader is found.

A dotted name does not have its parents implicitly imported as that requires loading them and that may not be desired. To properly import a submodule you will need to import all parent packages of the submodule and use the correct argument to path.

3.3 版新加入.

3.4 版更變: If __loader__ is not set, raise ValueError, just like when the attribute is set to None.

3.4 版後已棄用: Use importlib.util.find_spec() instead.

importlib.invalidate_caches()¶: Invalidate the internal caches of finders stored at sys.meta_path. If a finder implements invalidate_caches() then it will be called to perform the invalidation. This function should be called if any modules are created/installed while your program is running to guarantee all finders will notice the new module’s existence.

3.3 版新加入.

importlib.reload(module)¶

Reload a previously imported module. The argument must be a module object, so it must have been successfully imported before. This is useful if you have edited the module source file using an external editor and want to try out the new version without leaving the Python interpreter. The return value is the module object (which can be different if re-importing causes a different object to be placed in sys.modules).

When reload() is executed:

Python module’s code is recompiled and the module-level code re-executed, defining a new set of objects which are bound to names in the module’s dictionary by reusing the loader which originally loaded the module. The init function of extension modules is not called a second time.
As with all other objects in Python the old objects are only reclaimed after their reference counts drop to zero.
The names in the module namespace are updated to point to any new or changed objects.
Other references to the old objects (such as names external to the module) are not rebound to refer to the new objects and must be updated in each namespace where they occur if that is desired.

There are a number of other caveats:

When a module is reloaded, its dictionary (containing the module’s global variables) is retained. Redefinitions of names will override the old definitions, so this is generally not a problem. If the new version of a module does not define a name that was defined by the old version, the old definition remains. This feature can be used to the module’s advantage if it maintains a global table or cache of objects — with a try statement it can test for the table’s presence and skip its initialization if desired:

try:
    cache
except NameError:
    cache = {}

It is generally not very useful to reload built-in or dynamically loaded modules. Reloading sys, __main__, builtins and other key modules is not recommended. In many cases extension modules are not designed to be initialized more than once, and may fail in arbitrary ways when reloaded.

If a module imports objects from another module using from … import …, calling reload() for the other module does not redefine the objects imported from it — one way around this is to re-execute the from statement, another is to use import and qualified names (module.name) instead.

If a module instantiates instances of a class, reloading the module that defines the class does not affect the method definitions of the instances — they continue to use the old class definition. The same is true for derived classes.

3.4 版新加入.

3.7 版更變: ModuleNotFoundError is raised when the module being reloaded lacks a ModuleSpec.

32.5.3. `importlib.abc` – Abstract base classes related to import¶

Source code: Lib/importlib/abc.py

The importlib.abc module contains all of the core abstract base classes used by import. Some subclasses of the core abstract base classes are also provided to help in implementing the core ABCs.

ABC hierarchy:

object
 +-- Finder (deprecated)
 |    +-- MetaPathFinder
 |    +-- PathEntryFinder
 +-- Loader
      +-- ResourceLoader --------+
      +-- InspectLoader          |
           +-- ExecutionLoader --+
                                 +-- FileLoader
                                 +-- SourceLoader

class importlib.abc.Finder¶: An abstract base class representing a finder.

3.3 版後已棄用: Use MetaPathFinder or

32.5. importlib — The implementation of import¶

32.5.1. 簡介¶

32.5.2. Functions¶

32.5.3. importlib.abc – Abstract base classes related to import¶

32.5. `importlib` — The implementation of `import`¶

32.5.3. `importlib.abc` – Abstract base classes related to import¶