"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's 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. *init_globals* will not be modified. If any of the
   special global variables below are defined in *init_globals*, 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's globals dictionary. As with a script name
   supplied to the CPython command line, *file_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. *init_globals* will not be modified. If any of the
   special global variables below are defined in *init_globals*, 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 *file_path* directly references a script file (whether as source
   or as precompiled byte code), then "__file__" will be set to
   *file_path*, and "__spec__", "__cached__", "__loader__" and
   "__package__" will all be set to "None".

   If *file_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 *file_path* 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()" 函数
