5. 进口系统¶

5.2.1. 常规包¶

Python定义了两种类型的包，常规包 和 命名空间包。常规包是传统包，因为它们存在于Python 3.2及更早版本中。常规包通常实现为包含 __init__.py 文件的目录。当导入常规包时，该 __init__.py 文件被隐式执行，并且它定义的对象被绑定到包名称空间中的名称。 __init__.py 文件可以包含与任何其他模块可以包含的相同的Python代码，并且Python会在导入时为模块添加一些其他属性。

例如，以下文件系统布局定义具有三个子包的顶级 parent 包:

parent/
    __init__.py
    one/
        __init__.py
    two/
        __init__.py
    three/
        __init__.py

导入 parent.one 将隐式执行 parent/__init__.py 和 parent/one/__init__.py。随后进口的 parent.two 或 parent.three 将分别执行 parent/two/__init__.py 和 parent/three/__init__.py。

5.2.2. 命名空间包¶

命名空间包是各种 部分 的组合，其中每个部分向父包提供子包。部分可以驻留在文件系统上的不同位置。部分也可以在zip文件，网络或Python在导入期间搜索的任何其他位置找到。命名空间包可以或可以不直接对应于文件系统上的对象；它们可以是没有具体表示的虚拟模块。

命名空间包不为其 __path__ 属性使用普通列表。它们改为使用自定义可迭代类型，如果其父包（或顶级包的 sys.path）的路径发生更改，则会在该包中的下一次导入尝试时自动执行对包部分的新搜索。

使用命名空间包，没有 parent/__init__.py 文件。实际上，在导入搜索期间可能存在多个 parent 目录，其中每个由不同的部分提供。因此，parent/one 可能不在物理上位于 parent/two 旁边。在这种情况下，Python将为顶层 parent 包创建一个命名空间包，只要它被导入其中一个子包。

有关命名空间包规范的信息，请参阅 PEP 420。

5.3.1. 模块缓存¶

在导入搜索期间检查的第一个位置是 sys.modules。此映射用作先前导入的所有模块的缓存，包括中间路径。因此，如果以前导入 foo.bar.baz，则 sys.modules 将包含 foo，foo.bar 和 foo.bar.baz 的条目。每个键将具有相应的模块对象作为其值。

在导入期间，在 sys.modules 中查找模块名称，如果存在，则关联值是满足导入的模块，并且该过程完成。然而，如果值是 None，则引发 ModuleNotFoundError。如果模块名称丢失，Python将继续搜索模块。

sys.modules 是可写的。删除键可能不会破坏关联的模块（因为其他模块可能保存对它的引用），但它会使指定模块的缓存条目无效，导致Python在下次导入时重新搜索指定的模块。该键也可以分配给 None，强制下一次导入模块以产生 ModuleNotFoundError。

注意，如果你保留对模块对象的引用，使其在 sys.modules 中的缓存条目无效，然后重新导入命名的模块，两个模块对象将 not 相同。相比之下，importlib.reload() 将重用 same 模块对象，并通过重新运行模块的代码来重新初始化模块内容。

5.3.2. 查找器和装载器¶

如果在 sys.modules 中找不到指定的模块，那么将调用Python的导入协议来查找和加载模块。该协议包括两个概念对象，finders 和 装载机。 finder的工作是确定它是否可以使用知道的任何策略找到命名的模块。实现这两个接口的对象称为 进口商 - 当他们发现他们可以加载请求的模块时，它们返回自己。

Python包括多个默认查找器和导入器。第一个知道如何定位内置模块，第二个知道如何定位冻结的模块。第三个默认查找器在 import path 中搜索模块。 import path 是可以命名文件系统路径或zip文件的位置的列表。它还可以扩展为搜索任何可定位资源，例如由URL标识的资源。

导入机制是可扩展的，因此可以添加新的查找器以扩展模块搜索的范围和范围。

查找器实际上不加载模块。如果他们可以找到命名的模块，他们返回一个 module spec，模块的导入相关信息的封装，导入机制然后在加载模块时使用。

以下部分更详细地介绍查找器和装载程序的协议，包括如何创建和注册新协议以扩展导入机制。

5.3.3. 导入挂钩¶

进口机械设计为可扩展；其主要机制是 导入钩子。有两种类型的导入钩子：元钩 和 导入路径钩子。

在导入处理开始时，在发生任何其他导入处理之前调用元钩子，而不是 sys.modules 高速缓存查找。这允许元钩子重写 sys.path 处理，冻结模块，甚至内置模块。通过向 sys.meta_path 添加新的finder对象来注册元钩子，如下所述。

导入路径挂钩称为 sys.path （或 package.__path__）处理的一部分，在那里遇到它们相关的路径项目点。导入路径挂钩由下述增加新的可调用到 sys.path_hooks 注册。

5.3.4. 元路径¶

当在 sys.modules 中找不到命名的模块时，Python接下来搜索 sys.meta_path，其中包含元路径查找器对象的列表。这些查找器被查询以查看他们是否知道如何处理命名的模块。元路径查找器必须实现一个称为 find_spec() 的方法，它接受三个参数：名称，导入路径和（可选）目标模块。元路径查找器可以使用它想要的任何策略来确定它是否可以处理命名的模块。

如果元路径查找器知道如何处理指定的模块，它返回一个spec对象。如果它不能处理指定的模块，它返回 None。如果 sys.meta_path 处理到达其列表的末尾而不返回规范，则引发 ModuleNotFoundError。任何其他引发的异常都只是向上传播，中止导入过程。

元路径查找器的 find_spec() 方法用两个或三个参数调用。第一个是正在导入的模块的完全限定名称，例如 foo.bar.baz。第二个参数是用于模块搜索的路径条目。对于顶层模块，第二个参数是 None，但对于子模块或子包，第二个参数是父包的 __path__ 属性的值。如果不能访问适当的 __path__ 属性，则引发 ModuleNotFoundError。第三个参数是将成为稍后加载目标的现有模块对象。导入系统仅在重新加载期间传递目标模块。

对于单个导入请求，元路径可以被遍历多次。例如，假设没有涉及的模块已经被缓存，则导入 foo.bar.baz 将首先执行顶层导入，在每个元路径查找器（mpf）上调用 mpf.find_spec("foo", None, None)。在 foo 被导入之后，将通过遍历元路径第二次导入 foo.bar，称为 mpf.find_spec("foo.bar", foo.__path__, None)。一旦 foo.bar 被导入，最后的遍历将调用 mpf.find_spec("foo.bar.baz", foo.bar.__path__, None)。

一些元路径查找器仅支持顶级导入。当作为第二个参数传递 None 之外的任何东西时，这些进口商将总是返回 None。

Python的默认 sys.meta_path 有三个元路径查找器，一个知道如何导入内置模块，一个知道如何导入冻结模块，一个知道如何从 import path （即 path based finder）导入模块。

5.4.1. 装载机¶

模块加载器提供加载的关键功能：模块执行。导入机制使用单个参数调用 importlib.abc.Loader.exec_module() 方法，即要执行的模块对象。从 exec_module() 返回的任何值都将被忽略。

装载机必须满足以下要求：

• 如果模块是Python模块（而不是内置模块或动态加载的扩展），加载器应该在模块的全局名称空间（module.__dict__）中执行模块的代码。

• 如果加载器不能执行模块，它应该引发一个 ImportError，虽然在 exec_module() 期间引发的任何其他异常将被传播。

在许多情况下，finder和loader可以是同一个对象；在这种情况下，find_spec() 方法将返回一个规范，加载程序设置为 self。

模块加载器可以通过实现 create_module() 方法在加载期间选择创建模块对象。它接受一个参数，模块规范，并返回在加载期间要使用的新模块对象。 create_module() 不需要在模块对象上设置任何属性。如果方法返回 None，导入机制将创建新的模块本身。

5.4.2. 子模块¶

当使用任何机制（例如 importlib API，import 或 import-from 语句或内置 __import__()）加载子模块时，绑定将放置在父模块的命名空间中到子模块对象。例如，如果包 spam 具有子模块 foo，则在导入 spam.foo 之后，spam 将具有绑定到子模块的属性 foo。假设您有以下目录结构:

spam/
    __init__.py
    foo.py
    bar.py

而 spam/__init__.py 有以下几行:

from .foo import Foo
from .bar import Bar

然后执行以下命令，将名称绑定到 spam 模块中的 foo 和 bar:

>>> import spam
>>> spam.foo
<module 'spam.foo' from '/tmp/imports/spam/foo.py'>
>>> spam.bar
<module 'spam.bar' from '/tmp/imports/spam/bar.py'>

给定Python熟悉的名称绑定规则，这可能看起来令人惊讶，但它实际上是导入系统的一个基本特征。不变的控制是，如果你有 sys.modules['spam'] 和 sys.modules['spam.foo'] （如上述导入之后），后者必须显示为前者的 foo 属性。

5.4.3. 模块规格¶

导入机制在导入期间使用关于每个模块的各种信息，尤其是在加载之前。大多数信息对所有模块都是通用的。模块规范的目的是在每个模块的基础上封装这个导入相关的信息。

在导入期间使用规范允许状态在导入系统组件之间传送，例如，在创建模块spec的finder和执行它的loader之间。最重要的是，它允许导入机器执行加载的样板操作，而没有模块规范，加载器有责任。

有关模块规格可能包含的信息的更多细节，请参阅 ModuleSpec。

5.4.4. 导入相关的模块属性¶

导入机制在加载期间根据模块的规范在加载程序执行模块之前在每个模块对象上填充这些属性。

__name__¶

__name__ 属性必须设置为模块的完全限定名称。此名称用于唯一标识导入系统中的模块。

__loader__¶

__loader__ 属性必须设置为导入机制在加载模块时使用的加载器对象。这主要用于内省，但可用于其他特定于加载程序的功能，例如获取与加载程序关联的数据。

__package__¶

必须设置模块的 __package__ 属性。它的值必须是字符串，但它可以是与其 __name__ 相同的值。当模块是包时，其 __package__ 值应设置为其 __name__。当模块不是包时，__package__ 应设置为顶层模块的空字符串，或子模块的父字符串到父包的名称。有关详细信息，请参阅 PEP 366。

使用此属性而不是 __name__ 来计算主模块的显式相对导入，如 PEP 366 中定义。它预计与 __spec__.parent 具有相同的值。

在 3.6 版更改: __package__ 的值预期与 __spec__.parent 相同。

__spec__¶

__spec__ 属性必须设置为在导入模块时使用的模块规范。设置 __spec__ 适当地适用于 模块在解释器启动期间初始化。一个例外是 __main__，其中 __spec__ 是 在某些情况下设置为无。

当没有定义 __package__ 时，__spec__.parent 用作回退。

3.4 新版功能.

在 3.6 版更改: 当 __package__ 未定义时，__spec__.parent 用作后备。

__path__¶

如果模块是包（常规或命名空间），则必须设置模块对象的 __path__ 属性。该值必须是可迭代的，但如果 __path__ 没有其他重要性，则该值可以为空。如果 __path__ 不为空，则在迭代时必须生成字符串。关于 __path__ 的语义的更多细节给出 下面。

非包装模块不应该有 __path__ 属性。

__file__¶

__cached__¶

__file__ 是可选的。如果设置，此属性的值必须为字符串。如果导入系统没有语义（例如，从数据库加载的模块），则导入系统可以选择未设置 __file__。

如果设置 __file__，则也可以适当地设置 __cached__ 属性，该属性是到代码的任何编译版本（例如，字节编译的文件）的路径。该文件不需要存在来设置此属性；路径可以简单地指向编译文件将存在的位置（请参阅 PEP 3147）。

当 __file__ 未设置时，也可以设置 __cached__。然而，这种情况是相当不正常的。最终，装载机是使用 __file__ 和/或 __cached__ 的。因此，如果加载器可以从缓存的模块加载，但不能从文件加载，则该非典型场景可能是适当的。

5.4.5. 模块.__路径___¶

根据定义，如果模块具有 __path__ 属性，则它是一个包，而不管其值。

包的 __path__ 属性在其子包的导入期间使用。在进口机制内，其功能与 sys.path 大致相同，即提供在导入期间搜索模块的位置列表。然而，__path__ 通常比 sys.path 更受限制。

__path__ 必须是可迭代的字符串，但它可能为空。用于 sys.path 的相同规则也适用于封装的 __path__，并且当遍历封装的 __path__ 时参考 sys.path_hooks （如下所述）。

包的 __init__.py 文件可以设置或更改包的 __path__ 属性，这通常是在 PEP 420 之前实现命名空间包的方式。随着 PEP 420 的采用，命名空间包不再需要提供仅包含 __path__ 操作代码的 __init__.py 文件；导入机制自动为命名空间包设置 __path__。

5.4.6. 模块reprs¶

默认情况下，所有模块都有一个可用的repr，但是根据上面设置的属性，在模块的spec中，你可以更明确地控制模块对象的repr。

如果模块有一个规范（__spec__），导入机制将尝试从它生成一个repr。如果失败或没有spec，导入系统将使用模块上可用的任何信息来创建默认repr。它将尝试使用 module.__name__，module.__file__ 和 module.__loader__ 作为repr的输入，默认情况下缺少任何信息。

这里是使用的确切规则：

• 如果模块具有 __spec__ 属性，规范中的信息用于生成repr。参考“名称”，“加载器”，“原点”和“has_location”属性。

• 如果模块具有 __file__ 属性，则将其用作模块的repr的一部分。

• 如果模块没有 __file__，但有一个不是 None 的 __loader__，那么加载器的repr被用作模块的repr的一部分。

• 否则，只需在repr中使用模块的 __name__。

5.5.1. 路径条目查找器¶

path based finder 负责查找和加载位置以字符串 path entry 指定的Python模块和包。大多数路径条目在文件系统中命名位置，但它们不必局限于此。

作为元路径查找器，path based finder 实现先前描述的 find_spec() 协议，然而它暴露可用于定制如何从 import path 找到和加载模块的附加钩子。

path based finder，sys.path，sys.path_hooks 和 sys.path_importer_cache 使用三个变量。也使用包对象上的 __path__ 属性。这些提供了进口机制可以定制的额外方式。

sys.path 包含提供模块和包的搜索位置的字符串列表。它从 PYTHONPATH 环境变量和各种其他安装和实现特定的默认值初始化。 sys.path 中的条目可以命名文件系统上的目录，zip文件以及可能需要搜索模块（如URL或数据库查询）的其他“位置”（参见 site 模块）。只有字符串和字节应存在于 sys.path 上；所有其他数据类型将被忽略。字节条目的编码由各个 路径条目查找器 确定。

path based finder 是 meta path finder，因此导入机制通过调用基于路径的finder的 find_spec() 方法开始 import path 搜索，如前所述。当给出 find_spec() 的 path 参数时，它将是要遍历的字符串路径的列表 - 通常是该包内的导入的包的 __path__ 属性。如果 path 参数为 None，则表示使用顶级导入和 sys.path。

基于路径的查找器遍历搜索路径中的每个条目，并且对于每个条目，为路径条目寻找合适的 path entry finder （PathEntryFinder）。因为这可能是昂贵的操作（例如，对于该搜索可能存在 stat() 调用开销），所以基于路径的查找器维护到路径条目查找器的高速缓存映射路径条目。这个高速缓存在 sys.path_importer_cache 中维护（尽管名字，这个高速缓存实际上存储finder对象，而不是被限制为 importer 对象）。以这种方式，对特定 path entry 位置的 path entry finder 的昂贵搜索仅需要进行一次。用户代码可以从 sys.path_importer_cache 中自由删除高速缓存条目，迫使基于路径的查找器再次执行 [3] 的路径条目搜索。

如果路径条目不存在于高速缓存中，则基于路径的查找器迭代 sys.path_hooks 中的每个可调用者。此列表中的每个 路径入口钩子 都使用单个参数（要搜索的路径条目）进行调用。这个可调用可以返回可以处理路径条目的 path entry finder，或者它可以提高 ImportError。基于路径的查找器使用 ImportError 来用信号通知钩不能为该 path entry 找到 path entry finder。异常被忽略，import path 迭代继续。钩子应该期望一个字符串或字节对象；字节对象的编码是直到挂钩（例如，它可能是一个文件系统编码，UTF-8，或其他），如果挂钩不能解码参数，它应该提高 ImportError。

如果 sys.path_hooks 迭代以没有返回 path entry finder 结束，则基于路径的查找器的 find_spec() 方法将 None 存储在 sys.path_importer_cache 中（以指示对于该路径条目没有查找器），并返回 None，指示该 meta path finder 找不到模块。

如果 path entry finder is 由 sys.path_hooks 上的 path entry hook 可调用程序之一返回，则使用以下协议向查询器询问模块规格，然后在加载模块时使用该规范。

当前工作目录（由空字符串表示）与 sys.path 上的其他条目稍有不同。首先，如果发现当前工作目录不存在，则 sys.path_importer_cache 中不存储任何值。其次，为每个模块查找新的当前工作目录的值。第三，用于 sys.path_importer_cache 并由 importlib.machinery.PathFinder.find_spec() 返回的路径将是实际的当前工作目录，而不是空字符串。

5.5.2. 路径入口查找器协议¶

为了支持导入模块和初始化包以及为命名空间包提供部分，路径入口查找器必须实现 find_spec() 方法。

find_spec() 需要两个参数，即正在导入的模块的完全限定名称和（可选）目标模块。 find_spec() 返回模块的完全填充规范。此规范将始终具有“loader”设置（有一个例外）。

向进口机制指示规范表示命名空间 portion。路径入口查找器将规范上的“loader”设置为 None，将“submodule_search_locations”设置为包含该部分的列表。

5.7.1. __main __.__ spec__¶

根据 __main__ 如何初始化，__main__.__spec__ 被适当地设置或 None。

当Python使用 -m 选项启动时，__spec__ 设置为相应模块或包的模块规范。当 __main__ 模块作为执行目录，zip文件或其他 sys.path 条目的一部分加载时，还会填充 __spec__。

在 其余情况 中，__main__.__spec__ 设置为 None，因为用于填充 __main__ 的代码不直接对应于可导入模块：

• 交互式提示

• -c开关

• 从stdin运行

• 直接从源或字节码文件运行

注意，在最后一种情况下 __main__.__spec__ 总是 None，即使 文件可以在技术上直接作为模块导入。如果在 __main__ 中需要有效的模块元数据，请使用 -m 开关。

还要注意，即使当 __main__ 对应于可导入模块并且相应地设置 __main__.__spec__ 时，它们仍然被认为是 distinct 模块。这是因为由 if __name__ == "__main__": 检查保护的块仅在模块用于填充 __main__ 命名空间时执行，而不是在正常导入期间执行。