importlib
import
importlib.abc
importlib.machinery
importlib.util
importlib.import_module()
runpy — 定位和执行 Python 模块
runpy
Added in version 3.1.
源代码： Lib/importlib/__init__.py
目地对于 importlib package is three-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.
__import__()
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.
Three, the package contains modules exposing additional functionality for managing aspects of Python packages:
importlib.metadata presents access to metadata from third-party distributions.
importlib.metadata
importlib.resources provides routines for accessing non-code “resources” from Python packages.
importlib.resources
另请参阅
The language reference for the import 语句。
Original specification of packages. Some semantics have changed since the writing of this document (e.g. redirecting based on None in sys.modules ).
None
sys.modules
The import 语句是用于此函数的句法糖。
The initialization of sys.path .
sys.path
在不区分大小写的平台导入
定义 Python 源代码编码
新的导入挂钩
Imports: Multi-Line and Absolute/Relative
Main module explicit relative imports
隐式名称空间包
A ModuleSpec Type for the Import System
Elimination of PYO files
Multi-phase extension module initialization
Deterministic pycs
使用 UTF-8 作为默认源编码
PYC 存储库目录
实现内置 __import__() 函数。
注意
以编程方式导入模块应该使用 import_module() 而不是此函数。
import_module()
导入模块。 name 自变量按绝对 (或相对) 术语方式指定要导入什么模块 (如 pkg.mod or ..mod )。若名称以相对术语方式指定，那么 包 自变量必须被设为充当解析包名的锚点包的名称 (如 import_module('..mod', 'pkg.subpkg') 将导入 pkg.mod ).
pkg.mod
..mod
import_module('..mod', 'pkg.subpkg')
The import_module() 函数充当简化包裹器围绕 importlib.__import__() 。这意味着函数的所有语义均派生自 importlib.__import__() 。这 2 函数的最重要区别是 import_module() 返回指定包或模块 (如 pkg.mod )，而 __import__() 返回顶层包或模块 (如 pkg ).
importlib.__import__()
pkg
若要动态导入从解释器开始执行起创建的模块 (如：创建 Python 源文件)，可能需要调用 invalidate_caches() 为使新模块能被导入系统注意到。
invalidate_caches()
3.3 版改变： 自动导入父级包。
使内部缓存无效的查找器存储在 sys.meta_path 。若查找器有实现 invalidate_caches() 那么调用它将履行无效操作。应调用此函数，若运行程序时有创建/安装任何模块，以保证所有查找器都注意到新模块的存在。
sys.meta_path
Added in version 3.3.
3.10 版改变： Namespace packages created/installed in a different sys.path location after the same namespace was already imported are noticed.
重新加载先前导入的 模块 。自变量是模块对象，所以之前必须成功导入它。这很有用，若有使用外部编辑器编辑模块源文件，且想要不离开 Python 解释器试用新版本。返回值是模块对象 (可能不同，若重新导入导致不同对象被放置在 sys.modules ).
当 reload() 被执行：
reload()
Python 模块代码被重新编译且模块级代码被重新执行，定义被绑定到模块字典名称的一组新对象通过重用 loader 最初加载模块。 init 函数对于扩展模块不会被 2 次调用。
init
如 Python 所有其它对象，旧对象仅在其引用计数降至 0 后才被回收。
更新模块名称空间中的名称，以指向任何新的 (或更改) 对象。
旧对象的其它引用 (譬如：模块外部名称) 不会重新绑定到新对象引用，且必须更新它们出现的每个名称空间，若期望。
有很多其它告诫：
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
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.
sys
__main__
builtins
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 ) 代替。
from
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.
Added in version 3.4.
3.7 版改变： ModuleNotFoundError 被引发，当重新加载模块缺少 ModuleSpec .
ModuleNotFoundError
ModuleSpec
源代码： 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 +-- MetaPathFinder +-- PathEntryFinder +-- Loader +-- ResourceLoader --------+ +-- InspectLoader | +-- ExecutionLoader --+ +-- FileLoader +-- SourceLoader
An abstract base class representing a 元路径查找器 .
3.10 版改变： No longer a subclass of Finder .
Finder
An abstract method for finding a spec for the specified module. If this is a top-level import, path 将是 None . Otherwise, this is a search for a subpackage or module and path will be the value of __path__ from the parent package. If a spec cannot be found, None is returned. When passed in, target is a module object that the finder may use to make a more educated guess about what spec to return. importlib.util.spec_from_loader() may be useful for implementing concrete MetaPathFinders .
__path__
target
importlib.util.spec_from_loader()
MetaPathFinders
An optional method which, when called, should invalidate any internal cache used by the finder. Used by importlib.invalidate_caches() when invalidating the caches of all finders on sys.meta_path .
importlib.invalidate_caches()
3.4 版改变： 返回 None 当调用而不是 NotImplemented .
NotImplemented
An abstract base class representing a 路径条目查找器 . Though it bears some similarities to MetaPathFinder , PathEntryFinder is meant for use only within the path-based import subsystem provided by importlib.machinery.PathFinder .
MetaPathFinder
PathEntryFinder
importlib.machinery.PathFinder
An abstract method for finding a spec for the specified module. The finder will search for the module only within the 路径条目 to which it is assigned. If a spec cannot be found, None is returned. When passed in, target is a module object that the finder may use to make a more educated guess about what spec to return. importlib.util.spec_from_loader() may be useful for implementing concrete PathEntryFinders .
PathEntryFinders
An optional method which, when called, should invalidate any internal cache used by the finder. Used by importlib.machinery.PathFinder.invalidate_caches() when invalidating the caches of all cached finders.
importlib.machinery.PathFinder.invalidate_caches()
An abstract base class for a loader 。见 PEP 302 for the exact definition for a loader.
Loaders that wish to support resource reading should implement a get_resource_reader() method as specified by importlib.resources.abc.ResourceReader .
get_resource_reader()
importlib.resources.abc.ResourceReader
3.7 版改变： Introduced the optional get_resource_reader() 方法。
A method that returns the module object to use when importing a module. This method may return None , indicating that default module creation semantics should take place.
3.6 版改变： This method is no longer optional when exec_module() 有定义。
exec_module()
An abstract method that executes the module in its own namespace when a module is imported or reloaded. The module should already be initialized when exec_module() is called. When this method exists, create_module() 必须有定义。
create_module()
3.6 版改变： create_module() must also be defined.
A legacy method for loading a module. If the module cannot be loaded, ImportError is raised, otherwise the loaded module is returned.
ImportError
If the requested module already exists in sys.modules , that module should be used and reloaded. Otherwise the loader should create a new module and insert it into sys.modules before any loading begins, to prevent recursion from the import. If the loader inserted a module and the load fails, it must be removed by the loader from sys.modules ; modules already in sys.modules before the loader began execution should be left alone.
The loader should set several attributes on the module (note that some of these attributes can change when a module is reloaded):
__name__
The module’s fully qualified name. It is '__main__' for an executed module.
'__main__'
__file__
The location the loader used to load the module. For example, for modules loaded from a .py file this is the filename. It is not set on all modules (e.g. built-in modules).
__cached__
The filename of a compiled version of the module’s code. It is not set on all modules (e.g. built-in modules).
The list of locations where the package’s submodules will be found. Most of the time this is a single directory. The import system passes this attribute to __import__() and to finders in the same way as sys.path but just for the package. It is not set on non-package modules so it can be used as an indicator that the module is a package.
__package__
The fully qualified name of the package the module is in (or the empty string for a top-level module). If the module is a package then this is the same as __name__ .
__loader__
The loader used to load the module.
当 exec_module() is available then backwards-compatible functionality is provided.
3.4 版改变： 引发 ImportError 当调用而不是 NotImplementedError . Functionality provided when exec_module() 可用。
NotImplementedError
从 3.4 版起弃用： The recommended API for loading a module is exec_module() (和 create_module() ). Loaders should implement it instead of load_module() . The import machinery takes care of all the other responsibilities of load_module() 当 exec_module() is implemented.
load_module()
An abstract base class for a loader which implements the optional PEP 302 protocol for loading arbitrary resources from the storage back-end.
从 3.7 版起弃用： This ABC is deprecated in favour of supporting resource loading through importlib.resources.abc.ResourceReader .
An abstract method to return the bytes for the data located at path . Loaders that have a file-like storage back-end that allows storing arbitrary data can implement this abstract method to give direct access to the data stored. OSError is to be raised if the path cannot be found. The path is expected to be constructed using a module’s __file__ attribute or an item from a package’s __path__ .
OSError
3.4 版改变： 引发 OSError 而不是 NotImplementedError .
An abstract base class for a loader which implements the optional PEP 302 protocol for loaders that inspect modules.
Return the code object for a module, or None if the module does not have a code object (as would be the case, for example, for a built-in module). Raise an ImportError if loader cannot find the requested module.
While the method has a default implementation, it is suggested that it be overridden if possible for performance.
3.4 版改变： No longer abstract and a concrete implementation is provided.
An abstract method to return the source of a module. It is returned as a text string using 通用换行符 , translating all recognized line separators into '\n' characters. Returns None if no source is available (e.g. a built-in module). Raises ImportError if the loader cannot find the module specified.
'\n'
3.4 版改变： 引发 ImportError 而不是 NotImplementedError .
An optional method to return a true value if the module is a package, a false value otherwise. ImportError is raised if the loader cannot find the module.
Create a code object from Python source.
The data argument can be whatever the compile() function supports (i.e. string or bytes). The path argument should be the “path” to where the source code originated from, which can be an abstract concept (e.g. location in a zip file).
compile()
With the subsequent code object one can execute it in a module by running exec(code, module.__dict__) .
exec(code, module.__dict__)
3.5 版改变： Made the method static.
Implementation of Loader.exec_module() .
Loader.exec_module()
Implementation of Loader.load_module() .
Loader.load_module()
从 3.4 版起弃用： 使用 exec_module() 代替。
An abstract base class which inherits from InspectLoader that, when implemented, helps a module to be executed as a script. The ABC represents an optional PEP 302 协议。
InspectLoader
An abstract method that is to return the value of __file__ for the specified module. If no path is available, ImportError 被引发。
If source code is available, then the method should return the path to the source file, regardless of whether a bytecode was used to load the module.
An abstract base class which inherits from ResourceLoader and ExecutionLoader , providing concrete implementations of ResourceLoader.get_data() and ExecutionLoader.get_filename() .
ResourceLoader
ExecutionLoader
ResourceLoader.get_data()
ExecutionLoader.get_filename()
The fullname argument is a fully resolved name of the module the loader is to handle. The path argument is the path to the file for the module.
The name of the module the loader can handle.
模块文件的路径。
Calls super’s load_module() .
从 3.4 版起弃用： 使用 Loader.exec_module() 代替。
返回 path .
path
读取 path as a binary file and returns the bytes from it.
An abstract base class for implementing source (and optionally bytecode) file loading. The class inherits from both ResourceLoader and ExecutionLoader , requiring the implementation of:
Should only return the path to the source file; sourceless loading is not supported.
The abstract methods defined by this class are to add optional bytecode file support. Not implementing these optional methods (or causing them to raise NotImplementedError ) causes the loader to only work with source code. Implementing the methods allows the loader to work with source and bytecode files; it does not allow for sourceless loading where only bytecode is provided. Bytecode files are an optimization to speed up loading by removing the parsing step of Python’s compiler, and so no bytecode-specific API is exposed.
Optional abstract method which returns a dict containing metadata about the specified path. Supported dictionary keys are:
dict
'mtime' (mandatory): an integer or floating-point number representing the modification time of the source code;
'mtime'
'size' (optional): the size in bytes of the source code.
'size'
Any other keys in the dictionary are ignored, to allow for future extensions. If the path cannot be handled, OSError 被引发。
Optional abstract method which returns the modification time for the specified path.
从 3.3 版起弃用： This method is deprecated in favour of path_stats() . You don’t have to implement it, but it is still available for compatibility purposes. Raise OSError if the path cannot be handled.
path_stats()
Optional abstract method which writes the specified bytes to a file path. Any intermediate directories which do not exist are to be created automatically.
When writing to the path fails because the path is read-only ( errno.EACCES / PermissionError )，不传播异常。
errno.EACCES
PermissionError
3.4 版改变： 不再引发 NotImplementedError 当调用时。
具体实现的 InspectLoader.get_code() .
InspectLoader.get_code()
具体实现的 Loader.exec_module() .
具体实现的 Loader.load_module() .
具体实现的 InspectLoader.get_source() .
InspectLoader.get_source()
具体实现的 InspectLoader.is_package() . A module is determined to be a package if its file path (as provided by ExecutionLoader.get_filename() ) is a file named __init__ when the file extension is removed and the module name itself does not end in __init__ .
InspectLoader.is_package()
__init__
Superseded by TraversableResources
An 抽象基类 to provide the ability to read resources .
From the perspective of this ABC, a resource is a binary artifact that is shipped within a package. Typically this is something like a data file that lives next to the __init__.py file of the package. The purpose of this class is to help abstract out the accessing of such data files so that it does not matter if the package and its data file(s) are stored in a e.g. zip file versus on the file system.
__init__.py
For any of methods of this class, a resource argument is expected to be a 像路径对象 which represents conceptually just a file name. This means that no subdirectory paths should be included in the resource argument. This is because the location of the package the reader is for, acts as the “directory”. Hence the metaphor for directories and file names is packages and resources, respectively. This is also why instances of this class are expected to directly correlate to a specific package (instead of potentially representing multiple packages or a module).
Loaders that wish to support resource reading are expected to provide a method called get_resource_reader(fullname) which returns an object implementing this ABC’s interface. If the module specified by fullname is not a package, this method should return None . An object compatible with this ABC should only be returned when the specified module is a package.
get_resource_reader(fullname)
Added in version 3.7.
Deprecated since version 3.12, will be removed in version 3.14: 使用 importlib.resources.abc.TraversableResources 代替。
importlib.resources.abc.TraversableResources
Returns an opened, 像文件对象 for binary reading of the resource .
If the resource cannot be found, FileNotFoundError 被引发。
FileNotFoundError
Returns the file system path to the resource .
If the resource does not concretely exist on the file system, raise FileNotFoundError .
返回 True if the named name is considered a resource. FileNotFoundError 被引发若 name does not exist.
True
返回 iterable of strings over the contents of the package. Do note that it is not required that all names returned by the iterator be actual resources, e.g. it is acceptable to return names for which is_resource() would be false.
is_resource()
Allowing non-resource names to be returned is to allow for situations where how a package and its resources are stored are known a priori and the non-resource names would be useful. For instance, returning subdirectory names is allowed so that when it is known that the package and resources are stored on the file system then those subdirectory names can be used directly.
The abstract method returns an iterable of no items.
An object with a subset of pathlib.Path methods suitable for traversing directories and opening files.
pathlib.Path
For a representation of the object on the file-system, use importlib.resources.as_file() .
importlib.resources.as_file()
Added in version 3.9.
Deprecated since version 3.12, will be removed in version 3.14: 使用 importlib.resources.abc.Traversable 代替。
importlib.resources.abc.Traversable
Abstract. The base name of this object without any parent references.
Yield Traversable 对象在 self .
Traversable
self
返回 True if self is a directory.
返回 True if self is a file.
Return Traversable child in self .
返回 Traversable child in self .
mode may be ‘r’ or ‘rb’ to open as text or binary. Return a handle suitable for reading (same as pathlib.Path.open ).
pathlib.Path.open
When opening as text, accepts encoding parameters such as those accepted by io.TextIOWrapper .
io.TextIOWrapper
Read contents of self as bytes.
Read contents of self as text.
An abstract base class for resource readers capable of serving the importlib.resources.files() interface. Subclasses importlib.resources.abc.ResourceReader and provides concrete implementations of the importlib.resources.abc.ResourceReader ’s abstract methods. Therefore, any loader supplying importlib.abc.TraversableResources also supplies ResourceReader.
importlib.resources.files()
importlib.abc.TraversableResources
Loaders that wish to support resource reading are expected to implement this interface.
返回 importlib.resources.abc.Traversable object for the loaded package.
源代码： Lib/importlib/machinery.py
此模块包含的各种对象帮助 import 查找和加载模块。
A list of strings representing the recognized file suffixes for source modules.
A list of strings representing the file suffixes for non-optimized bytecode modules.
从 3.5 版起弃用： 使用 BYTECODE_SUFFIXES 代替。
BYTECODE_SUFFIXES
A list of strings representing the file suffixes for optimized bytecode modules.
A list of strings representing the recognized file suffixes for bytecode modules (including the leading dot).
3.5 版改变： 值不再从属 __debug__ .
__debug__
A list of strings representing the recognized file suffixes for extension modules.
Returns a combined list of strings representing all file suffixes for modules recognized by the standard import machinery. This is a helper for code which simply needs to know if a filesystem path potentially refers to a module without needing any details on the kind of module (for example, inspect.getmodulename() ).
inspect.getmodulename()
An importer for built-in modules. All known built-in modules are listed in sys.builtin_module_names . This class implements the importlib.abc.MetaPathFinder and importlib.abc.InspectLoader ABCs.
sys.builtin_module_names
importlib.abc.MetaPathFinder
importlib.abc.InspectLoader
Only class methods are defined by this class to alleviate the need for instantiation.
3.5 版改变： As part of PEP 489 , the builtin importer now implements Loader.create_module() and Loader.exec_module()
Loader.create_module()
An importer for frozen modules. This class implements the importlib.abc.MetaPathFinder and importlib.abc.InspectLoader ABCs.
3.4 版改变： Gained create_module() and exec_module() 方法。
Finder for modules declared in the Windows registry. This class implements the importlib.abc.MetaPathFinder ABC.
从 3.6 版起弃用： 使用 site configuration instead. Future versions of Python may not enable this finder by default.
site
A Finder for sys.path 和包 __path__ attributes. This class implements the importlib.abc.MetaPathFinder ABC.
Class method that attempts to find a spec for the module specified by fullname on sys.path or, if defined, on path . For each path entry that is searched, sys.path_importer_cache is checked. If a non-false object is found then it is used as the 路径条目查找器 to look for the module being searched for. If no entry is found in sys.path_importer_cache ，那么 sys.path_hooks is searched for a finder for the path entry and, if found, is stored in sys.path_importer_cache along with being queried about the module. If no finder is ever found then None is both stored in the cache and returned.
sys.path_importer_cache
sys.path_hooks
3.5 版改变： If the current working directory – represented by an empty string – is no longer valid then None is returned but no value is cached in sys.path_importer_cache .
调用 importlib.abc.PathEntryFinder.invalidate_caches() on all finders stored in sys.path_importer_cache that define the method. Otherwise entries in sys.path_importer_cache 设为 None 被删除。
importlib.abc.PathEntryFinder.invalidate_caches()
3.7 版改变： Entries of None in sys.path_importer_cache 被删除。
3.4 版改变： Calls objects in sys.path_hooks with the current working directory for '' (i.e. the empty string).
''
A concrete implementation of importlib.abc.PathEntryFinder which caches results from the file system.
importlib.abc.PathEntryFinder
The path argument is the directory for which the finder is in charge of searching.
The loader_details argument is a variable number of 2-item tuples each containing a loader and a sequence of file suffixes the loader recognizes. The loaders are expected to be callables which accept two arguments of the module’s name and the path to the file found.
The finder will cache the directory contents as necessary, making stat calls for each module search to verify the cache is not outdated. Because cache staleness relies upon the granularity of the operating system’s state information of the file system, there is a potential race condition of searching for a module, creating a new file, and then searching for the module the new file represents. If the operations happen fast enough to fit within the granularity of stat calls, then the module search will fail. To prevent this from happening, when you create a module dynamically, make sure to call importlib.invalidate_caches() .
The path the finder will search in.
Attempt to find the spec to handle fullname 在 path .
Clear out the internal cache.
A class method which returns a closure for use on sys.path_hooks . An instance of FileFinder is returned by the closure using the path argument given to the closure directly and loader_details indirectly.
FileFinder
If the argument to the closure is not an existing directory, ImportError 被引发。
A concrete implementation of importlib.abc.SourceLoader by subclassing importlib.abc.FileLoader and providing some concrete implementations of other methods.
importlib.abc.SourceLoader
importlib.abc.FileLoader
The name of the module that this loader will handle.
源文件路径。
返回 True if path appears to be for a package.
具体实现的 importlib.abc.SourceLoader.path_stats() .
importlib.abc.SourceLoader.path_stats()
具体实现的 importlib.abc.SourceLoader.set_data() .
importlib.abc.SourceLoader.set_data()
具体实现的 importlib.abc.Loader.load_module() where specifying the name of the module to load is optional.
importlib.abc.Loader.load_module()
从 3.6 版起弃用： 使用 importlib.abc.Loader.exec_module() 代替。
importlib.abc.Loader.exec_module()
A concrete implementation of importlib.abc.FileLoader which can import bytecode files (i.e. no source code files exist).
Please note that direct use of bytecode files (and thus not source code files) inhibits your modules from being usable by all Python implementations or new versions of Python which change the bytecode format.
The name of the module the loader will handle.
The path to the bytecode file.
Determines if the module is a package based on path .
Returns the code object for name created from path .
name
返回 None as bytecode files have no source when this loader is used.
A concrete implementation of importlib.abc.ExecutionLoader for extension modules.
importlib.abc.ExecutionLoader
The fullname argument specifies the name of the module the loader is to support. The path argument is the path to the extension module’s file.
Note that, by default, importing an extension module will fail in subinterpreters if it doesn’t implement multi-phase init (see PEP 489 ), even if it would otherwise import successfully.
Changed in version 3.12: Multi-phase init is now required for use in subinterpreters.
Name of the module the loader supports.
Path to the extension module.
Creates the module object from the given specification in accordance with PEP 489 .
Added in version 3.5.
Initializes the given module object in accordance with PEP 489 .
返回 True if the file path points to a package’s __init__ module based on EXTENSION_SUFFIXES .
EXTENSION_SUFFIXES
返回 None as extension modules lack a code object.
返回 None as extension modules do not have source code.
A concrete implementation of importlib.abc.InspectLoader for namespace packages. This is an alias for a private class and is only made public for introspecting the __loader__ attribute on namespace packages:
>>> from importlib.machinery import NamespaceLoader >>> import my_namespace >>> isinstance(my_namespace.__loader__, NamespaceLoader) True >>> import importlib.abc >>> isinstance(my_namespace.__loader__, importlib.abc.Loader) True
Added in version 3.11.
A specification for a module’s import-system-related state. This is typically exposed as the module’s __spec__ attribute. In the descriptions below, the names in parentheses give the corresponding attribute available directly on the module object, e.g. module.__spec__.origin == module.__file__ . Note, however, that while the 值 are usually equivalent, they can differ since there is no synchronization between the two objects. For example, it is possible to update the module’s __file__ at runtime and this will not be automatically reflected in the module’s __spec__.origin , and vice versa.
__spec__
module.__spec__.origin == module.__file__
__spec__.origin
( __name__ )
The module’s fully qualified name. The finder should always set this attribute to a non-empty string.
( __loader__ )
The loader used to load the module. The finder should always set this attribute.
( __file__ )
The location the loader should use to load the module. For example, for modules loaded from a .py file this is the filename. The finder should always set this attribute to a meaningful value for the loader to use. In the uncommon case that there is not one (like for namespace packages), it should be set to None .
( __path__ )
The list of locations where the package’s submodules will be found. Most of the time this is a single directory. The finder should set this attribute to a list, even an empty one, to indicate to the import system that the module is a package. It should be set to None for non-package modules. It is set automatically later to a special object for namespace packages.
The finder may set this attribute to an object containing additional, module-specific data to use when loading the module. Otherwise it should be set to None .
( __cached__ )
The filename of a compiled version of the module’s code. The finder should always set this attribute but it may be None for modules that do not need compiled code stored.
( __package__ )
(Read-only) The fully qualified name of the package the module is in (or the empty string for a top-level module). If the module is a package then this is the same as name .
origin
False otherwise. This value impacts how origin is interpreted and how the module’s __file__ is populated.
False
源代码： Lib/importlib/util.py
This module contains the various objects that help in the construction of an importer .
The bytes which represent the bytecode version number. If you need help with loading/writing bytecode then consider importlib.abc.SourceLoader .
返回 PEP 3147 / PEP 488 path to the byte-compiled file associated with the source path . For example, if path is /foo/bar/baz.py the return value would be /foo/bar/__pycache__/baz.cpython-32.pyc for Python 3.2. The cpython-32 string comes from the current magic tag (see get_tag() ；若 sys.implementation.cache_tag is not defined then NotImplementedError will be raised).
/foo/bar/baz.py
/foo/bar/__pycache__/baz.cpython-32.pyc
cpython-32
get_tag()
sys.implementation.cache_tag
The optimization parameter is used to specify the optimization level of the bytecode file. An empty string represents no optimization, so /foo/bar/baz.py with an optimization of '' will result in a bytecode path of /foo/bar/__pycache__/baz.cpython-32.pyc . None causes the interpreter’s optimization level to be used. Any other value’s string representation is used, so /foo/bar/baz.py with an optimization of 2 will lead to the bytecode path of /foo/bar/__pycache__/baz.cpython-32.opt-2.pyc . The string representation of optimization can only be alphanumeric, else ValueError 被引发。
2
/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc
ValueError
The debug_override parameter is deprecated and can be used to override the system’s value for __debug__ 。 True value is the equivalent of setting optimization to the empty string. A False value is the same as setting optimization to 1 . If both debug_override an optimization are not None then TypeError 被引发。
1
TypeError
3.5 版改变： The optimization parameter was added and the debug_override parameter was deprecated.
3.6 版改变： 接受 像路径对象 .
Given the path 到 PEP 3147 file name, return the associated source code file path. For example, if path is /foo/bar/__pycache__/baz.cpython-32.pyc the returned path would be /foo/bar/baz.py . path need not exist, however if it does not conform to PEP 3147 or PEP 488 format, a ValueError 被引发。若 sys.implementation.cache_tag 未定义， NotImplementedError 被引发。
Decode the given bytes representing source code and return it as a string with universal newlines (as required by importlib.abc.InspectLoader.get_source() ).
importlib.abc.InspectLoader.get_source()
Resolve a relative module name to an absolute one.
若 名称 has no leading dots, then 名称 is simply returned. This allows for usage such as importlib.util.resolve_name('sys', __spec__.parent) without doing a check to see if the 包 argument is needed.
importlib.util.resolve_name('sys', __spec__.parent)
ImportError 被引发若 名称 is a relative module name but 包 is a false value (e.g. None or the empty string). ImportError is also raised if a relative name would escape its containing package (e.g. requesting ..bacon from within the spam package).
..bacon
spam
3.9 版改变： To improve consistency with import statements, raise ImportError 而不是 ValueError for invalid relative import attempts.
Find the spec for a module, optionally relative to the specified 包 name. If the module is in sys.modules ，那么 sys.modules[name].__spec__ is returned (unless the spec would be None 或未设置，在这种情况下 ValueError 被引发)。否则，搜索使用 sys.meta_path 完成。 None is returned if no spec is found.
sys.modules[name].__spec__
若 名称 is for a submodule (contains a dot), the parent module is automatically imported.
名称 and 包 work the same as for import_module() .
3.7 版改变： 引发 ModuleNotFoundError 而不是 AttributeError if 包 is in fact not a package (i.e. lacks a __path__ 属性)。
AttributeError
Create a new module based on spec and spec.loader.create_module .
spec.loader.create_module
若 spec.loader.create_module 不返回 None , then any pre-existing attributes will not be reset. Also, no AttributeError will be raised if triggered while accessing spec or setting an attribute on the module.
This function is preferred over using types.ModuleType to create a new module as spec is used to set as many import-controlled attributes on the module as possible.
types.ModuleType
A factory function for creating a ModuleSpec instance based on a loader. The parameters have the same meaning as they do for ModuleSpec. The function uses available loader APIs, such as InspectLoader.is_package() , to fill in any missing information on the spec.
A factory function for creating a ModuleSpec instance based on the path to a file. Missing information will be filled in on the spec by making use of loader APIs and by the implication that the module will be file-based.
Return the hash of source_bytes as bytes. A hash-based .pyc file embeds the source_hash() of the corresponding source file’s contents in its header.
.pyc
source_hash()
A context manager that can temporarily skip the compatibility check for extension modules. By default the check is enabled and will fail when a single-phase init module is imported in a subinterpreter. It will also fail for a multi-phase init module that doesn’t explicitly support a per-interpreter GIL, when imported in an interpreter with its own GIL.
Note that this function is meant to accommodate an unusual case; one which is likely to eventually go away. There’s is a pretty good chance this is not what you were looking for.
You can get the same effect as this function by implementing the basic interface of multi-phase init ( PEP 489 ) and lying about support for multiple interpreters (or per-interpreter GIL).
警告
Using this function to disable the check can lead to unexpected behavior and even crashes. It should only be used during extension module development.
3.12 版添加。
A class which postpones the execution of the loader of a module until the module has an attribute accessed.
This class only works with loaders that define exec_module() as control over what module type is used for the module is required. For those same reasons, the loader’s create_module() method must return None or a type for which its __class__ attribute can be mutated along with not using slots . Finally, modules which substitute the object placed into sys.modules will not work as there is no way to properly replace the module references throughout the interpreter safely; ValueError is raised if such a substitution is detected.
__class__
For projects where startup time is critical, this class allows for potentially minimizing the cost of loading a module if it is never used. For projects where startup time is not essential then use of this class is heavily discouraged due to error messages created during loading being postponed and thus occurring out of context.
3.6 版改变： Began calling create_module() , removing the compatibility warning for importlib.machinery.BuiltinImporter and importlib.machinery.ExtensionFileLoader .
importlib.machinery.BuiltinImporter
importlib.machinery.ExtensionFileLoader
A class method which returns a callable that creates a lazy loader. This is meant to be used in situations where the loader is passed by class instead of by instance.
suffixes = importlib.machinery.SOURCE_SUFFIXES loader = importlib.machinery.SourceFileLoader lazy_loader = importlib.util.LazyLoader.factory(loader) finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))
To programmatically import a module, use importlib.import_module() .
import importlib itertools = importlib.import_module('itertools')
If you need to find out if a module can be imported without actually doing the import, then you should use importlib.util.find_spec() .
importlib.util.find_spec()
注意，若 name is a submodule (contains a dot), importlib.util.find_spec() will import the parent module.
import importlib.util import sys # For illustrative purposes. name = 'itertools' if name in sys.modules: print(f"{name!r} already in sys.modules") elif (spec := importlib.util.find_spec(name)) is not None: # If you chose to perform the actual import ... module = importlib.util.module_from_spec(spec) sys.modules[name] = module spec.loader.exec_module(module) print(f"{name!r} has been imported") else: print(f"can't find the {name!r} module")
To import a Python source file directly, use the following recipe:
import importlib.util import sys # For illustrative purposes. import tokenize file_path = tokenize.__file__ module_name = tokenize.__name__ spec = importlib.util.spec_from_file_location(module_name, file_path) module = importlib.util.module_from_spec(spec) sys.modules[module_name] = module spec.loader.exec_module(module)
The example below shows how to implement lazy imports:
>>> import importlib.util >>> import sys >>> def lazy_import(name): ... spec = importlib.util.find_spec(name) ... loader = importlib.util.LazyLoader(spec.loader) ... spec.loader = loader ... module = importlib.util.module_from_spec(spec) ... sys.modules[name] = module ... loader.exec_module(module) ... return module ... >>> lazy_typing = lazy_import("typing") >>> #lazy_typing is a real module object, >>> #but it is not loaded in memory yet. >>> lazy_typing.TYPE_CHECKING False
For deep customizations of import, you typically want to implement an importer . This means managing both the finder and loader side of things. For finders there are two flavours to choose from depending on your needs: a 元路径查找器 或 路径条目查找器 . The former is what you would put on sys.meta_path while the latter is what you create using a 路径条目挂钩 on sys.path_hooks which works with sys.path entries to potentially create a finder. This example will show you how to register your own importers so that import will use them (for creating an importer for yourself, read the documentation for the appropriate classes defined within this package):
import importlib.machinery import sys # For illustrative purposes only. SpamMetaPathFinder = importlib.machinery.PathFinder SpamPathEntryFinder = importlib.machinery.FileFinder loader_details = (importlib.machinery.SourceFileLoader, importlib.machinery.SOURCE_SUFFIXES) # Setting up a meta path finder. # Make sure to put the finder in the proper location in the list in terms of # priority. sys.meta_path.append(SpamMetaPathFinder) # Setting up a path entry finder. # Make sure to put the path hook in the proper location in the list in terms # of priority. sys.path_hooks.append(SpamPathEntryFinder.path_hook(loader_details))
Import itself is implemented in Python code, making it possible to expose most of the import machinery through importlib. The following helps illustrate the various APIs that importlib exposes by providing an approximate implementation of importlib.import_module() :
import importlib.util import sys def import_module(name, package=None): """An approximate implementation of import.""" absolute_name = importlib.util.resolve_name(name, package) try: return sys.modules[absolute_name] except KeyError: pass path = None if '.' in absolute_name: parent_name, _, child_name = absolute_name.rpartition('.') parent_module = import_module(parent_name) path = parent_module.__spec__.submodule_search_locations for finder in sys.meta_path: spec = finder.find_spec(absolute_name, path) if spec is not None: break else: msg = f'No module named {absolute_name!r}' raise ModuleNotFoundError(msg, name=absolute_name) module = importlib.util.module_from_spec(spec) sys.modules[absolute_name] = module spec.loader.exec_module(module) if path is not None: setattr(parent_module, child_name, module) return module
importlib.resources – Package resource reading, opening and access
键入搜索术语或模块、类、函数名称。