CPython 3.16 修复 Py_RunMain 退出码语义：返回 int 而非调用 Py_Exit，让嵌入方掌控进程退出流程

CPython 3.16 修复 Py_RunMain 退出码语义：返回 int 而非调用 Py_Exit，让嵌入方掌控进程退出流程

【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython

本篇文章聚焦 CPython 主分支（当前版本 3.16.0a0，见 Include/patchlevel.h）中一项 C API 行为修复：Py_RunMain()在运行脚本、-c命令或交互式 REPL 之后，不再直接调用Py_Exit()终止进程，而是以int退出码的形式返回给调用者。读完本文，你将理解该修复的动机、Py_RunMain()在 Modules/main.c 中的完整调用链与退出码来源，掌握如何在自己嵌入 Python 的程序中正确利用这一返回值，并了解 Programs/_testembed.c 与 Lib/test/test_embed.py 中的回归测试是如何锁定该行为的。

背景：Py_RunMain 的职责与旧行为的问题

Py_RunMain()是 PEP 587「Python Initialization Configuration」（以及后续 PEP 741）为嵌入场景设计的核心入口之一，在 Include/cpython/pylifecycle.h 中声明为：

PyAPI_FUNC(int) Py_RunMain(void);

它负责在 Python 运行时已经通过Py_InitializeFromConfig()完成初始化之后，真正"跑起来"一段 Python 程序——这段程序可以是命令行脚本（python script.py）、模块（python -m module）、-c命令（python -c code），也可以是交互式 REPL（python/python -i）。标准命令行解释器Py_Main()最终也经由pymain_main()调用Py_RunMain()（见 Modules/main.c），因此它是 CPython 可执行文件主循环的公共入口。

修复前的行为存在一个嵌入场景的痛点：当被运行的 Python 代码通过sys.exit(123)或抛出的SystemExit决定进程退出码时，Py_RunMain()内部会直接调用Py_Exit()终止整个宿主进程。这意味着：

• 嵌入方（embedding application）永远拿不到这次 Python 执行的退出码；
• Py_Exit()之后宿主自身的清理逻辑（释放资源、写日志、返回自定义状态给操作系统）完全没有机会执行；
• 调用Py_RunMain()之后的任何 C 代码都是不可达的，函数签名中的int返回值形同虚设。

本次修复（对应 gh-issue-152132，补丁作者 Victor Stinner）正是要改变这一局面：运行脚本、命令或 REPL 后，Py_RunMain()返回退出码，而不再调用Py_Exit()。

修复后的实现：退出码如何一路返回到调用者

修复后的Py_RunMain()实现在 Modules/main.c，核心逻辑如下：

int Py_RunMain(void) { int exitcode = 0; _PyRuntime.signals.unhandled_keyboard_interrupt = 0; pymain_run_python(&exitcode); if (Py_FinalizeEx() < 0) { /* Value unlikely to be confused with a non-error exit status or other special meaning */ exitcode = 120; } pymain_free(); if (_PyRuntime.signals.unhandled_keyboard_interrupt) { exitcode = exit_sigint(); } return exitcode; }

可以清晰地看到三条退出码来源路径：

1. Python 代码自身的退出码：pymain_run_python(&exitcode)（见 Modules/main.c）根据PyConfig的配置分发执行，并把结果写入exitcode：
   • config->run_command非空（-c命令）→pymain_run_command()；
   • config->run_module非空（-m模块）→pymain_run_module()；
   • 存在main_importer_path（目录形式的脚本）→ 以__main__模块运行；
   • config->run_filename非空（脚本文件）→pymain_run_file()；
   • 否则 →pymain_run_stdin()（交互式 REPL 或从标准输入读取）。 无论是sys.exit(n)显式设置的SystemExit，还是脚本自然结束，最终都会汇聚为这个int退出码返回。
2. Py_FinalizeEx()失败：若终结解释器时出错，返回码被置为 120，并注释说明这是"不太可能与正常退出状态混淆的特殊值"。
3. 未处理的键盘中断：如果运行期间发生了未被捕获的KeyboardInterrupt（即_PyRuntime.signals.unhandled_keyboard_interrupt被置位），则调用exit_sigint()（见 Modules/main.c）——该函数故意通过 SIGINT 的SIG_DFL默认处理器自杀式退出，以保证外层 shell 等进程能正确感知用户按下的^C，而不是把 130 之类的数值伪装成正常返回。

配套变化：pymain_main 与初始化失败路径

与Py_RunMain()的语义对齐，pymain_main()也做了相应调整（Modules/main.c）：

static int pymain_main(_PyArgv *args) { PyStatus status = pymain_init(args); if (_PyStatus_IS_EXIT(status)) { pymain_free(); return status.exitcode; /* 直接返回，而不是调用 Py_Exit() */ } if (_PyStatus_EXCEPTION(status)) { pymain_exit_error(status); } return Py_RunMain(); }

当pymain_init()返回一个"退出"状态的PyStatus（例如命令行参数解析阶段要求立即退出）时，现在同样先执行pymain_free()清理，再直接返回status.exitcode。

需要强调的是，这并不意味着Py_Exit系列的语义被完全移除。Py_ExitStatusException()（在 Include/cpython/pylifecycle.h 中声明为_Py_NO_RETURN）仍然保留，用于真正异常性错误的退出场景，例如初始化失败需要打印错误信息并携带非零退出码终止进程时，见pymain_exit_error()（Modules/main.c）以及 Doc/c-api/init_config.rst 示例中的exception:分支。也就是说，本次修复的边界非常明确：正常执行脚本/命令/REPL 属于"可返回"的流程，而初始化失败属于"不可恢复、必须终止"的流程。

嵌入方如何受益：一个可运行的完整示例

官方文档 Doc/c-api/init_config.rst 给出了自定义 Python 程序的标准骨架，修复后的Py_RunMain()让这个骨架真正完整——return Py_RunMain();会把 Python 代码的退出码作为宿主程序的返回值：

int main(int argc, char **argv) { PyStatus status; PyConfig config; PyConfig_InitPythonConfig(&config); config.isolated = 1; /* Decode command line arguments. Implicitly preinitialize Python (in isolated mode). */ status = PyConfig_SetBytesArgv(&config, argc, argv); if (PyStatus_Exception(status)) { goto exception; } status = Py_InitializeFromConfig(&config); if (PyStatus_Exception(status)) { goto exception; } PyConfig_Clear(&config); return Py_RunMain(); exception: PyConfig_Clear(&config); if (PyStatus_IsExit(status)) { return status.exitcode; } /* Display the error message and exit the process with non-zero exit code */ Py_ExitStatusException(status); }

在这个模式下，宿主程序可以把Py_RunMain()的返回值继续向上传递，或在其后进行自己的收尾工作，例如：

int exitcode = Py_RunMain(); /* 宿主自己的清理逻辑，例如关闭日志、释放非 Python 资源 */ fflush(stdout); return exitcode;

这正是本次修复的实战价值：Py_RunMain()的int返回值从"永远不可达的占位符"变成了嵌入方可依赖的真实退出码。由于 Include/cpython/pylifecycle.h 的 API 签名并未改变，现有嵌入代码无需重新编译即可获得新行为，属于纯语义层面的向后兼容改进。

回归测试：锁定返回 123 而非调用 Py_Exit

该修复在测试层面有非常直接的验证。核心用例是 Programs/_testembed.c 中的test_init_run_main_exitcode：

static int test_init_run_main_exitcode(Py_ssize_t argc, wchar_t * const *argv) { PyConfig config; ... int exitcode = Py_RunMain(); if (exitcode != 123) { error_fmt("Py_RunMain() returned %i, expected 123", exitcode); return 1; } // If Py_RunMain() calls Py_Exit(), this message is not written to stdout printf("ok! Py_RunMain() returned 123\n"); return 0; }

注意其中的注释：如果Py_RunMain()调用Py_Exit()，这行printf永远不会执行。因此该测试既验证了返回码的数值，也验证了"进程没有被提前终止"这一关键行为。

同一文件还针对四种运行模式分别构造了参数组合（Programs/_testembed.c）：

对应的 Python 侧断言位于 Lib/test/test_embed.py：check_program_exitcode()通过run_embedded_interpreter()运行内嵌解释器，并断言标准输出恰好为'ok! Py_RunMain() returned 123'且 stderr 为空。

此外，Programs/_testembed.c 中的test_run_main_loop验证了Py_InitializeFromConfig() + Py_RunMain()可被连续调用 5 次而不崩溃（对应历史 bpo-40413），而test_repeated_init_and_inittab（同文件 Programs/_testembed.c）则确认Py_RunMain()退出时通过pymain_free()内部的_PyImport_Fini2()重置PyImport_Inittab，保证再次初始化前可以重新注册内建模块——这些都与"返回而非终止"的新流程共同保证了嵌入方可反复初始化、运行、终结 Python 运行时。

与 PyConfig 的配合：sys.path 与运行目标

Py_RunMain()的行为深度依赖 PyConfig 的配置。文档明确指出（Doc/c-api/init_config.rst），Py_RunMain()与Py_Main()都会修改sys.path：

• 若run_filename指向一个包含__main__.py的目录，则将该目录前置到sys.path；
• 若isolated为零且设置了run_module，将当前目录前置到sys.path；
• 若设置了run_filename，将该文件所在目录前置到sys.path。

而safe_path配置项（Doc/c-api/init_config.rst）则控制Py_RunMain()启动时是否前置"潜在不安全"的路径：-m模式前置当前工作目录，脚本模式前置脚本目录（符号链接会被解析），-c与裸python模式前置空字符串（即当前工作目录）；-P选项将其置为 1 以关闭这些隐式路径注入。这些行为决定了嵌入方通过config.run_command/config.run_module/config.run_filename指定执行目标后，Py_RunMain()究竟会以何种方式找到并运行代码。

影响与注意事项小结

• 行为变化：Py_RunMain()运行脚本、-c命令或 REPL 后返回退出码，不再调用Py_Exit()；pymain_main()在初始化阶段遇到退出类PyStatus时同样改为直接返回status.exitcode。
• 保留边界：真正不可恢复的初始化异常仍由_Py_NO_RETURN的Py_ExitStatusException()终止进程，宿主代码不应假设所有路径都能返回。
• 键盘中断：未处理的KeyboardInterrupt走exit_sigint()路径，通过 SIGINT 默认行为终止，以便 shell 感知^C，此时函数不会正常返回。
• 嵌入价值：宿主现在可以在Py_RunMain()返回后执行自定义清理，并把 Python 侧退出码（如sys.exit(123)的 123）原样透传给操作系统，这是编写"以 Python 为脚本引擎的宿主程序"时的关键能力。

如果你正在维护一个嵌入 CPython 的 C/C++ 应用，建议对照 Programs/_testembed.c 中的test_init_run_main_*系列用例检查自身退出码处理逻辑，并在升级到包含本修复的 CPython 版本后，将Py_RunMain()的返回值纳入宿主退出流程。

【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython