# `runpy` --- Locating and executing Python modules

源代码： Lib/runpy.py

`runpy` 模块用于找到并运行 Python 的模块，而无需首先导入。主要用于实现 `-m` 命令行开关，以允许用 Python 模块命名空间而不是文件系统来定位脚本。

请注意，这 并非 一个沙盒模块——所有代码都在当前进程中运行，所有副作用（如其他模块对导入操作进行了缓存）在函数返回后都会留存。

此外，在 `runpy` 函数返回后，任何由已执行代码定义的函数和类都不能保证正确工作。如果某使用场景不能接收此限制，那么选用 `importlib` 可能更合适些。

`runpy` 模块提供两个函数：

runpy.run_module(mod_name, init_globals=None, run_name=None, alter_sys=False)

  Execute the code of the specified module and return the resulting module globals dictionary. The module's code is first located using the standard import mechanism (refer to PEP 302 for details) and then executed in a fresh module namespace.

  mod_name 参数应当是一个绝对模块名。 如果模块名指向一个包而非普通模块，则会导入这个包然后执行这个包中的 `__main__` 子模块再返回模块全局字典。

  The optional dictionary argument init_globals may be used to pre-populate the module's globals dictionary before the code is executed. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by `run_module()`.

  The special global variables `__name__`, `__spec__`, `__file__`, `__cached__`, `__loader__` and `__package__` are set in the globals dictionary before the module code is executed (Note that this is a minimal set of variables - other variables may be set implicitly as an interpreter implementation detail).

  若可选参数 `__name__` 不为 `None` 则设为 run_name，若此名称的模块是一个包则设为 `mod_name + '.__main__'`，否则设为 mod_name 参数。

  `__spec__` will be set appropriately for the actually imported module (that is, `__spec__.name` will always be mod_name or `mod_name + '.__main__`, never run_name).

  `__file__` 、`__cached__`、 `__loader__` 和 `__package__` 根据模块规格进行 常规设置

  如果给出了参数 alter_sys 并且值为 `True`，那么 `sys.argv[0]` 将被更新为 `__file__` 的值，`sys.modules[__name__]` 将被更新为临时模块对象。在函数返回前， `sys.argv[0]` 和 `sys.modules[__name__]` 将会复原。

  请注意对 `sys` 的这种操作不是线程安全的。 其他线程可能会看到部分初始化的模块，以及更改后的参数列表。 建议当从线程中的代码调用此函数时不要使用 `sys` 模块。

  参见

  `-m` 选项由命令行提供相同功能。

  在 3.1 版本发生变更: 增加了通过查找 `__main__` 子模块来执行包的功能。

  在 3.2 版本发生变更: 加入了 `__cached__` 全局变量（参见 PEP 3147 ）。

  在 3.4 版本发生变更: 充分利用 PEP 451 加入的模块规格功能。使得以这种方式运行的模块能够正确设置 `__cached__`，并确保真正的模块名称总是可以通过 `__spec__.name` 的形式访问。

  在 3.12 版本发生变更: `__cached__`, `__loader__` 和 `__package__` 的设置已被弃用。 替代设置参见 `ModuleSpec`。

runpy.run_path(path_name, init_globals=None, run_name=None)

  Execute the code at the named filesystem location and return the resulting module globals dictionary. As with a script name supplied to the CPython command line, the supplied path may refer to a Python source file, a compiled bytecode file or a valid `sys.path` entry containing a `__main__` module (e.g. a zipfile containing a top-level `__main__.py` file).

  对于简单的脚本而言，只需在新的模块命名空间中执行指定的代码即可。 对于一个有效的 `sys.path` 条目（通常是一个 zip 文件或目录），首先会将该条目添加到 `sys.path` 的开头。 然后函数会使用更新后的路径查找并执行 `__main__` 模块。 请注意如果在指定的位置上没有 `__main__` 模块那么在发起调用位于 `sys.path` 中其他位置上的现有条目时也不会受到特殊保护。

  The optional dictionary argument init_globals may be used to pre-populate the module's globals dictionary before the code is executed. The supplied dictionary will not be modified. If any of the special global variables below are defined in the supplied dictionary, those definitions are overridden by `run_path()`.

  The special global variables `__name__`, `__spec__`, `__file__`, `__cached__`, `__loader__` and `__package__` are set in the globals dictionary before the module code is executed (Note that this is a minimal set of variables - other variables may be set implicitly as an interpreter implementation detail).

  如果该可选参数不为 `None`，则 `__name__` 被设为 run_name，否则为 `'<run_path>'`。

  If the supplied path directly references a script file (whether as source or as precompiled byte code), then `__file__` will be set to the supplied path, and `__spec__`, `__cached__`, `__loader__` and `__package__` will all be set to `None`.

  If the supplied path is a reference to a valid `sys.path` entry, then `__spec__` will be set appropriately for the imported `__main__` module (that is, `__spec__.name` will always be `__main__`). `__file__`, `__cached__`, `__loader__` and `__package__` will be set as normal based on the module spec.

  A number of alterations are also made to the `sys` module. Firstly, `sys.path` may be altered as described above. `sys.argv[0]` is updated with the value of `path_name` and `sys.modules[__name__]` is updated with a temporary module object for the module being executed. All modifications to items in `sys` are reverted before the function returns.

  请注意，与 `run_module()` 不同，对 `sys` 的修改在本函数中不是可选项，因为这些调整对于允许执行 `sys.path` 条目来说是至关重要的。 由于线程安全限制仍然适用，在线程代码中使用该函数应当使用导入锁进行序列化，或是委托给单独的进程。

  参见

  接口选项 用于在命令行上实现同等功能（`python path/to/script`）。

  Added in version 3.2.

  在 3.4 版本发生变更: 进行更新以便利用 PEP 451 加入的模块规格特性。 这允许在 `__main__` 是从有效的 `sys.path` 条目导入而不是直接执行的情况下能够正确地设置 `__cached__`。

  在 3.12 版本发生变更: `__cached__`, `__loader__` 和 `__package__` 已被弃用。

参见

PEP 338 -- 将模块作为脚本执行

  PEP 由 Nick Coghlan 撰写并实现。

PEP 366 ——主模块的显式相对导入

  PEP 由 Nick Coghlan 撰写并实现。

PEP 451 —— 导入系统采用的 ModuleSpec 类型

  PEP 由 Eric Snow 撰写并实现。

命令行与环境 —— CPython 命令行详解

`importlib.import_module()` 函数