### 导航
- [索引](../genindex.xhtml "总目录")
- [模块](../py-modindex.xhtml "Python 模块索引") |
- [下一页](expressions.xhtml "6. 表达式") |
- [上一页](executionmodel.xhtml "4. 执行模型") |
- 
- [Python](https://www.python.org/) »
- zh\_CN 3.7.3 [文档](../index.xhtml) »
- [Python 语言参考](index.xhtml) »
- $('.inline-search').show(0); |
# 5. 导入系统
一个 [module](../glossary.xhtml#term-module) 内的 Python 代码通过 [importing](../glossary.xhtml#term-importing) 操作就能够访问另一个模块内的代码。 [`import`](simple_stmts.xhtml#import) 语句是发起调用导入机制的最常用方式，但不是唯一的方式。 [`importlib.import_module()`](../library/importlib.xhtml#importlib.import_module "importlib.import_module") 以及内置的 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 等函数也可以被用来发起调用导入机制。
[`import`](simple_stmts.xhtml#import) 语句结合了两个操作；它先搜索指定名称的模块，然后将搜索结果绑定到当前作用域中的名称。 `import` 语句的搜索操作定义为对 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 函数的调用并带有适当的参数。 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 的返回值会被用于执行 `import` 语句的名称绑定操作。 请参阅 `import` 语句了解名称绑定操作的更多细节。
对 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 的直接调用将仅执行模块搜索以及在找到时的模块创建操作。 不过也可能产生某些副作用，例如导入父包和更新各种缓存 (包括 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules"))，只有 [`import`](simple_stmts.xhtml#import) 语句会执行名称绑定操作。
当 [`import`](simple_stmts.xhtml#import) 语句被执行时，标准的内置 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 函数会被调用。 其他发起调用导入系统的机制 (例如 [`importlib.import_module()`](../library/importlib.xhtml#importlib.import_module "importlib.import_module")) 可能会选择绕过 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 并使用它们自己的解决方案来实现导入机制。
当一个模块首次被导入时，Python 会搜索该模块，如果找到就创建一个 module 对象 [1](#fnmo) 并初始化它。 如果指定名称的模块未找到，则会引发 [`ModuleNotFoundError`](../library/exceptions.xhtml#ModuleNotFoundError "ModuleNotFoundError")。 当发起调用导入机制时，Python 会实现多种策略来搜索指定名称的模块。 这些策略可以通过使用使用下文所描述的多种钩子来加以修改和扩展。
在 3.3 版更改: 导入系统已被更新以完全实现 [**PEP 302**](https://www.python.org/dev/peps/pep-0302) \[https://www.python.org/dev/peps/pep-0302\] 中的第二阶段要求。 不会再有任何隐式的导入机制 —— 整个导入系统都通过 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 暴露出来。 此外，对原生命名空间包的支持也已被实现 (参见 [**PEP 420**](https://www.python.org/dev/peps/pep-0420) \[https://www.python.org/dev/peps/pep-0420\])。
## 5.1. [`importlib`](../library/importlib.xhtml#module-importlib "importlib: The implementation of the import machinery.")
[`importlib`](../library/importlib.xhtml#module-importlib "importlib: The implementation of the import machinery.") 模块提供了一个丰富的 API 用来与导入系统进行交互。 例如 [`importlib.import_module()`](../library/importlib.xhtml#importlib.import_module "importlib.import_module") 提供了相比内置的 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 更推荐、更简单的 API 用来发起调用导入机制。 更多细节请参看 [`importlib`](../library/importlib.xhtml#module-importlib "importlib: The implementation of the import machinery.") 库文档。
## 5.2. 包
Python 只有一种模块对象类型，所有模块都属于该类型，无论模块是用 Python、C 还是别的语言实现。 为了帮助组织模块并提供名称层次结构，Python 还引入了 [包](../glossary.xhtml#term-package) 的概念。
你可以把包看成是文件系统中的目录，并把模块看成是目录中的文件，但请不要对这个类似做过于字面的理解，因为包和模块不是必须来自于文件系统。 为了方便理解本文档，我们将继续使用这种目录和文件的类比。 与文件系统一样，包通过层次结构进行组织，在包之内除了一般的模块，还可以有子包。
要注意的一个重点概念是所有包都是模块，但并非所有模块都是包。 或者换句话说，包只是一种特殊的模块。 特别地，任何具有 `__path__` 属性的模块都会被当作是包。
所有模块都有自己的名字。 子包名与其父包名以点号分隔，与 Python 的标准属性访问语法一致。 例如你可能看到一个名为 [`sys`](../library/sys.xhtml#module-sys "sys: Access system-specific parameters and functions.") 的模块，以及一个名为 [`email`](../library/email.xhtml#module-email "email: Package supporting the parsing, manipulating, and generating email messages.") 的包，这个包又有一个名为 [`email.mime`](../library/email.mime.xhtml#module-email.mime "email.mime: Build MIME messages.") 的子包和该子包中的名为 `email.mime.text` 的子包。
### 5.2.1. 正规包
Python 定义了两种类型的包，[正规包](../glossary.xhtml#term-regular-package) 和 [命名空间包](../glossary.xhtml#term-namespace-package)。 正规包是传统的包类型，它们在 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. 命名空间包
命名空间包是由多个 [部分](../glossary.xhtml#term-portion) 构成的，每个部分为父包增加一个子包。 各个部分可能处于文件系统的不同位置。 部分也可能处于 zip 文件中、网络上，或者 Python 在导入期间可以搜索的其他地方。 命名空间包并不一定会直接对应到文件系统中的对象；它们有可能是无实体表示的虚拟模块。
命名空间包的 `__path__` 属性不使用普通的列表。 而是使用定制的可迭代类型，如果其父包的路径 (或者最高层级包的 [`sys.path`](../library/sys.xhtml#sys.path "sys.path")) 发生改变，这种对象会在该包内的下一次导入尝试时自动执行新的对包部分的搜索。
命名空间包没有 `parent/__init__.py` 文件。 实际上，在导入搜索期间可能找到多个 `parent` 目录，每个都由不同的部分所提供。 因此 `parent/one` 的物理位置不一定与 `parent/two` 相邻。 在这种情况下，Python 将为顶级的 `parent` 包创建一个命名空间包，无论是它本身还是它的某个子包被导入。
另请参阅 [**PEP 420**](https://www.python.org/dev/peps/pep-0420) \[https://www.python.org/dev/peps/pep-0420\] 了解对命名空间包的规格描述。
## 5.3. 搜索
为了开始搜索，Python 需要被导入模块（或者包，对于当前讨论来说两者没有差别）的完整 [限定名称](../glossary.xhtml#term-qualified-name)。 此名称可以来自 [`import`](simple_stmts.xhtml#import) 语句所带的各种参数，或者来自传给 [`importlib.import_module()`](../library/importlib.xhtml#importlib.import_module "importlib.import_module") 或 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 函数的形参。
此名称会在导入搜索的各个阶段被使用，它也可以是指向一个子模块的带点号路径，例如 `foo.bar.baz`。 在这种情况下，Python 会先尝试导入 `foo`，然后是 `foo.bar`，最后是 `foo.bar.baz`。 如果这些导入中的任何一个失败，都会引发 [`ModuleNotFoundError`](../library/exceptions.xhtml#ModuleNotFoundError "ModuleNotFoundError")。
### 5.3.1. 模块缓存
在导入搜索期间首先会被检查的地方是 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules")。 这个映射起到缓存之前导入的所有模块的作用（包括其中间路径）。 因此如果之前导入过 `foo.bar.baz`，则 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 将包含 `foo`, `foo.bar` 和 `foo.bar.baz` 条目。 每个键的值就是相应的模块对象。
在导入期间，会在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 查找模块名称，如存在则其关联的值就是需要导入的模块，导入过程完成。 然而，如果值为 `None`，则会引发 [`ModuleNotFoundError`](../library/exceptions.xhtml#ModuleNotFoundError "ModuleNotFoundError")。 如果找不到指定模块名称，Python 将继续搜索该模块。
[`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 是可写的。删除键可能不会破坏关联的模块（因为其他模块可能会保留对它的引用），但它会使命名模块的缓存条目无效，导致 Python 在下次导入时重新搜索命名模块。键也可以赋值为 `None` ，强制下一次导入模块导致 [`ModuleNotFoundError`](../library/exceptions.xhtml#ModuleNotFoundError "ModuleNotFoundError") 。
但是要小心，因为如果你还保有对某个模块对象的引用，同时停用其在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中的缓存条目，然后又再次导入该名称的模块，则前后两个模块对象将 *不是* 同一个。 相反地，[`importlib.reload()`](../library/importlib.xhtml#importlib.reload "importlib.reload") 将重用 *同一个* 模块对象，并简单地通过重新运行模块的代码来重新初始化模块内容。
### 5.3.2. 查找器和加载器
如果指定名称的模块在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 找不到，则将发起调用 Python 的导入协议以查找和加载该模块。 此协议由两个概念性模块构成，即 [查找器](../glossary.xhtml#term-finder) 和 [加载器](../glossary.xhtml#term-loader)。 查找器的任务是确定是否能使用其所知的策略找到该名称的模块。 同时实现这两种接口的对象称为 [导入器](../glossary.xhtml#term-importer) —— 它们在确定能加载所需的模块时会返回其自身。
Python 包含了多个默认查找器和导入器。 第一个知道如何定位内置模块，第二个知道如何定位冻结模块。 第三个默认查找器会在 [import path](../glossary.xhtml#term-import-path) 中搜索模块。 [import path](../glossary.xhtml#term-import-path) 是一个由文件系统路径或 zip 文件组成的位置列表。 它还可以扩展为搜索任意可定位资源，例如由 URL 指定的资源。
导入机制是可扩展的，因此可以加入新的查找器以扩展模块搜索的范围和作用域。
查找器并不真正加载模块。 如果它们能找到指定名称的模块，会返回一个 *模块规格说明*，这是对模块导入相关信息的封装，供后续导入机制用于在加载模块时使用。
以下各节描述了有关查找器和加载器协议的更多细节，包括你应该如何创建并注册新的此类对象来扩展导入机制。
在 3.4 版更改: 在之前的 Python 版本中，查找器会直接返回 [加载器](../glossary.xhtml#term-loader)，现在它们则返回模块规格说明，其中 *包含* 加载器。 加载器仍然在导入期间被使用，但负担的任务有所减少。
### 5.3.3. 导入钩子
导入机制被设计为可扩展；其中的基本机制是 *导入钩子*。 导入钩子有两种类型: *元钩子* 和 *导入路径钩子*。
元钩子在导入过程开始时被调用，此时任何其他导入过程尚未发生，但 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 缓存查找除外。 这允许元钩子重载 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 过程、冻结模块甚至内置模块。 元钩子的注册是通过向 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 添加新的查找器对象，具体如下所述。
导入路径钩子是作为 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") (或 `package.__path__`) 过程的一部分，在遇到它们所关联的路径项的时候被调用。 导入路径钩子的注册是通过向 [`sys.path_hooks`](../library/sys.xhtml#sys.path_hooks "sys.path_hooks") 添加新的可调用对象，具体如下所述。
### 5.3.4. 元路径
当指定名称的模块在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中找不到时，Python 会接着搜索 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path")，其中包含元路径查找器对象列表。 这些查找器按顺序被查询以确定它们是否知道如何处理该名称的模块。 元路径查找器必须实现名为 [`find_spec()`](../library/importlib.xhtml#importlib.abc.MetaPathFinder.find_spec "importlib.abc.MetaPathFinder.find_spec") 的方法，该方法接受三个参数：名称、导入路径和目标模块（可选）。 元路径查找器可使用任何策略来确定它是否能处理指定名称的模块。
如果元路径查找器知道如何处理指定名称的模块，它将返回一个说明对象。 如果它不能处理该名称的模块，则会返回 `None`。 如果 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 处理过程到达列表末尾仍未返回说明对象，则将引发 [`ModuleNotFoundError`](../library/exceptions.xhtml#ModuleNotFoundError "ModuleNotFoundError")。 任何其他被引发异常将直接向上传播，并放弃导入过程。
元路径查找器的 [`find_spec()`](../library/importlib.xhtml#importlib.abc.MetaPathFinder.find_spec "importlib.abc.MetaPathFinder.find_spec") 方法调用带有两到三个参数。 第一个是被导入模块的完整限定名称，例如 `foo.bar.baz`。 第二个参数是供模块搜索使用的路径条目。 对于最高层级模块，第二个参数为 `None`，但对于子模块或子包，第二个参数为父包 `__path__` 属性的值。 如果相应的 `__path__` 属性无法访问，将引发 [`ModuleNotFoundError`](../library/exceptions.xhtml#ModuleNotFoundError "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`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 具有三种元路径查找器，一种知道如何导入内置模块，一种知道如何导入冻结模块，还有一种知道如何导入来自 [import path](../glossary.xhtml#term-import-path) 的模块 (即 [path based finder](../glossary.xhtml#term-path-based-finder))。
在 3.4 版更改: 元路径查找器的 [`find_spec()`](../library/importlib.xhtml#importlib.abc.MetaPathFinder.find_spec "importlib.abc.MetaPathFinder.find_spec") 方法替代了 [`find_module()`](../library/importlib.xhtml#importlib.abc.MetaPathFinder.find_module "importlib.abc.MetaPathFinder.find_module")，后者现已弃用，它将继续可用但不会再做改变，导入机制仅会在查找器未实现 `find_spec()` 时尝试使用它。
## 5.4. 加载
当一个模块说明被找到时，导入机制将在加载该模块时使用它（及其所包含的加载器）。 下面是导入的加载部分所发生过程的简要说明:
```
module = None
if spec.loader is not None and hasattr(spec.loader, 'create_module'):
# It is assumed 'exec_module' will also be defined on the loader.
module = spec.loader.create_module(spec)
if module is None:
module = ModuleType(spec.name)
# The import-related module attributes get set here:
_init_module_attrs(spec, module)
if spec.loader is None:
if spec.submodule_search_locations is not None:
# namespace package
sys.modules[spec.name] = module
else:
# unsupported
raise ImportError
elif not hasattr(spec.loader, 'exec_module'):
module = spec.loader.load_module(spec.name)
# Set __loader__ and __package__ if missing.
else:
sys.modules[spec.name] = module
try:
spec.loader.exec_module(module)
except BaseException:
try:
del sys.modules[spec.name]
except KeyError:
pass
raise
return sys.modules[spec.name]
```
请注意以下细节:
> - 如果在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中存在指定名称的模块对象，导入操作会已经将其返回。
> - 在加载器执行模块代码之前，该模块将存在于 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中。 这一点很关键，因为该模块代码可能（直接或间接地）导入其自身；预先将其添加到 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 可防止在最坏情况下的无限递归和最好情况下的多次加载。
> - 如果加载失败，则该模块 -- 只限加载失败的模块 -- 将从 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中移除。 任何已存在于 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 缓存的模块，以及任何作为附带影响被成功加载的模块仍会保留在缓存中。 这与重新加载不同，后者会把即使加载失败的模块也保留在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中。
> - 在模块创建完成但还未执行之前，导入机制会设置导入相关模块属性（在上面的示例伪代码中为 “\_init\_module\_attrs”），详情参见 [后续部分](#import-mod-attrs)。
> - 模块执行是加载的关键时刻，在此期间将填充模块的命名空间。 执行会完全委托给加载器，由加载器决定要填充的内容和方式。
> - 在加载过程中创建并传递给 exec\_module() 的模块并不一定就是在导入结束时返回的模块 [2](#fnlo)。
在 3.4 版更改: 导入系统已经接管了加载器建立样板的责任。 这些在以前是由 [`importlib.abc.Loader.load_module()`](../library/importlib.xhtml#importlib.abc.Loader.load_module "importlib.abc.Loader.load_module") 方法来执行的。
### 5.4.1. 加载器
模块加载器提供关键的加载功能：模块执行。 导入机制调用 [`importlib.abc.Loader.exec_module()`](../library/importlib.xhtml#importlib.abc.Loader.exec_module "importlib.abc.Loader.exec_module") 方法并传入一个参数来执行模块对象。 从 [`exec_module()`](../library/importlib.xhtml#importlib.abc.Loader.exec_module "importlib.abc.Loader.exec_module") 返回的任何值都将被忽略。
加载器必须满足下列要求:
> - 如果模块是一个 Python 模块（而非内置模块或动态加载的扩展），加载器应该在模块的全局命名空间 (`module.__dict__`) 中执行模块的代码。
> - 如果加载器无法执行指定模块，它应该引发 [`ImportError`](../library/exceptions.xhtml#ImportError "ImportError")，不过在 [`exec_module()`](../library/importlib.xhtml#importlib.abc.Loader.exec_module "importlib.abc.Loader.exec_module") 期间引发的任何其他异常也会被传播。
在许多情况下，查找器和加载器可以是同一对象；在此情况下 [`find_spec()`](../library/importlib.xhtml#importlib.abc.MetaPathFinder.find_spec "importlib.abc.MetaPathFinder.find_spec") 方法将返回一个规格说明，其中加载器会被设为 `self`。
模块加载器可以选择通过实现 [`create_module()`](../library/importlib.xhtml#importlib.abc.Loader.create_module "importlib.abc.Loader.create_module") 方法在加载期间创建模块对象。 它接受一个参数，即模块规格说明，并返回新的模块对象供加载期间使用。 `create_module()` 不需要在模块对象上设置任何属性。 如果模块返回 `None`，导入机制将自行创建新模块。
3\.4 新版功能: 加载器的 [`create_module()`](../library/importlib.xhtml#importlib.abc.Loader.create_module "importlib.abc.Loader.create_module") 方法。
在 3.4 版更改: [`load_module()`](../library/importlib.xhtml#importlib.abc.Loader.load_module "importlib.abc.Loader.load_module") 方法被 [`exec_module()`](../library/importlib.xhtml#importlib.abc.Loader.exec_module "importlib.abc.Loader.exec_module") 所替代，导入机制会对加载的所有样板责任作出假定。
为了与现有的加载器兼容，导入机制会使用导入器的 `load_module()` 方法，如果它存在且导入器也未实现 `exec_module()`。 但是，`load_module()` 现已弃用，加载器应该转而实现 `exec_module()`。
除了执行模块之外，`load_module()` 方法必须实现上文描述的所有样板加载功能。 所有相同的限制仍然适用，并带有一些附加规定:
> - 如果 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中存在指定名称的模块对象，加载器必须使用已存在的模块。 （否则 [`importlib.reload()`](../library/importlib.xhtml#importlib.reload "importlib.reload") 将无法正确工作。） 如果该名称模块不存在于 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中，加载器必须创建一个新的模块对象并将其加入 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules")。
> - 在加载器执行模块代码之前，模块 *必须* 存在于 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 之中，以防止无限递归或多次加载。
> - 如果加载失败，加载器必须移除任何它已加入到 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中的模块，但它必须 **仅限** 移除加载失败的模块，且所移除的模块应为加载器自身显式加载的。
在 3.5 版更改: 当 `exec_module()` 已定义但 `create_module()` 未定义时将引发 [`DeprecationWarning`](../library/exceptions.xhtml#DeprecationWarning "DeprecationWarning")。
在 3.6 版更改: 当 `exec_module()` 已定义但 `create_module()` 未定义时将引发 [`ImportError`](../library/exceptions.xhtml#ImportError "ImportError")。
### 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__` 属性对外公开。 有关模块规格的详细内容请参阅 [`ModuleSpec`](../library/importlib.xhtml#importlib.machinery.ModuleSpec "importlib.machinery.ModuleSpec")。
3\.4 新版功能.
### 5.4.4. 导入相关的模块属性
导入机制会在加载期间会根据模块的规格说明填充每个模块对象的这些属性，并在加载器执行模块之前完成。
`__name__``__name__` 属性必须被设为模块的完整限定名称。 此名称被用来在导入系统中唯一地标识模块。
`__loader__``__loader__` 属性必须被设为导入系统在加载模块时使用的加载器对象。 这主要是用于内省，但也可用于额外的加载器专用功能，例如获取关联到加载器的数据。
`__package__`模块的 `__package__` 属性必须设定。 其取值必须为一个字符串，但可以与 `__name__` 取相同的值。 当模块是包时，其 `__package__` 值应该设为其 `__name__` 值。 当模块不是包时，对于最高层级模块 `__package__` 应该设为空字符串，对于子模块则应该设为其父包名。 更多详情可参阅 [**PEP 366**](https://www.python.org/dev/peps/pep-0366) \[https://www.python.org/dev/peps/pep-0366\]。
该属性取代 `__name__` 被用来为主模块计算显式相对导入，相关定义见 [**PEP 366**](https://www.python.org/dev/peps/pep-0366) \[https://www.python.org/dev/peps/pep-0366\]。 预期它与 `__spec__.parent` 具有相同的值。
在 3.6 版更改: `__package__` 预期与 `__spec__.parent` 具有相同的值。
`__spec__``__spec__` 属性必须设为在导入模块时要使用的模块规格说明。 对 `__spec__` 的正确设定将同时作用于 [解释器启动期间初始化的模块](toplevel_components.xhtml#programs)。 唯一的例外是 `__main__`，其中的 `__spec__` 会 [在某些情况下设为 None](#main-spec).
当 `__package__` 未定义时， `__spec__.parent` 会被用作回退项。
3\.4 新版功能.
在 3.6 版更改: 当 `__package__` 未定义时，`__spec__.parent` 会被用作回退项。
`__path__`如果模块为包（不论是正规包还是命名空间包），则必须设置模块对象的 `__path__` 属性。 属性值必须为可迭代对象，但如果 `__path__` 没有进一步的用处则可以为空。 如果 `__path__` 不为空，则在迭代时它应该产生字符串。 有关 `__path__` 语义的更多细节将在 [下文](#package-path-rules) 中给出。
不是包的模块不应该具有 `__path__` 属性。
`__file__``__cached__``__file__` 是可选项。 如果设置，此属性的值必须为字符串。 导入系统可以选择在其没有语法意义时不设置 `__file__` (例如从数据库加载的模块)。
如果设置了 `__file__`，则也可以再设置 `__cached__` 属性，后者取值为编译版本代码（例如字节码文件）所在的路径。 设置此属性不要求文件已存在；该路径可以简单地指向应该存放编译文件的位置 (参见 [**PEP 3147**](https://www.python.org/dev/peps/pep-3147) \[https://www.python.org/dev/peps/pep-3147\])。
当未设置 `__file__` 时也可以设置 `__cached__`。 但是，那样的场景很不典型。 最终，加载器会使用 `__file__` 和/或 `__cached__`。 因此如果一个加载器可以从缓存加载模块但是不能从文件加载，那种非典型场景就是适当的。
### 5.4.5. module.\_\_path\_\_
根据定义，如果一个模块具有 `__path__` 属性，它就是包。
包的 `__path__` 属性会在导入其子包期间被使用。 在导入机制内部，它的功能与 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 基本相同，即在导入期间提供一个模块搜索位置列表。 但是，`__path__` 通常会比 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 受到更多限制。
`__path__` 必须是由字符串组成的可迭代对象，但它也可以为空。 作用于 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 的规则同样适用于包的 `__path__`，并且 [`sys.path_hooks`](../library/sys.xhtml#sys.path_hooks "sys.path_hooks") (见下文) 会在遍历包的 `__path__` 时被查询。
包的 `__init__.py` 文件可以设置或更改包的 `__path__` 属性，而且这是在 [**PEP 420**](https://www.python.org/dev/peps/pep-0420) \[https://www.python.org/dev/peps/pep-0420\] 之前实现命名空间包的典型方式。 随着 [**PEP 420**](https://www.python.org/dev/peps/pep-0420) \[https://www.python.org/dev/peps/pep-0420\] 的引入，命名空间包不再需要提供仅包含 `__path__` 操控代码的 `__init__.py` 文件；导入机制会自动为命名空间包正确地设置 `__path__`。
### 5.4.6. 模块的 repr
默认情况下，全部模块都具有一个可用的 repr，但是你可以依据上述的属性设置，在模块的规格说明中更为显式地控制模块对象的 repr。
如果模块具有 spec (`__spec__`)，导入机制将尝试用它来生成一个 repr。 如果生成失败或找不到 spec，导入系统将使用模块中的各种可用信息来制作一个默认 repr。 它将尝试使用 `module.__name__`, `module.__file__` 以及 `module.__loader__` 作为 repr 的输入，并将任何丢失的信息赋为默认值。
以下是所使用的确切规则:
> - 如果模块具有 `__spec__` 属性，其中的规格信息会被用来生成 repr。 被查询的属性有 "name", "loader", "origin" 和 "has\_location" 等等。
> - 如果模块具有 `__file__` 属性，这会被用作模块 repr 的一部分。
> - 如果模块没有 `__file__` 但是有 `__loader__` 且取值不为 `None`，则加载器的 repr 会被用作模块 repr 的一部分。
> - 对于其他情况，仅在 repr 中使用模块的 `__name__`。
在 3.4 版更改: [`loader.module_repr()`](../library/importlib.xhtml#importlib.abc.Loader.module_repr "importlib.abc.Loader.module_repr") 已弃用，导入机制现在使用模块规格说明来生成模块 repr。
为了向后兼容 Python 3.3，如果加载器定义了 [`module_repr()`](../library/importlib.xhtml#importlib.abc.Loader.module_repr "importlib.abc.Loader.module_repr") 方法，则会在尝试上述两种方式之前先调用该方法来生成模块 repr。 但请注意此方法已弃用。
### 5.4.7. 已缓存字节码的失效
在 Python 从 `.pyc` 文件加载已缓存字节码之前，它会检查缓存是否由最新的 `.py` 源文件生成。 默认情况下，Python 通过在所写入缓存文件中保存源文件的最近修改时间戳和大小来实现这一点。 在运行时，导入系统会通过比对缓存文件中保存的元数据和源文件的元数据确定该缓存的有效性。
Python 也支持“基于哈希的”缓存文件，即保存源文件内容的哈希值而不是其元数据。 存在两种基于哈希的 `.pyc` 文件：检查型和非检查型。 对于检查型基于哈希的 `.pyc` 文件，Python 会通过求哈希源文件并将结果哈希值与缓存文件中的哈希值比对来确定缓存有效性。 如果检查型基于哈希的缓存文件被确定为失效，Python 会重新生成并写入一个新的检查型基于哈希的缓存文件。 对于非检查型 `.pyc` 文件，只要其存在 Python 就会直接认定缓存文件有效。 确定基于哈希的 `.pyc` 文件有效性的行为可通过 [`--check-hash-based-pycs`](../using/cmdline.xhtml#cmdoption-check-hash-based-pycs) 旗标来重载。
在 3.7 版更改: 增加了基于哈希的 `.pyc` 文件。在此之前，Python 只支持基于时间戳来确定字节码缓存的有效性。
## 5.5. 基于路径的查找器
在之前已经提及，Python 带有几种默认的元路径查找器。 其中之一是 [path based finder](../glossary.xhtml#term-path-based-finder) ([`PathFinder`](../library/importlib.xhtml#importlib.machinery.PathFinder "importlib.machinery.PathFinder"))，它会搜索包含一个 [路径条目](../glossary.xhtml#term-path-entry) 列表的 [import path](../glossary.xhtml#term-import-path)。 每个路径条目指定一个用于搜索模块的位置。
基于路径的查找器自身并不知道如何进行导入。 它只是遍历单独的路径条目，将它们各自关联到某个知道如何处理特定类型路径的路径条目查找器。
默认的路径条目查找器集合实现了在文件系统中查找模块的所有语义，可处理多种特殊文件类型例如 Python 源码 (`.py` 文件)，Python 字节码 (`.pyc` 文件) 以及共享库 (例如 `.so` 文件)。 在标准库中 [`zipimport`](../library/zipimport.xhtml#module-zipimport "zipimport: support for importing Python modules from ZIP archives.") 模块的支持下，默认路径条目查找器还能处理所有来自 zip 文件的上述文件类型。
路径条目不必仅限于文件系统位置。 它们可以指向 URL、数据库查询或可以用字符串指定的任何其他位置。
基于路径的查找器还提供了额外的钩子和协议以便能扩展和定制可搜索路径条目的类型。 例如，如果你想要支持网络 URL 形式的路径条目，你可以编写一个实现 HTTP 语义在网络上查找模块的钩子。 这个钩子（可调用对象）应当返回一个支持下述协议的 [path entry finder](../glossary.xhtml#term-path-entry-finder)，以被用来获取一个专门针对来自网络的模块的加载器。
预先的警告：本节和上节都使用了 *查找器* 这一术语，并通过 [meta path finder](../glossary.xhtml#term-meta-path-finder) 和 [path entry finder](../glossary.xhtml#term-path-entry-finder) 两个术语来明确区分它们。 这两种类型的查找器非常相似，支持相似的协议，且在导入过程中以相似的方式运作，但关键的一点是要记住它们是有微妙差异的。 特别地，元路径查找器作用于导入过程的开始，主要是启动 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 遍历。
相比之下，路径条目查找器在某种意义上说是基于路径的查找器的实现细节，实际上，如果需要从 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 移除基于路径的查找器，并不会有任何路径条目查找器被发起调用。
### 5.5.1. 路径条目查找器
[path based finder](../glossary.xhtml#term-path-based-finder) 会负责查找和加载通过 [path entry](../glossary.xhtml#term-path-entry) 字符串来指定位置的 Python 模块和包。 多数路径条目所指定的是文件系统中的位置，但它们并不必受限于此。
作为一种元路径查找器，[path based finder](../glossary.xhtml#term-path-based-finder) 实现了上文描述的 [`find_spec()`](../library/importlib.xhtml#importlib.abc.MetaPathFinder.find_spec "importlib.abc.MetaPathFinder.find_spec") 协议，但是它还对外公开了一些附加钩子，可被用来定制模块如何从 [import path](../glossary.xhtml#term-import-path) 查找和加载。
有三个变量由 [path based finder](../glossary.xhtml#term-path-based-finder), [`sys.path`](../library/sys.xhtml#sys.path "sys.path"), [`sys.path_hooks`](../library/sys.xhtml#sys.path_hooks "sys.path_hooks") 和 [`sys.path_importer_cache`](../library/sys.xhtml#sys.path_importer_cache "sys.path_importer_cache") 所使用。 包对象的 `__path__` 属性也会被使用。 它们提供了可用于定制导入机制的额外方式。
[`sys.path`](../library/sys.xhtml#sys.path "sys.path") 包含一个提供模块和包搜索位置的字符串列表。 它初始化自 `PYTHONPATH` 环境变量以及多种其他特定安装和实现的默认设置。 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 条目可指定的名称有文件系统中的目录、zip 文件和其他可用于搜索模块的潜在“位置”（参见 [`site`](../library/site.xhtml#module-site "site: Module responsible for site-specific configuration.") 模块），例如 URL 或数据库查询等。 在 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 中只能出现字符串和字节串；所有其他数据类型都会被忽略。 字节串条目使用的编码由单独的 [路径条目查找器](../glossary.xhtml#term-path-entry-finder) 来确定。
[path based finder](../glossary.xhtml#term-path-based-finder) 是一种 [meta path finder](../glossary.xhtml#term-meta-path-finder)，因此导入机制会通过调用上文描述的基于路径的查找器的 [`find_spec()`](../library/importlib.xhtml#importlib.machinery.PathFinder.find_spec "importlib.machinery.PathFinder.find_spec") 方法来启动 [import path](../glossary.xhtml#term-import-path) 搜索。 当要向 [`find_spec()`](../library/importlib.xhtml#importlib.machinery.PathFinder.find_spec "importlib.machinery.PathFinder.find_spec") 传入 `path` 参数时，它将是一个可遍历的字符串列表 —— 通常为用来在其内部进行导入的包的 `__path__` 属性。 如果 `path` 参数为 `None`，这表示最高层级的导入，将会使用 [`sys.path`](../library/sys.xhtml#sys.path "sys.path")。
基于路径的查找器会迭代搜索路径中的每个条目，并且每次都查找与路径条目对应的 [path entry finder](../glossary.xhtml#term-path-entry-finder) ([`PathEntryFinder`](../library/importlib.xhtml#importlib.abc.PathEntryFinder "importlib.abc.PathEntryFinder"))。 因为这种操作可能很耗费资源（例如搜索会有 stat() 调用的开销），基于路径的查找器会维持一个缓存来将路径条目映射到路径条目查找器。 这个缓存放于 [`sys.path_importer_cache`](../library/sys.xhtml#sys.path_importer_cache "sys.path_importer_cache") (尽管如此命名，但这个缓存实际存放的是查找器对象而非仅限于 [importer](../glossary.xhtml#term-importer) 对象)。 通过这种方式，对特定 [path entry](../glossary.xhtml#term-path-entry) 位置的 [path entry finder](../glossary.xhtml#term-path-entry-finder) 的高耗费搜索只需进行一次。 用户代码可以自由地从 [`sys.path_importer_cache`](../library/sys.xhtml#sys.path_importer_cache "sys.path_importer_cache") 移除缓存条目，以强制基于路径的查找器再次执行路径条目搜索 [3](#fnpic)。
如果路径条目不存在于缓存中，基于路径的查找器会迭代 [`sys.path_hooks`](../library/sys.xhtml#sys.path_hooks "sys.path_hooks") 中的每个可调用对象。 对此列表中的每个 [路径条目钩子](../glossary.xhtml#term-path-entry-hook) 的调用会带有一个参数，即要搜索的路径条目。 每个可调用对象或是返回可处理路径条目的 [path entry finder](../glossary.xhtml#term-path-entry-finder)，或是引发 [`ImportError`](../library/exceptions.xhtml#ImportError "ImportError")。 基于路径的查找器使用 [`ImportError`](../library/exceptions.xhtml#ImportError "ImportError") 来表示钩子无法找到与 [path entry](../glossary.xhtml#term-path-entry) 相对应的 [path entry finder](../glossary.xhtml#term-path-entry-finder)。 该异常会被忽略并继续进行 [import path](../glossary.xhtml#term-import-path) 的迭代。 每个钩子应该期待接收一个字符串或字节串对象；字节串对象的编码由钩子决定（例如可以是文件系统使用的编码 UTF-8 或其它编码），如果钩子无法解码参数，它应该引发 [`ImportError`](../library/exceptions.xhtml#ImportError "ImportError")。
如果 [`sys.path_hooks`](../library/sys.xhtml#sys.path_hooks "sys.path_hooks") 迭代结束时没有返回 [path entry finder](../glossary.xhtml#term-path-entry-finder)，则基于路径的查找器 [`find_spec()`](../library/importlib.xhtml#importlib.machinery.PathFinder.find_spec "importlib.machinery.PathFinder.find_spec") 方法将在 [`sys.path_importer_cache`](../library/sys.xhtml#sys.path_importer_cache "sys.path_importer_cache") 中存入 `None` (表示此路径条目没有对应的查找器) 并返回 `None`，表示此 [meta path finder](../glossary.xhtml#term-meta-path-finder) 无法找到该模块。
如果 [`sys.path_hooks`](../library/sys.xhtml#sys.path_hooks "sys.path_hooks") 中的某个 [path entry hook](../glossary.xhtml#term-path-entry-hook) 可调用对象的返回值 *是* 一个 [path entry finder](../glossary.xhtml#term-path-entry-finder)，则以下协议会被用来向查找器请求一个模块的规格说明，并在加载该模块时被使用。
当前工作目录 -- 由一个空字符串表示 -- 的处理方式与 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 中的其他条目略有不同。 首先，如果发现当前工作目录不存在，则 [`sys.path_importer_cache`](../library/sys.xhtml#sys.path_importer_cache "sys.path_importer_cache") 中不会存放任何值。 其次，每个模块查找会对当前工作目录的值进行全新查找。 第三，由 [`sys.path_importer_cache`](../library/sys.xhtml#sys.path_importer_cache "sys.path_importer_cache") 所使用并由 [`importlib.machinery.PathFinder.find_spec()`](../library/importlib.xhtml#importlib.machinery.PathFinder.find_spec "importlib.machinery.PathFinder.find_spec") 所返回的路径将是实际的当前工作目录而非空字符串。
### 5.5.2. 路径条目查找器协议
为了支持模块和已初始化包的导入，也为了给命名空间包提供组成部分，路径条目查找器必须实现 [`find_spec()`](../library/importlib.xhtml#importlib.abc.PathEntryFinder.find_spec "importlib.abc.PathEntryFinder.find_spec") 方法。
[`find_spec()`](../library/importlib.xhtml#importlib.abc.PathEntryFinder.find_spec "importlib.abc.PathEntryFinder.find_spec") 接受两个参数，即要导入模块的完整限定名称，以及（可选的）目标模块。 `find_spec()` 返回模块的完全填充好的规格说明。 这个规格说明总是包含“加载器”集合（但有一个例外）。
为了向导入机制提示该规格说明代表一个命名空间的 [portion](../glossary.xhtml#term-portion)。 路径条目查找器会将规格说明中的 "loader" 设为 `None` 并将 "submodule\_search\_locations" 设为一个包含该部分的列表。
在 3.4 版更改: [`find_spec()`](../library/importlib.xhtml#importlib.abc.PathEntryFinder.find_spec "importlib.abc.PathEntryFinder.find_spec") 替代了 [`find_loader()`](../library/importlib.xhtml#importlib.abc.PathEntryFinder.find_loader "importlib.abc.PathEntryFinder.find_loader") 和 [`find_module()`](../library/importlib.xhtml#importlib.abc.PathEntryFinder.find_module "importlib.abc.PathEntryFinder.find_module")，后两者现在都已弃用，但会在 `find_spec()` 未定义时被使用。
较旧的路径条目查找器可能会实现这两个已弃用的方法中的一个而没有实现 `find_spec()`。 为保持向后兼容，这两个方法仍会被接受。 但是，如果在路径条目查找器上实现了 `find_spec()`，这两个遗留方法就会被忽略。
[`find_loader()`](../library/importlib.xhtml#importlib.abc.PathEntryFinder.find_loader "importlib.abc.PathEntryFinder.find_loader") 接受一个参数，即被导入模块的完整限定名称。 `find_loader()` 会返回一个二元组，其中第一项为加载器，第二项为一个命名空间 [portion](../glossary.xhtml#term-portion)。 当第一项（即加载器）为 `None` 时，这意味着路径条目查找器虽然没有指定名称模块的加载器，但它知道该路径条目为指定名称模块提供了一个命名空间部分。 这几乎总是表明一种情况，即 Python 被要求导入一个并不以文件系统中的实体形式存在的命名空间包。 当一个路径条目查找器返回的加载器为 `None` 时，该二元组返回值的第二项必须为一个序列，不过它也可以为空。
如果 `find_loader()` 所返回加载器的值不为 `None`，则该部分会被忽略，而该加载器会自基于路径的查找器返回，终止对路径条目的搜索。
为了向后兼容其他导入协议的实现，许多路径条目查找器也同样支持元路径查找器所支持的传统 `find_module()` 方法。 但是路径条目查找器 `find_module()` 方法的调用绝不会带有 `path` 参数（它们被期望记录来自对路径钩子初始调用的恰当路径信息）。
路径条目查找器的 `find_module()` 方法已弃用，因为它不允许路径条目查找器为命名空间包提供部分。 如果 `find_loader()` 和 `find_module()` 同时存在于一个路径条目查找器中，导入系统将总是调用 `find_loader()` 而不选择 `find_module()`。
## 5.6. 替换标准导入系统
替换整个导入系统的最可靠机制是移除 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 的默认内容，,将其完全替换为自定义的元路径钩子。
一个可行的方式是仅改变导入语句的行为而不影响访问导入系统的其他 API，那么替换内置的 [`__import__()`](../library/functions.xhtml#__import__ "__import__") 函数可能就够了。 这种技巧也可以在模块层级上运用，即只在某个模块内部改变导入语句的行为。
想要选择性地预先防止在元路径上从一个钩子导入某些模块（而不是完全禁用标准导入系统），直接从 [`find_spec()`](../library/importlib.xhtml#importlib.abc.MetaPathFinder.find_spec "importlib.abc.MetaPathFinder.find_spec") 引发 [`ModuleNotFoundError`](../library/exceptions.xhtml#ModuleNotFoundError "ModuleNotFoundError") 而非返回 `None` 就够了。 返回后者表示元路径搜索应当继续，而引发异常则会立即终止搜索。
## 5.7. Package Relative Imports
Relative imports use leading dots. A single leading dot indicates a relative import, starting with the current package. Two or more leading dots indicate a relative import to the parent(s) of the current package, one level per dot after the first. For example, given the following package layout:
```
package/
__init__.py
subpackage1/
__init__.py
moduleX.py
moduleY.py
subpackage2/
__init__.py
moduleZ.py
moduleA.py
```
In either `subpackage1/moduleX.py` or `subpackage1/__init__.py`, the following are valid relative imports:
```
from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo
```
Absolute imports may use either the `import <>` or `from <> import <>`syntax, but relative imports may only use the second form; the reason for this is that:
```
import XXX.YYY.ZZZ
```
should expose `XXX.YYY.ZZZ` as a usable expression, but .moduleY is not a valid expression.
## 5.8. 有关 \_\_main\_\_ 的特殊事项
对于 Python 的导入系统来说 [`__main__`](../library/__main__.xhtml#module-__main__ "__main__: The environment where the top-level script is run.") 模块是一个特殊情况。 正如在 [另一节](toplevel_components.xhtml#programs) 中所述，`__main__` 模块是在解释器启动时直接初始化的，与 [`sys`](../library/sys.xhtml#module-sys "sys: Access system-specific parameters and functions.") 和 [`builtins`](../library/builtins.xhtml#module-builtins "builtins: The module that provides the built-in namespace.") 很类似。 但是，与那两者不同，它并不被严格归类为内置模块。 这是因为 `__main__` 被初始化的方式依赖于发起调用解释器所附带的旗标和其他选项。
### 5.8.1. \_\_main\_\_.\_\_spec\_\_
根据 [`__main__`](../library/__main__.xhtml#module-__main__ "__main__: The environment where the top-level script is run.") 被初始化的方式，`__main__.__spec__` 会被设置相应值或是 `None`。
当 Python 附加 [`-m`](../using/cmdline.xhtml#cmdoption-m) 选项启动时，`__spec__` 会被设为相应模块或包的模块规格说明。 `__spec__` 也会在 `__main__` 模块作为执行某个目录，zip 文件或其它 [`sys.path`](../library/sys.xhtml#sys.path "sys.path") 条目的一部分加载时被填充。
在 [其余的情况](../using/cmdline.xhtml#using-on-interface-options) 下 `__main__.__spec__` 会被设为 `None`，因为用于填充 [`__main__`](../library/__main__.xhtml#module-__main__ "__main__: The environment where the top-level script is run.") 的代码不直接与可导入的模块相对应:
- 交互型提示
- [`-c`](../using/cmdline.xhtml#cmdoption-c) 选项
- 从 stdin 运行
- 直接从源码或字节码文件运行
请注意在最后一种情况中 `__main__.__spec__` 总是为 `None`，*即使* 文件从技术上说可以作为一个模块被导入。 如果想要让 [`__main__`](../library/__main__.xhtml#module-__main__ "__main__: The environment where the top-level script is run.") 中的元数据生效，请使用 [`-m`](../using/cmdline.xhtml#cmdoption-m) 开关。
还要注意即使是在 `__main__` 对应于一个可导入模块且 `__main__.__spec__` 被相应地设定时，它们仍会被视为 *不同的* 模块。 这是由于以下事实：使用 `if __name__ == "__main__":` 检测来保护的代码块仅会在模块被用来填充 `__main__` 命名空间时而非普通的导入时被执行。
## 5.9. 开放问题项
XXX 最好是能增加一个图表。
XXX \* (import\_machinery.rst) 是否要专门增加一节来说明模块和包的属性，也许可以扩展或移植数据模型参考页中的相关条目？
XXX 库手册中的 runpy 和 pkgutil 等等应该都在页面顶端增加指向新的导入系统章节的“另请参阅”链接。
XXX 是否要增加关于初始化 `__main__` 的不同方式的更多解释？
XXX 增加更多有关 `__main__` 怪异/坑人特性的信息 (例如直接从 [**PEP 395**](https://www.python.org/dev/peps/pep-0395) \[https://www.python.org/dev/peps/pep-0395\] 复制)。
## 5.10. 参考文献
导入机制自 Python 诞生之初至今已发生了很大的变化。 原始的 [包规格说明](https://www.python.org/doc/essays/packages/) \[https://www.python.org/doc/essays/packages/\] 仍然可以查阅，但在撰写该文档之后许多相关细节已被修改。
原始的 [`sys.meta_path`](../library/sys.xhtml#sys.meta_path "sys.meta_path") 规格说明见 [**PEP 302**](https://www.python.org/dev/peps/pep-0302) \[https://www.python.org/dev/peps/pep-0302\]，后续的扩展说明见 [**PEP 420**](https://www.python.org/dev/peps/pep-0420) \[https://www.python.org/dev/peps/pep-0420\]。
[**PEP 420**](https://www.python.org/dev/peps/pep-0420) \[https://www.python.org/dev/peps/pep-0420\] 为 Python 3.3 引入了 [命名空间包](../glossary.xhtml#term-namespace-package)。 [**PEP 420**](https://www.python.org/dev/peps/pep-0420) \[https://www.python.org/dev/peps/pep-0420\] 还引入了 `find_loader()` 协议作为 `find_module()` 的替代。
[**PEP 366**](https://www.python.org/dev/peps/pep-0366) \[https://www.python.org/dev/peps/pep-0366\] 描述了新增的 `__package__` 属性，用于在模块中的显式相对导入。
[**PEP 328**](https://www.python.org/dev/peps/pep-0328) \[https://www.python.org/dev/peps/pep-0328\] 引入了绝对和显式相对导入，并初次提出了 `__name__` 语义，最终由 [**PEP 366**](https://www.python.org/dev/peps/pep-0366) \[https://www.python.org/dev/peps/pep-0366\] 为 `__package__` 加入规范描述。
[**PEP 338**](https://www.python.org/dev/peps/pep-0338) \[https://www.python.org/dev/peps/pep-0338\] 定义了将模块作为脚本执行。
[**PEP 451**](https://www.python.org/dev/peps/pep-0451) \[https://www.python.org/dev/peps/pep-0451\] 在 spec 对象中增加了对每个模块导入状态的封装。 它还将加载器的大部分样板责任移交回导入机制中。 这些改变允许弃用导入系统中的一些 API 并为查找器和加载器增加一些新的方法。
脚注
[1](#id1)参见 [`types.ModuleType`](../library/types.xhtml#types.ModuleType "types.ModuleType")。
[2](#id2)importlib 实现避免直接使用返回值。 而是通过在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中查找模块名称来获取模块对象。 这种方式的间接影响是被导入的模块可能在 [`sys.modules`](../library/sys.xhtml#sys.modules "sys.modules") 中替换其自身。 这属于具体实现的特定行为，不保证能在其他 Python 实现中起作用。
[3](#id3)在遗留代码中，有可能在 [`sys.path_importer_cache`](../library/sys.xhtml#sys.path_importer_cache "sys.path_importer_cache") 中找到 [`imp.NullImporter`](../library/imp.xhtml#imp.NullImporter "imp.NullImporter") 的实例。 建议将这些代码修改为使用 `None` 代替。 详情参见 [Porting Python code](../whatsnew/3.3.xhtml#portingpythoncode)。
### 导航
- [索引](../genindex.xhtml "总目录")
- [模块](../py-modindex.xhtml "Python 模块索引") |
- [下一页](expressions.xhtml "6. 表达式") |
- [上一页](executionmodel.xhtml "4. 执行模型") |
- 
- [Python](https://www.python.org/) »
- zh\_CN 3.7.3 [文档](../index.xhtml) »
- [Python 语言参考](index.xhtml) »
- $('.inline-search').show(0); |
© [版权所有](../copyright.xhtml) 2001-2019, Python Software Foundation.
Python 软件基金会是一个非盈利组织。 [请捐助。](https://www.python.org/psf/donations/)
最后更新于 5月 21, 2019. [发现了问题](../bugs.xhtml)？
使用[Sphinx](http://sphinx.pocoo.org/)1.8.4 创建。
- Python文档内容
- Python 有什么新变化？
- Python 3.7 有什么新变化
- 摘要 - 发布重点
- 新的特性
- 其他语言特性修改
- 新增模块
- 改进的模块
- C API 的改变
- 构建的改变
- 性能优化
- 其他 CPython 实现的改变
- 已弃用的 Python 行为
- 已弃用的 Python 模块、函数和方法
- 已弃用的 C API 函数和类型
- 平台支持的移除
- API 与特性的移除
- 移除的模块
- Windows 专属的改变
- 移植到 Python 3.7
- Python 3.7.1 中的重要变化
- Python 3.7.2 中的重要变化
- Python 3.6 有什么新变化A
- 摘要 - 发布重点
- 新的特性
- 其他语言特性修改
- 新增模块
- 改进的模块
- 性能优化
- Build and C API Changes
- 其他改进
- 弃用
- 移除
- 移植到Python 3.6
- Python 3.6.2 中的重要变化
- Python 3.6.4 中的重要变化
- Python 3.6.5 中的重要变化
- Python 3.6.7 中的重要变化
- Python 3.5 有什么新变化
- 摘要 - 发布重点
- 新的特性
- 其他语言特性修改
- 新增模块
- 改进的模块
- Other module-level changes
- 性能优化
- Build and C API Changes
- 弃用
- 移除
- Porting to Python 3.5
- Notable changes in Python 3.5.4
- What's New In Python 3.4
- 摘要 - 发布重点
- 新的特性
- 新增模块
- 改进的模块
- CPython Implementation Changes
- 弃用
- 移除
- Porting to Python 3.4
- Changed in 3.4.3
- What's New In Python 3.3
- 摘要 - 发布重点
- PEP 405: Virtual Environments
- PEP 420: Implicit Namespace Packages
- PEP 3118: New memoryview implementation and buffer protocol documentation
- PEP 393: Flexible String Representation
- PEP 397: Python Launcher for Windows
- PEP 3151: Reworking the OS and IO exception hierarchy
- PEP 380: Syntax for Delegating to a Subgenerator
- PEP 409: Suppressing exception context
- PEP 414: Explicit Unicode literals
- PEP 3155: Qualified name for classes and functions
- PEP 412: Key-Sharing Dictionary
- PEP 362: Function Signature Object
- PEP 421: Adding sys.implementation
- Using importlib as the Implementation of Import
- 其他语言特性修改
- A Finer-Grained Import Lock
- Builtin functions and types
- 新增模块
- 改进的模块
- 性能优化
- Build and C API Changes
- 弃用
- Porting to Python 3.3
- What's New In Python 3.2
- PEP 384: Defining a Stable ABI
- PEP 389: Argparse Command Line Parsing Module
- PEP 391: Dictionary Based Configuration for Logging
- PEP 3148: The concurrent.futures module
- PEP 3147: PYC Repository Directories
- PEP 3149: ABI Version Tagged .so Files
- PEP 3333: Python Web Server Gateway Interface v1.0.1
- 其他语言特性修改
- New, Improved, and Deprecated Modules
- 多线程
- 性能优化
- Unicode
- Codecs
- 文档
- IDLE
- Code Repository
- Build and C API Changes
- Porting to Python 3.2
- What's New In Python 3.1
- PEP 372: Ordered Dictionaries
- PEP 378: Format Specifier for Thousands Separator
- 其他语言特性修改
- New, Improved, and Deprecated Modules
- 性能优化
- IDLE
- Build and C API Changes
- Porting to Python 3.1
- What's New In Python 3.0
- Common Stumbling Blocks
- Overview Of Syntax Changes
- Changes Already Present In Python 2.6
- Library Changes
- PEP 3101: A New Approach To String Formatting
- Changes To Exceptions
- Miscellaneous Other Changes
- Build and C API Changes
- 性能
- Porting To Python 3.0
- What's New in Python 2.7
- The Future for Python 2.x
- Changes to the Handling of Deprecation Warnings
- Python 3.1 Features
- PEP 372: Adding an Ordered Dictionary to collections
- PEP 378: Format Specifier for Thousands Separator
- PEP 389: The argparse Module for Parsing Command Lines
- PEP 391: Dictionary-Based Configuration For Logging
- PEP 3106: Dictionary Views
- PEP 3137: The memoryview Object
- 其他语言特性修改
- New and Improved Modules
- Build and C API Changes
- Other Changes and Fixes
- Porting to Python 2.7
- New Features Added to Python 2.7 Maintenance Releases
- Acknowledgements
- Python 2.6 有什么新变化
- Python 3.0
- Changes to the Development Process
- PEP 343: The 'with' statement
- PEP 366: Explicit Relative Imports From a Main Module
- PEP 370: Per-user site-packages Directory
- PEP 371: The multiprocessing Package
- PEP 3101: Advanced String Formatting
- PEP 3105: print As a Function
- PEP 3110: Exception-Handling Changes
- PEP 3112: Byte Literals
- PEP 3116: New I/O Library
- PEP 3118: Revised Buffer Protocol
- PEP 3119: Abstract Base Classes
- PEP 3127: Integer Literal Support and Syntax
- PEP 3129: Class Decorators
- PEP 3141: A Type Hierarchy for Numbers
- 其他语言特性修改
- New and Improved Modules
- Deprecations and Removals
- Build and C API Changes
- Porting to Python 2.6
- Acknowledgements
- What's New in Python 2.5
- PEP 308: Conditional Expressions
- PEP 309: Partial Function Application
- PEP 314: Metadata for Python Software Packages v1.1
- PEP 328: Absolute and Relative Imports
- PEP 338: Executing Modules as Scripts
- PEP 341: Unified try/except/finally
- PEP 342: New Generator Features
- PEP 343: The 'with' statement
- PEP 352: Exceptions as New-Style Classes
- PEP 353: Using ssize_t as the index type
- PEP 357: The 'index' method
- 其他语言特性修改
- New, Improved, and Removed Modules
- Build and C API Changes
- Porting to Python 2.5
- Acknowledgements
- What's New in Python 2.4
- PEP 218: Built-In Set Objects
- PEP 237: Unifying Long Integers and Integers
- PEP 289: Generator Expressions
- PEP 292: Simpler String Substitutions
- PEP 318: Decorators for Functions and Methods
- PEP 322: Reverse Iteration
- PEP 324: New subprocess Module
- PEP 327: Decimal Data Type
- PEP 328: Multi-line Imports
- PEP 331: Locale-Independent Float/String Conversions
- 其他语言特性修改
- New, Improved, and Deprecated Modules
- Build and C API Changes
- Porting to Python 2.4
- Acknowledgements
- What's New in Python 2.3
- PEP 218: A Standard Set Datatype
- PEP 255: Simple Generators
- PEP 263: Source Code Encodings
- PEP 273: Importing Modules from ZIP Archives
- PEP 277: Unicode file name support for Windows NT
- PEP 278: Universal Newline Support
- PEP 279: enumerate()
- PEP 282: The logging Package
- PEP 285: A Boolean Type
- PEP 293: Codec Error Handling Callbacks
- PEP 301: Package Index and Metadata for Distutils
- PEP 302: New Import Hooks
- PEP 305: Comma-separated Files
- PEP 307: Pickle Enhancements
- Extended Slices
- 其他语言特性修改
- New, Improved, and Deprecated Modules
- Pymalloc: A Specialized Object Allocator
- Build and C API Changes
- Other Changes and Fixes
- Porting to Python 2.3
- Acknowledgements
- What's New in Python 2.2
- 概述
- PEPs 252 and 253: Type and Class Changes
- PEP 234: Iterators
- PEP 255: Simple Generators
- PEP 237: Unifying Long Integers and Integers
- PEP 238: Changing the Division Operator
- Unicode Changes
- PEP 227: Nested Scopes
- New and Improved Modules
- Interpreter Changes and Fixes
- Other Changes and Fixes
- Acknowledgements
- What's New in Python 2.1
- 概述
- PEP 227: Nested Scopes
- PEP 236: future Directives
- PEP 207: Rich Comparisons
- PEP 230: Warning Framework
- PEP 229: New Build System
- PEP 205: Weak References
- PEP 232: Function Attributes
- PEP 235: Importing Modules on Case-Insensitive Platforms
- PEP 217: Interactive Display Hook
- PEP 208: New Coercion Model
- PEP 241: Metadata in Python Packages
- New and Improved Modules
- Other Changes and Fixes
- Acknowledgements
- What's New in Python 2.0
- 概述
- What About Python 1.6?
- New Development Process
- Unicode
- 列表推导式
- Augmented Assignment
- 字符串的方法
- Garbage Collection of Cycles
- Other Core Changes
- Porting to 2.0
- Extending/Embedding Changes
- Distutils: Making Modules Easy to Install
- XML Modules
- Module changes
- New modules
- IDLE Improvements
- Deleted and Deprecated Modules
- Acknowledgements
- 更新日志
- Python 下一版
- Python 3.7.3 最终版
- Python 3.7.3 发布候选版 1
- Python 3.7.2 最终版
- Python 3.7.2 发布候选版 1
- Python 3.7.1 最终版
- Python 3.7.1 RC 2版本
- Python 3.7.1 发布候选版 1
- Python 3.7.0 正式版
- Python 3.7.0 release candidate 1
- Python 3.7.0 beta 5
- Python 3.7.0 beta 4
- Python 3.7.0 beta 3
- Python 3.7.0 beta 2
- Python 3.7.0 beta 1
- Python 3.7.0 alpha 4
- Python 3.7.0 alpha 3
- Python 3.7.0 alpha 2
- Python 3.7.0 alpha 1
- Python 3.6.6 final
- Python 3.6.6 RC 1
- Python 3.6.5 final
- Python 3.6.5 release candidate 1
- Python 3.6.4 final
- Python 3.6.4 release candidate 1
- Python 3.6.3 final
- Python 3.6.3 release candidate 1
- Python 3.6.2 final
- Python 3.6.2 release candidate 2
- Python 3.6.2 release candidate 1
- Python 3.6.1 final
- Python 3.6.1 release candidate 1
- Python 3.6.0 final
- Python 3.6.0 release candidate 2
- Python 3.6.0 release candidate 1
- Python 3.6.0 beta 4
- Python 3.6.0 beta 3
- Python 3.6.0 beta 2
- Python 3.6.0 beta 1
- Python 3.6.0 alpha 4
- Python 3.6.0 alpha 3
- Python 3.6.0 alpha 2
- Python 3.6.0 alpha 1
- Python 3.5.5 final
- Python 3.5.5 release candidate 1
- Python 3.5.4 final
- Python 3.5.4 release candidate 1
- Python 3.5.3 final
- Python 3.5.3 release candidate 1
- Python 3.5.2 final
- Python 3.5.2 release candidate 1
- Python 3.5.1 final
- Python 3.5.1 release candidate 1
- Python 3.5.0 final
- Python 3.5.0 release candidate 4
- Python 3.5.0 release candidate 3
- Python 3.5.0 release candidate 2
- Python 3.5.0 release candidate 1
- Python 3.5.0 beta 4
- Python 3.5.0 beta 3
- Python 3.5.0 beta 2
- Python 3.5.0 beta 1
- Python 3.5.0 alpha 4
- Python 3.5.0 alpha 3
- Python 3.5.0 alpha 2
- Python 3.5.0 alpha 1
- Python 教程
- 课前甜点
- 使用 Python 解释器
- 调用解释器
- 解释器的运行环境
- Python 的非正式介绍
- Python 作为计算器使用
- 走向编程的第一步
- 其他流程控制工具
- if 语句
- for 语句
- range() 函数
- break 和 continue 语句，以及循环中的 else 子句
- pass 语句
- 定义函数
- 函数定义的更多形式
- 小插曲：编码风格
- 数据结构
- 列表的更多特性
- del 语句
- 元组和序列
- 集合
- 字典
- 循环的技巧
- 深入条件控制
- 序列和其它类型的比较
- 模块
- 有关模块的更多信息
- 标准模块
- dir() 函数
- 包
- 输入输出
- 更漂亮的输出格式
- 读写文件
- 错误和异常
- 语法错误
- 异常
- 处理异常
- 抛出异常
- 用户自定义异常
- 定义清理操作
- 预定义的清理操作
- 类
- 名称和对象
- Python 作用域和命名空间
- 初探类
- 补充说明
- 继承
- 私有变量
- 杂项说明
- 迭代器
- 生成器
- 生成器表达式
- 标准库简介
- 操作系统接口
- 文件通配符
- 命令行参数
- 错误输出重定向和程序终止
- 字符串模式匹配
- 数学
- 互联网访问
- 日期和时间
- 数据压缩
- 性能测量
- 质量控制
- 自带电池
- 标准库简介 —— 第二部分
- 格式化输出
- 模板
- 使用二进制数据记录格式
- 多线程
- 日志
- 弱引用
- 用于操作列表的工具
- 十进制浮点运算
- 虚拟环境和包
- 概述
- 创建虚拟环境
- 使用pip管理包
- 接下来？
- 交互式编辑和编辑历史
- Tab 补全和编辑历史
- 默认交互式解释器的替代品
- 浮点算术：争议和限制
- 表示性错误
- 附录
- 交互模式
- 安装和使用 Python
- 命令行与环境
- 命令行
- 环境变量
- 在Unix平台中使用Python
- 获取最新版本的Python
- 构建Python
- 与Python相关的路径和文件
- 杂项
- 编辑器和集成开发环境
- 在Windows上使用 Python
- 完整安装程序
- Microsoft Store包
- nuget.org 安装包
- 可嵌入的包
- 替代捆绑包
- 配置Python
- 适用于Windows的Python启动器
- 查找模块
- 附加模块
- 在Windows上编译Python
- 其他平台
- 在苹果系统上使用 Python
- 获取和安装 MacPython
- IDE
- 安装额外的 Python 包
- Mac 上的图形界面编程
- 在 Mac 上分发 Python 应用程序
- 其他资源
- Python 语言参考
- 概述
- 其他实现
- 标注
- 词法分析
- 行结构
- 其他形符
- 标识符和关键字
- 字面值
- 运算符
- 分隔符
- 数据模型
- 对象、值与类型
- 标准类型层级结构
- 特殊方法名称
- 协程
- 执行模型
- 程序的结构
- 命名与绑定
- 异常
- 导入系统
- importlib
- 包
- 搜索
- 加载
- 基于路径的查找器
- 替换标准导入系统
- Package Relative Imports
- 有关 main 的特殊事项
- 开放问题项
- 参考文献
- 表达式
- 算术转换
- 原子
- 原型
- await 表达式
- 幂运算符
- 一元算术和位运算
- 二元算术运算符
- 移位运算
- 二元位运算
- 比较运算
- 布尔运算
- 条件表达式
- lambda 表达式
- 表达式列表
- 求值顺序
- 运算符优先级
- 简单语句
- 表达式语句
- 赋值语句
- assert 语句
- pass 语句
- del 语句
- return 语句
- yield 语句
- raise 语句
- break 语句
- continue 语句
- import 语句
- global 语句
- nonlocal 语句
- 复合语句
- if 语句
- while 语句
- for 语句
- try 语句
- with 语句
- 函数定义
- 类定义
- 协程
- 最高层级组件
- 完整的 Python 程序
- 文件输入
- 交互式输入
- 表达式输入
- 完整的语法规范
- Python 标准库
- 概述
- 可用性注释
- 内置函数
- 内置常量
- 由 site 模块添加的常量
- 内置类型
- 逻辑值检测
- 布尔运算 — and, or, not
- 比较
- 数字类型 — int, float, complex
- 迭代器类型
- 序列类型 — list, tuple, range
- 文本序列类型 — str
- 二进制序列类型 — bytes, bytearray, memoryview
- 集合类型 — set, frozenset
- 映射类型 — dict
- 上下文管理器类型
- 其他内置类型
- 特殊属性
- 内置异常
- 基类
- 具体异常
- 警告
- 异常层次结构
- 文本处理服务
- string — 常见的字符串操作
- re — 正则表达式操作
- 模块 difflib 是一个计算差异的助手
- textwrap — Text wrapping and filling
- unicodedata — Unicode 数据库
- stringprep — Internet String Preparation
- readline — GNU readline interface
- rlcompleter — GNU readline的完成函数
- 二进制数据服务
- struct — Interpret bytes as packed binary data
- codecs — Codec registry and base classes
- 数据类型
- datetime — 基础日期/时间数据类型
- calendar — General calendar-related functions
- collections — 容器数据类型
- collections.abc — 容器的抽象基类
- heapq — 堆队列算法
- bisect — Array bisection algorithm
- array — Efficient arrays of numeric values
- weakref — 弱引用
- types — Dynamic type creation and names for built-in types
- copy — 浅层 (shallow) 和深层 (deep) 复制操作
- pprint — 数据美化输出
- reprlib — Alternate repr() implementation
- enum — Support for enumerations
- 数字和数学模块
- numbers — 数字的抽象基类
- math — 数学函数
- cmath — Mathematical functions for complex numbers
- decimal — 十进制定点和浮点运算
- fractions — 分数
- random — 生成伪随机数
- statistics — Mathematical statistics functions
- 函数式编程模块
- itertools — 为高效循环而创建迭代器的函数
- functools — 高阶函数和可调用对象上的操作
- operator — 标准运算符替代函数
- 文件和目录访问
- pathlib — 面向对象的文件系统路径
- os.path — 常见路径操作
- fileinput — Iterate over lines from multiple input streams
- stat — Interpreting stat() results
- filecmp — File and Directory Comparisons
- tempfile — Generate temporary files and directories
- glob — Unix style pathname pattern expansion
- fnmatch — Unix filename pattern matching
- linecache — Random access to text lines
- shutil — High-level file operations
- macpath — Mac OS 9 路径操作函数
- 数据持久化
- pickle —— Python 对象序列化
- copyreg — Register pickle support functions
- shelve — Python object persistence
- marshal — Internal Python object serialization
- dbm — Interfaces to Unix “databases”
- sqlite3 — SQLite 数据库 DB-API 2.0 接口模块
- 数据压缩和存档
- zlib — 与 gzip 兼容的压缩
- gzip — 对 gzip 格式的支持
- bz2 — 对 bzip2 压缩算法的支持
- lzma — 用 LZMA 算法压缩
- zipfile — 在 ZIP 归档中工作
- tarfile — Read and write tar archive files
- 文件格式
- csv — CSV 文件读写
- configparser — Configuration file parser
- netrc — netrc file processing
- xdrlib — Encode and decode XDR data
- plistlib — Generate and parse Mac OS X .plist files
- 加密服务
- hashlib — 安全哈希与消息摘要
- hmac — 基于密钥的消息验证
- secrets — Generate secure random numbers for managing secrets
- 通用操作系统服务
- os — 操作系统接口模块
- io — 处理流的核心工具
- time — 时间的访问和转换
- argparse — 命令行选项、参数和子命令解析器
- getopt — C-style parser for command line options
- 模块 logging — Python 的日志记录工具
- logging.config — 日志记录配置
- logging.handlers — Logging handlers
- getpass — 便携式密码输入工具
- curses — 终端字符单元显示的处理
- curses.textpad — Text input widget for curses programs
- curses.ascii — Utilities for ASCII characters
- curses.panel — A panel stack extension for curses
- platform — Access to underlying platform's identifying data
- errno — Standard errno system symbols
- ctypes — Python 的外部函数库
- 并发执行
- threading — 基于线程的并行
- multiprocessing — 基于进程的并行
- concurrent 包
- concurrent.futures — 启动并行任务
- subprocess — 子进程管理
- sched — 事件调度器
- queue — 一个同步的队列类
- _thread — 底层多线程 API
- _dummy_thread — _thread 的替代模块
- dummy_threading — 可直接替代 threading 模块。
- contextvars — Context Variables
- Context Variables
- Manual Context Management
- asyncio support
- 网络和进程间通信
- asyncio — 异步 I/O
- socket — 底层网络接口
- ssl — TLS/SSL wrapper for socket objects
- select — Waiting for I/O completion
- selectors — 高级 I/O 复用库
- asyncore — 异步socket处理器
- asynchat — 异步 socket 指令/响应 处理器
- signal — Set handlers for asynchronous events
- mmap — Memory-mapped file support
- 互联网数据处理
- email — 电子邮件与 MIME 处理包
- json — JSON 编码和解码器
- mailcap — Mailcap file handling
- mailbox — Manipulate mailboxes in various formats
- mimetypes — Map filenames to MIME types
- base64 — Base16, Base32, Base64, Base85 数据编码
- binhex — 对binhex4文件进行编码和解码
- binascii — 二进制和 ASCII 码互转
- quopri — Encode and decode MIME quoted-printable data
- uu — Encode and decode uuencode files
- 结构化标记处理工具
- html — 超文本标记语言支持
- html.parser — 简单的 HTML 和 XHTML 解析器
- html.entities — HTML 一般实体的定义
- XML处理模块
- xml.etree.ElementTree — The ElementTree XML API
- xml.dom — The Document Object Model API
- xml.dom.minidom — Minimal DOM implementation
- xml.dom.pulldom — Support for building partial DOM trees
- xml.sax — Support for SAX2 parsers
- xml.sax.handler — Base classes for SAX handlers
- xml.sax.saxutils — SAX Utilities
- xml.sax.xmlreader — Interface for XML parsers
- xml.parsers.expat — Fast XML parsing using Expat
- 互联网协议和支持
- webbrowser — 方便的Web浏览器控制器
- cgi — Common Gateway Interface support
- cgitb — Traceback manager for CGI scripts
- wsgiref — WSGI Utilities and Reference Implementation
- urllib — URL 处理模块
- urllib.request — 用于打开 URL 的可扩展库
- urllib.response — Response classes used by urllib
- urllib.parse — Parse URLs into components
- urllib.error — Exception classes raised by urllib.request
- urllib.robotparser — Parser for robots.txt
- http — HTTP 模块
- http.client — HTTP协议客户端
- ftplib — FTP protocol client
- poplib — POP3 protocol client
- imaplib — IMAP4 protocol client
- nntplib — NNTP protocol client
- smtplib —SMTP协议客户端
- smtpd — SMTP Server
- telnetlib — Telnet client
- uuid — UUID objects according to RFC 4122
- socketserver — A framework for network servers
- http.server — HTTP 服务器
- http.cookies — HTTP state management
- http.cookiejar — Cookie handling for HTTP clients
- xmlrpc — XMLRPC 服务端与客户端模块
- xmlrpc.client — XML-RPC client access
- xmlrpc.server — Basic XML-RPC servers
- ipaddress — IPv4/IPv6 manipulation library
- 多媒体服务
- audioop — Manipulate raw audio data
- aifc — Read and write AIFF and AIFC files
- sunau — 读写 Sun AU 文件
- wave — 读写WAV格式文件
- chunk — Read IFF chunked data
- colorsys — Conversions between color systems
- imghdr — 推测图像类型
- sndhdr — 推测声音文件的类型
- ossaudiodev — Access to OSS-compatible audio devices
- 国际化
- gettext — 多语种国际化服务
- locale — 国际化服务
- 程序框架
- turtle — 海龟绘图
- cmd — 支持面向行的命令解释器
- shlex — Simple lexical analysis
- Tk图形用户界面(GUI)
- tkinter — Tcl/Tk的Python接口
- tkinter.ttk — Tk themed widgets
- tkinter.tix — Extension widgets for Tk
- tkinter.scrolledtext — 滚动文字控件
- IDLE
- 其他图形用户界面（GUI）包
- 开发工具
- typing — 类型标注支持
- pydoc — Documentation generator and online help system
- doctest — Test interactive Python examples
- unittest — 单元测试框架
- unittest.mock — mock object library
- unittest.mock 上手指南
- 2to3 - 自动将 Python 2 代码转为 Python 3 代码
- test — Regression tests package for Python
- test.support — Utilities for the Python test suite
- test.support.script_helper — Utilities for the Python execution tests
- 调试和分析
- bdb — Debugger framework
- faulthandler — Dump the Python traceback
- pdb — The Python Debugger
- The Python Profilers
- timeit — 测量小代码片段的执行时间
- trace — Trace or track Python statement execution
- tracemalloc — Trace memory allocations
- 软件打包和分发
- distutils — 构建和安装 Python 模块
- ensurepip — Bootstrapping the pip installer
- venv — 创建虚拟环境
- zipapp — Manage executable Python zip archives
- Python运行时服务
- sys — 系统相关的参数和函数
- sysconfig — Provide access to Python's configuration information
- builtins — 内建对象
- main — 顶层脚本环境
- warnings — Warning control
- dataclasses — 数据类
- contextlib — Utilities for with-statement contexts
- abc — 抽象基类
- atexit — 退出处理器
- traceback — Print or retrieve a stack traceback
- future — Future 语句定义
- gc — 垃圾回收器接口
- inspect — 检查对象
- site — Site-specific configuration hook
- 自定义 Python 解释器
- code — Interpreter base classes
- codeop — Compile Python code
- 导入模块
- zipimport — Import modules from Zip archives
- pkgutil — Package extension utility
- modulefinder — 查找脚本使用的模块
- runpy — Locating and executing Python modules
- importlib — The implementation of import
- Python 语言服务
- parser — Access Python parse trees
- ast — 抽象语法树
- symtable — Access to the compiler's symbol tables
- symbol — 与 Python 解析树一起使用的常量
- token — 与Python解析树一起使用的常量
- keyword — 检验Python关键字
- tokenize — Tokenizer for Python source
- tabnanny — 模糊缩进检测
- pyclbr — Python class browser support
- py_compile — Compile Python source files
- compileall — Byte-compile Python libraries
- dis — Python 字节码反汇编器
- pickletools — Tools for pickle developers
- 杂项服务
- formatter — Generic output formatting
- Windows系统相关模块
- msilib — Read and write Microsoft Installer files
- msvcrt — Useful routines from the MS VC++ runtime
- winreg — Windows 注册表访问
- winsound — Sound-playing interface for Windows
- Unix 专有服务
- posix — The most common POSIX system calls
- pwd — 用户密码数据库
- spwd — The shadow password database
- grp — The group database
- crypt — Function to check Unix passwords
- termios — POSIX style tty control
- tty — 终端控制功能
- pty — Pseudo-terminal utilities
- fcntl — The fcntl and ioctl system calls
- pipes — Interface to shell pipelines
- resource — Resource usage information
- nis — Interface to Sun's NIS (Yellow Pages)
- Unix syslog 库例程
- 被取代的模块
- optparse — Parser for command line options
- imp — Access the import internals
- 未创建文档的模块
- 平台特定模块
- 扩展和嵌入 Python 解释器
- 推荐的第三方工具
- 不使用第三方工具创建扩展
- 使用 C 或 C++ 扩展 Python
- 自定义扩展类型：教程
- 定义扩展类型：已分类主题
- 构建C/C++扩展
- 在Windows平台编译C和C++扩展
- 在更大的应用程序中嵌入 CPython 运行时
- Embedding Python in Another Application
- Python/C API 参考手册
- 概述
- 代码标准
- 包含文件
- 有用的宏
- 对象、类型和引用计数
- 异常
- 嵌入Python
- 调试构建
- 稳定的应用程序二进制接口
- The Very High Level Layer
- Reference Counting
- 异常处理
- Printing and clearing
- 抛出异常
- Issuing warnings
- Querying the error indicator
- Signal Handling
- Exception Classes
- Exception Objects
- Unicode Exception Objects
- Recursion Control
- 标准异常
- 标准警告类别
- 工具
- 操作系统实用程序
- 系统功能
- 过程控制
- 导入模块
- Data marshalling support
- 语句解释及变量编译
- 字符串转换与格式化
- 反射
- 编解码器注册与支持功能
- 抽象对象层
- Object Protocol
- 数字协议
- Sequence Protocol
- Mapping Protocol
- 迭代器协议
- 缓冲协议
- Old Buffer Protocol
- 具体的对象层
- 基本对象
- 数值对象
- 序列对象
- 容器对象
- 函数对象
- 其他对象
- Initialization, Finalization, and Threads
- 在Python初始化之前
- 全局配置变量
- Initializing and finalizing the interpreter
- Process-wide parameters
- Thread State and the Global Interpreter Lock
- Sub-interpreter support
- Asynchronous Notifications
- Profiling and Tracing
- Advanced Debugger Support
- Thread Local Storage Support
- 内存管理
- 概述
- 原始内存接口
- Memory Interface
- 对象分配器
- 默认内存分配器
- Customize Memory Allocators
- The pymalloc allocator
- tracemalloc C API
- 示例
- 对象实现支持
- 在堆中分配对象
- Common Object Structures
- Type 对象
- Number Object Structures
- Mapping Object Structures
- Sequence Object Structures
- Buffer Object Structures
- Async Object Structures
- 使对象类型支持循环垃圾回收
- API 和 ABI 版本管理
- 分发 Python 模块
- 关键术语
- 开源许可与协作
- 安装工具
- 阅读指南
- 我该如何...？
- ...为我的项目选择一个名字？
- ...创建和分发二进制扩展？
- 安装 Python 模块
- 关键术语
- 基本使用
- 我应如何 ...？
- ... 在 Python 3.4 之前的 Python 版本中安装 pip ？
- ... 只为当前用户安装软件包？
- ... 安装科学计算类 Python 软件包？
- ... 使用并行安装的多个 Python 版本？
- 常见的安装问题
- 在 Linux 的系统 Python 版本上安装
- 未安装 pip
- 安装二进制编译扩展
- Python 常用指引
- 将 Python 2 代码迁移到 Python 3
- 简要说明
- 详情
- 将扩展模块移植到 Python 3
- 条件编译
- 对象API的更改
- 模块初始化和状态
- CObject 替换为 Capsule
- 其他选项
- Curses Programming with Python
- What is curses?
- Starting and ending a curses application
- Windows and Pads
- Displaying Text
- User Input
- For More Information
- 实现描述器
- 摘要
- 定义和简介
- 描述器协议
- 发起调用描述符
- 描述符示例
- Properties
- 函数和方法
- Static Methods and Class Methods
- 函数式编程指引
- 概述
- 迭代器
- 生成器表达式和列表推导式
- 生成器
- 内置函数
- itertools 模块
- The functools module
- Small functions and the lambda expression
- Revision History and Acknowledgements
- 引用文献
- 日志 HOWTO
- 日志基础教程
- 进阶日志教程
- 日志级别
- 有用的处理程序
- 记录日志中引发的异常
- 使用任意对象作为消息
- 优化
- 日志操作手册
- 在多个模块中使用日志
- 在多线程中使用日志
- 使用多个日志处理器和多种格式化
- 在多个地方记录日志
- 日志服务器配置示例
- 处理日志处理器的阻塞
- Sending and receiving logging events across a network
- Adding contextual information to your logging output
- Logging to a single file from multiple processes
- Using file rotation
- Use of alternative formatting styles
- Customizing LogRecord
- Subclassing QueueHandler - a ZeroMQ example
- Subclassing QueueListener - a ZeroMQ example
- An example dictionary-based configuration
- Using a rotator and namer to customize log rotation processing
- A more elaborate multiprocessing example
- Inserting a BOM into messages sent to a SysLogHandler
- Implementing structured logging
- Customizing handlers with dictConfig()
- Using particular formatting styles throughout your application
- Configuring filters with dictConfig()
- Customized exception formatting
- Speaking logging messages
- Buffering logging messages and outputting them conditionally
- Formatting times using UTC (GMT) via configuration
- Using a context manager for selective logging
- 正则表达式HOWTO
- 概述
- 简单模式
- 使用正则表达式
- 更多模式能力
- 修改字符串
- 常见问题
- 反馈
- 套接字编程指南
- 套接字
- 创建套接字
- 使用一个套接字
- 断开连接
- 非阻塞的套接字
- 排序指南
- 基本排序
- 关键函数
- Operator 模块函数
- 升序和降序
- 排序稳定性和排序复杂度
- 使用装饰-排序-去装饰的旧方法
- 使用 cmp 参数的旧方法
- 其它
- Unicode 指南
- Unicode 概述
- Python's Unicode Support
- Reading and Writing Unicode Data
- Acknowledgements
- 如何使用urllib包获取网络资源
- 概述
- Fetching URLs
- 处理异常
- info and geturl
- Openers and Handlers
- Basic Authentication
- Proxies
- Sockets and Layers
- 脚注
- Argparse 教程
- 概念
- 基础
- 位置参数介绍
- Introducing Optional arguments
- Combining Positional and Optional arguments
- Getting a little more advanced
- Conclusion
- ipaddress模块介绍
- 创建 Address/Network/Interface 对象
- 审查 Address/Network/Interface 对象
- Network 作为 Address 列表
- 比较
- 将IP地址与其他模块一起使用
- 实例创建失败时获取更多详细信息
- Argument Clinic How-To
- The Goals Of Argument Clinic
- Basic Concepts And Usage
- Converting Your First Function
- Advanced Topics
- 使用 DTrace 和 SystemTap 检测CPython
- Enabling the static markers
- Static DTrace probes
- Static SystemTap markers
- Available static markers
- SystemTap Tapsets
- 示例
- Python 常见问题
- Python常见问题
- 一般信息
- 现实世界中的 Python
- 编程常见问题
- 一般问题
- 核心语言
- 数字和字符串
- 性能
- 序列（元组/列表）
- 对象
- 模块
- 设计和历史常见问题
- 为什么Python使用缩进来分组语句？
- 为什么简单的算术运算得到奇怪的结果？
- 为什么浮点计算不准确？
- 为什么Python字符串是不可变的？
- 为什么必须在方法定义和调用中显式使用“self”？
- 为什么不能在表达式中赋值？
- 为什么Python对某些功能（例如list.index()）使用方法来实现，而其他功能（例如len(List)）使用函数实现？
- 为什么 join()是一个字符串方法而不是列表或元组方法？
- 异常有多快？
- 为什么Python中没有switch或case语句？
- 难道不能在解释器中模拟线程，而非得依赖特定于操作系统的线程实现吗？
- 为什么lambda表达式不能包含语句？
- 可以将Python编译为机器代码，C或其他语言吗？
- Python如何管理内存？
- 为什么CPython不使用更传统的垃圾回收方案？
- CPython退出时为什么不释放所有内存？
- 为什么有单独的元组和列表数据类型？
- 列表是如何在CPython中实现的？
- 字典是如何在CPython中实现的？
- 为什么字典key必须是不可变的？
- 为什么 list.sort() 没有返回排序列表？
- 如何在Python中指定和实施接口规范？
- 为什么没有goto？
- 为什么原始字符串（r-strings）不能以反斜杠结尾？
- 为什么Python没有属性赋值的“with”语句？
- 为什么 if/while/def/class语句需要冒号？
- 为什么Python在列表和元组的末尾允许使用逗号？
- 代码库和插件 FAQ
- 通用的代码库问题
- 通用任务
- 线程相关
- 输入输出
- 网络 / Internet 编程
- 数据库
- 数学和数字
- 扩展/嵌入常见问题
- 可以使用C语言中创建自己的函数吗？
- 可以使用C++语言中创建自己的函数吗？
- C很难写，有没有其他选择？
- 如何从C执行任意Python语句？
- 如何从C中评估任意Python表达式？
- 如何从Python对象中提取C的值？
- 如何使用Py_BuildValue()创建任意长度的元组？
- 如何从C调用对象的方法？
- 如何捕获PyErr_Print()（或打印到stdout / stderr的任何内容）的输出？
- 如何从C访问用Python编写的模块？
- 如何从Python接口到C ++对象？
- 我使用Setup文件添加了一个模块，为什么make失败了？
- 如何调试扩展？
- 我想在Linux系统上编译一个Python模块，但是缺少一些文件。为什么?
- 如何区分“输入不完整”和“输入无效”？
- 如何找到未定义的g++符号__builtin_new或__pure_virtual？
- 能否创建一个对象类，其中部分方法在C中实现，而其他方法在Python中实现（例如通过继承）？
- Python在Windows上的常见问题
- 我怎样在Windows下运行一个Python程序？
- 我怎么让 Python 脚本可执行？
- 为什么有时候 Python 程序会启动缓慢？
- 我怎样使用Python脚本制作可执行文件？
- *.pyd 文件和DLL文件相同吗？
- 我怎样将Python嵌入一个Windows程序？
- 如何让编辑器不要在我的 Python 源代码中插入 tab ？
- 如何在不阻塞的情况下检查按键？
- 图形用户界面（GUI）常见问题
- 图形界面常见问题
- Python 是否有平台无关的图形界面工具包？
- 有哪些Python的GUI工具是某个平台专用的？
- 有关Tkinter的问题
- “为什么我的电脑上安装了 Python ？”
- 什么是Python？
- 为什么我的电脑上安装了 Python ？
- 我能删除 Python 吗？
- 术语对照表
- 文档说明
- Python 文档贡献者
- 解决 Bug
- 文档错误
- 使用 Python 的错误追踪系统
- 开始为 Python 贡献您的知识
- 版权
- 历史和许可证
- 软件历史
- 访问Python或以其他方式使用Python的条款和条件
- Python 3.7.3 的 PSF 许可协议
- Python 2.0 的 BeOpen.com 许可协议
- Python 1.6.1 的 CNRI 许可协议
- Python 0.9.0 至 1.2 的 CWI 许可协议
- 集成软件的许可和认可
- Mersenne Twister
- 套接字
- Asynchronous socket services
- Cookie management
- Execution tracing
- UUencode and UUdecode functions
- XML Remote Procedure Calls
- test_epoll
- Select kqueue
- SipHash24
- strtod and dtoa
- OpenSSL
- expat
- libffi
- zlib
- cfuhash
- libmpdec