CPython os.exec* 系列函数错误信息改进为 FileNotFoundError / NotADirectoryError 填充 filename 属性【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython本文围绕 CPython 仓库中 Misc/NEWS.d/next/Library/2020-05-05-06-05-24.gh-issue-84687.ggjoGl.rst 这条库变更记录展开讲解os.exec*系列函数os.execl、os.execv、os.execvp、os.execve、os.execvpe等在底层系统调用失败时如何将OSError.filename属性设置为调用者传入的程序名并结合 Modules/posixmodule.c 的 C 实现与 Lib/test/test_os 下的测试用例进行源码级验证。读完本文你将理解os.exec*家族的错误处理链路、OSError.filename的填充机制以及如何在真实场景中借助该属性快速定位程序路径错误。一、变更概述一条 NEWS 条目背后的行为改进该 NEWS 条目全文如下Theos.exec* os.execlfunctions now set the~OSError.filenameattribute of the raisedFileNotFoundErrororNotADirectoryErrorto the program name passed by the caller.翻译过来即os.exec*系列函数现在会把抛出的FileNotFoundError或NotADirectoryError的OSError.filename属性设置为调用者传入的程序名。这是一个典型的错误信息可诊断性diagnosability改进在此之前os.exec*系列函数在执行失败时抛出的异常未必携带程序名信息开发者只能通过异常消息文本去猜测是哪个路径出了问题改进之后异常对象上会附带结构化的filename字段便于程序化地捕获、检查与报告错误。从文件名的日期2020-05-05与官方问题编号gh-issue-84687可以看出这条变更提交于 CPython 3.10 的开发周期属于该版本的库Library行为改进之一。相关变更仍保留在仓库的 NEWS 记录目录中作为该行为变更的官方存档。二、背景知识os.exec* 家族是谁在深入了解该改动之前先回顾os.exec*系列函数在标准库中的定位。它们位于 Modules/posixmodule.c是posix模块即os模块的底层实现的一部分功能是用新的程序替换当前进程因此成功时不会返回失败时才抛出OSError及其子类。常见的成员包括函数程序路径来源参数形式os.execl(path, arg0, arg1, ...)直接指定路径可变长参数os.execv(path, args)直接指定路径列表 / 元组os.execle(path, arg0, ..., env)直接指定路径可变长参数 环境字典os.execve(path, args, env)直接指定路径列表 环境字典os.execlp(file, arg0, arg1, ...)在PATH中搜索可变长参数os.execvp(file, args)在PATH中搜索列表 / 元组os.execlpe(file, arg0, ..., env)在PATH中搜索可变长参数 环境字典os.execvpe(file, args, env)在PATH中搜索列表 环境字典其中以p结尾的变体会在PATH环境变量中搜索程序以e结尾的变体允许显式传入环境字典。它们的共同特征是一旦底层exec*系统调用失败例如目标文件不存在、路径指向了目录而非可执行文件当前进程并不会被替换而是向调用方抛出异常。三、改动核心filename 属性从何而来本变更的核心内容非常聚焦当os.exec*系列函数抛出的异常类型为FileNotFoundError对应系统错误ENOENT或NotADirectoryError对应系统错误ENOTDIR时异常对象的filename属性会被设置为调用者传入的程序名。这里程序名指的就是调用os.exec*时传入的第一个参数例如import os os.execvp(no_such_program, [no_such_program])在上述调用中程序名是字符串no_such_program。改进之前异常对象上未必能可靠地取得这一信息改进之后捕获到的异常将具备try: os.execvp(no_such_program, [no_such_program]) except FileNotFoundError as exc: assert exc.filename no_such_program # 现在为 True print(exc.filename) # no_such_programfilename是OSError的标准属性之一通常用于记录出错时所操作的文件路径与异常消息文本相比它是结构化的字段可以直接用于日志结构化、告警字段填充、以及错误聚合等场景。为什么这对开发者重要快速定位程序路径问题当脚本因可执行文件不存在而失败时exc.filename直接给出出错路径无需解析异常消息字符串。支持编程式处理上层框架或运维工具可以捕获OSError检查filename字段判断是否为 exec 类失败进而决定重试、回退或告警策略。与其他 os 模块错误行为对齐os.open、os.remove等路径相关函数早已在异常中携带filename本次改动使os.exec*家族的错误语义与之一致。四、源码级验证错误处理链路的实际实现4.1 错误设置入口path_error 系列辅助函数在 Modules/posixmodule.c 中路径相关错误统一由一组辅助函数生成static PyObject * path_error(path_t *path) { return path_object_error(path-object); } static PyObject * posix_path_error(path_t *path) { return posix_path_object_error(path-object); } static PyObject * path_error2(path_t *path, path_t *path2) { return path_object_error2(path-object, path2-object); }对应 Modules/posixmodule.c其中posix_path_object_error最终会调用PyErr_SetFromErrnoWithFilenameObjects之类的 C API把当前的errno转换为对应的OSError子类ENOENT→FileNotFoundErrorENOTDIR→NotADirectoryError同时把路径对象写入异常的filename属性。这正是程序名被设置到filename这一行为的底层实现机制。4.2 os.execv 的实现os.execv的 C 实现位于 Modules/posixmodule.c其关键流程如下os_execv_impl(PyObject *module, path_t *path, PyObject *argv) { /* ... 参数校验argv 必须是列表/元组、不能为空、 首个元素不能为空字符串 ... */ if (PySys_Audit(os.exec, OO, path-object, argv, NULL) 0) { goto fail_1; } #ifdef HAVE_WEXECV _wexecv(path-wide, argvlist); #else execv(path-narrow, argvlist); #endif /* If we get here its definitely an error */ posix_path_error(path); /* ... 释放资源 ... */ }可以看到当execv()系统调用失败返回后代码立即调用posix_path_error(path)把errno转换成对应的OSError子类并将path-object即调用者传入的程序名对象写入异常的filename属性。4.3 os.execve 的实现os.execve的 C 实现位于 Modules/posixmodule.c处理逻辑与os.execv类似但多了对env参数的解析与校验并支持通过文件描述符执行HAVE_FEXECVE时使用fexecve(path-fd, ...)os_execve_impl(PyObject *module, path_t *path, PyObject *argv, PyObject *env) { /* ... argv 与 env 的类型、空值校验 ... */ if (PySys_Audit(os.exec, OOO, path-object, argv, env) 0) { goto fail_1; } #ifdef HAVE_FEXECVE if (path-is_fd) fexecve(path-fd, argvlist, envlist); else #endif #ifdef HAVE_WEXECV _wexecve(path-wide, argvlist, envlist); #else execve(path-narrow, argvlist, envlist); #endif /* If we get here its definitely an error */ posix_path_error(path); /* ... 释放资源 ... */ }同样地底层调用失败后经由posix_path_error(path)抛出携带filename的异常。其余os.execl*、os.execvpe等变体在 Python 层面会组合复用上述 C 入口os.execl在 Python 侧拼装args后调用execvos.execvp/os.execvpe在 Python 侧完成PATH搜索后调用execv/execve因此该改进覆盖整个os.exec*家族。4.4 一个值得注意的细节路径对象类型从测试代码可以看出filename属性记录的是调用者传入的原始对象而不一定是字符串。若传入的是pathlib.Path或实现了os.PathLike协议的对象filename会是该对象经os.fspath()转换后的字符串测试中通过os.fspath(bad_filename)断言。这意味着exc.filename与调用时传入的程序名保持语义一致。五、测试验证仓库中的回归测试CPython 为此行为提供了完整的回归测试集中体现在两处5.1 ExecTestsos.exec* 家族测试Lib/test/test_os/test_os.py 中的ExecTests类定义了_test_bad_program辅助方法对os.execv、os.execvp、os.execve、os.execvpe逐一验证def _test_bad_program(self, do_exec, exc_typeOSError): bad_filenames [nosuchapp, FakePath(nosuchapp)] if os.name ! nt: # Bytes program names are not supported on Windows. bad_filenames [bnosuchapp, FakePath(bnosuchapp)] for bad_filename in bad_filenames: with self.subTest(bad_filename): with self.assertRaises(exc_type) as ctx: do_exec(bad_filename) self.assertEqual(ctx.exception.filename, os.fspath(bad_filename)) self.assertIn(nosuchapp, str(ctx.exception)) def test_execv_with_bad_program(self): self._test_bad_program(lambda name: os.execv(name, [nosuchapp])) def test_execvp_with_bad_program(self): self._test_bad_program(lambda name: os.execvp(name, [nosuchapp])) def test_execve_with_bad_program(self): self._test_bad_program(lambda name: os.execve(name, [nosuchapp], {})) def test_execvpe_with_bad_program(self): self._test_bad_program(lambda name: os.execvpe(name, [nosuchapp], {}))该测试断言了三件事使用不存在的程序名调用各os.exec*变体时会抛出异常异常的filename属性等于传入的程序名经os.fspath()规范化后的值异常的消息文本中包含程序名nosuchapp。测试覆盖了str、bytes、FakePathos.PathLike模拟对象等多种程序名类型确保filename属性在各种输入形态下都被正确填充。同文件后续的test_execvp_with_bad_path_entry等测试还覆盖了PATH中普通文件导致ENOTDIR即NotADirectoryError的场景验证异常类型与filename的组合行为。5.2 test_posix.pyos.posix_spawn 的同类断言Lib/test/test_os/test_posix.py 中的test_no_such_executable对os.posix_spawn做了类似验证def test_no_such_executable(self): no_such_executable no_such_executable try: pid self.spawn_func(no_such_executable, [no_such_executable], os.environ) # bpo-35794: PermissionError can be raised if there are # directories in the $PATH that are not accessible. except (FileNotFoundError, PermissionError) as exc: self.assertEqual(exc.filename, no_such_executable) ...虽然该测试针对的是os.posix_spawn但它与 NEWS 条目验证的是同一类错误语义进程启动类 API 在失败时异常应携带被查找的程序名。这表明 CPython 在错误诊断一致性上对进程启动 API 家族做了整体收口。六、实战应用如何利用该行为改进自己的代码6.1 编写可诊断的启动包装器假设你正在编写一个启动外部程序的工具函数可以利用filename属性输出更友好的错误信息import os import sys def run_program(program, args): try: os.execvpe(program, [program, *args], os.environ) except OSError as exc: # 3.10 起exc.filename 即为调用者传入的程序名 raise RuntimeError( f无法执行程序 {exc.filename!r}: {exc.strerror} ) from exc即使异常被上层框架层层包装filename字段依然保留着最初的程序路径避免了在字符串中二次解析。6.2 在日志与监控中聚合错误结构化日志可以方便地记录filename字段import logging import os logger logging.getLogger(launcher) try: os.execvp(worker, [worker, --config, /etc/app.conf]) except FileNotFoundError as exc: logger.error( exec failed: program%s errno%s, exc.filename, exc.errno, )6.3 与其他进程启动 API 对比需要注意的是本 NEWS 条目针对的是os.exec*系列以及同一错误语义体系的os.posix_spawn等。subprocess模块在Popen启动失败时同样会抛出携带filename的OSError子类二者在错误诊断语义上是一致的底层execve失败时errno与路径名都会被保留在异常对象中。七、小结这条 NEWS 条目记录了一个小而实用的库行为改进行为os.exec*系列函数在抛出FileNotFoundError或NotADirectoryError时会将OSError.filename设置为调用者传入的程序名实现底层通过 Modules/posixmodule.c 中的posix_path_error/path_error辅助函数在execv/execve系统调用失败后把路径对象写入异常filename属性参见 os.execv 实现 与 os.execve 实现验证Lib/test/test_os/test_os.py 的ExecTests覆盖了全部主要os.exec*变体及str/bytes/PathLike输入形态Lib/test/test_os/test_posix.py 则对os.posix_spawn做了同类断言。对于使用os.exec*系列编写启动器、进程替换工具或容器入口脚本的开发者而言从此可以在异常处理中直接读取exc.filename写出更健壮、更可诊断的错误处理代码。这条变更的完整记录保留在 Misc/NEWS.d/next/Library/2020-05-05-06-05-24.gh-issue-84687.ggjoGl.rst 中读者可以随时在仓库中查阅原文并结合上述源码与测试文件做进一步探究。【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CPython os.exec* 系列函数错误信息改进：为 FileNotFoundError / NotADirectoryError 填充 filename 属性
CPython os.exec* 系列函数错误信息改进为 FileNotFoundError / NotADirectoryError 填充 filename 属性【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython本文围绕 CPython 仓库中 Misc/NEWS.d/next/Library/2020-05-05-06-05-24.gh-issue-84687.ggjoGl.rst 这条库变更记录展开讲解os.exec*系列函数os.execl、os.execv、os.execvp、os.execve、os.execvpe等在底层系统调用失败时如何将OSError.filename属性设置为调用者传入的程序名并结合 Modules/posixmodule.c 的 C 实现与 Lib/test/test_os 下的测试用例进行源码级验证。读完本文你将理解os.exec*家族的错误处理链路、OSError.filename的填充机制以及如何在真实场景中借助该属性快速定位程序路径错误。一、变更概述一条 NEWS 条目背后的行为改进该 NEWS 条目全文如下Theos.exec* os.execlfunctions now set the~OSError.filenameattribute of the raisedFileNotFoundErrororNotADirectoryErrorto the program name passed by the caller.翻译过来即os.exec*系列函数现在会把抛出的FileNotFoundError或NotADirectoryError的OSError.filename属性设置为调用者传入的程序名。这是一个典型的错误信息可诊断性diagnosability改进在此之前os.exec*系列函数在执行失败时抛出的异常未必携带程序名信息开发者只能通过异常消息文本去猜测是哪个路径出了问题改进之后异常对象上会附带结构化的filename字段便于程序化地捕获、检查与报告错误。从文件名的日期2020-05-05与官方问题编号gh-issue-84687可以看出这条变更提交于 CPython 3.10 的开发周期属于该版本的库Library行为改进之一。相关变更仍保留在仓库的 NEWS 记录目录中作为该行为变更的官方存档。二、背景知识os.exec* 家族是谁在深入了解该改动之前先回顾os.exec*系列函数在标准库中的定位。它们位于 Modules/posixmodule.c是posix模块即os模块的底层实现的一部分功能是用新的程序替换当前进程因此成功时不会返回失败时才抛出OSError及其子类。常见的成员包括函数程序路径来源参数形式os.execl(path, arg0, arg1, ...)直接指定路径可变长参数os.execv(path, args)直接指定路径列表 / 元组os.execle(path, arg0, ..., env)直接指定路径可变长参数 环境字典os.execve(path, args, env)直接指定路径列表 环境字典os.execlp(file, arg0, arg1, ...)在PATH中搜索可变长参数os.execvp(file, args)在PATH中搜索列表 / 元组os.execlpe(file, arg0, ..., env)在PATH中搜索可变长参数 环境字典os.execvpe(file, args, env)在PATH中搜索列表 环境字典其中以p结尾的变体会在PATH环境变量中搜索程序以e结尾的变体允许显式传入环境字典。它们的共同特征是一旦底层exec*系统调用失败例如目标文件不存在、路径指向了目录而非可执行文件当前进程并不会被替换而是向调用方抛出异常。三、改动核心filename 属性从何而来本变更的核心内容非常聚焦当os.exec*系列函数抛出的异常类型为FileNotFoundError对应系统错误ENOENT或NotADirectoryError对应系统错误ENOTDIR时异常对象的filename属性会被设置为调用者传入的程序名。这里程序名指的就是调用os.exec*时传入的第一个参数例如import os os.execvp(no_such_program, [no_such_program])在上述调用中程序名是字符串no_such_program。改进之前异常对象上未必能可靠地取得这一信息改进之后捕获到的异常将具备try: os.execvp(no_such_program, [no_such_program]) except FileNotFoundError as exc: assert exc.filename no_such_program # 现在为 True print(exc.filename) # no_such_programfilename是OSError的标准属性之一通常用于记录出错时所操作的文件路径与异常消息文本相比它是结构化的字段可以直接用于日志结构化、告警字段填充、以及错误聚合等场景。为什么这对开发者重要快速定位程序路径问题当脚本因可执行文件不存在而失败时exc.filename直接给出出错路径无需解析异常消息字符串。支持编程式处理上层框架或运维工具可以捕获OSError检查filename字段判断是否为 exec 类失败进而决定重试、回退或告警策略。与其他 os 模块错误行为对齐os.open、os.remove等路径相关函数早已在异常中携带filename本次改动使os.exec*家族的错误语义与之一致。四、源码级验证错误处理链路的实际实现4.1 错误设置入口path_error 系列辅助函数在 Modules/posixmodule.c 中路径相关错误统一由一组辅助函数生成static PyObject * path_error(path_t *path) { return path_object_error(path-object); } static PyObject * posix_path_error(path_t *path) { return posix_path_object_error(path-object); } static PyObject * path_error2(path_t *path, path_t *path2) { return path_object_error2(path-object, path2-object); }对应 Modules/posixmodule.c其中posix_path_object_error最终会调用PyErr_SetFromErrnoWithFilenameObjects之类的 C API把当前的errno转换为对应的OSError子类ENOENT→FileNotFoundErrorENOTDIR→NotADirectoryError同时把路径对象写入异常的filename属性。这正是程序名被设置到filename这一行为的底层实现机制。4.2 os.execv 的实现os.execv的 C 实现位于 Modules/posixmodule.c其关键流程如下os_execv_impl(PyObject *module, path_t *path, PyObject *argv) { /* ... 参数校验argv 必须是列表/元组、不能为空、 首个元素不能为空字符串 ... */ if (PySys_Audit(os.exec, OO, path-object, argv, NULL) 0) { goto fail_1; } #ifdef HAVE_WEXECV _wexecv(path-wide, argvlist); #else execv(path-narrow, argvlist); #endif /* If we get here its definitely an error */ posix_path_error(path); /* ... 释放资源 ... */ }可以看到当execv()系统调用失败返回后代码立即调用posix_path_error(path)把errno转换成对应的OSError子类并将path-object即调用者传入的程序名对象写入异常的filename属性。4.3 os.execve 的实现os.execve的 C 实现位于 Modules/posixmodule.c处理逻辑与os.execv类似但多了对env参数的解析与校验并支持通过文件描述符执行HAVE_FEXECVE时使用fexecve(path-fd, ...)os_execve_impl(PyObject *module, path_t *path, PyObject *argv, PyObject *env) { /* ... argv 与 env 的类型、空值校验 ... */ if (PySys_Audit(os.exec, OOO, path-object, argv, env) 0) { goto fail_1; } #ifdef HAVE_FEXECVE if (path-is_fd) fexecve(path-fd, argvlist, envlist); else #endif #ifdef HAVE_WEXECV _wexecve(path-wide, argvlist, envlist); #else execve(path-narrow, argvlist, envlist); #endif /* If we get here its definitely an error */ posix_path_error(path); /* ... 释放资源 ... */ }同样地底层调用失败后经由posix_path_error(path)抛出携带filename的异常。其余os.execl*、os.execvpe等变体在 Python 层面会组合复用上述 C 入口os.execl在 Python 侧拼装args后调用execvos.execvp/os.execvpe在 Python 侧完成PATH搜索后调用execv/execve因此该改进覆盖整个os.exec*家族。4.4 一个值得注意的细节路径对象类型从测试代码可以看出filename属性记录的是调用者传入的原始对象而不一定是字符串。若传入的是pathlib.Path或实现了os.PathLike协议的对象filename会是该对象经os.fspath()转换后的字符串测试中通过os.fspath(bad_filename)断言。这意味着exc.filename与调用时传入的程序名保持语义一致。五、测试验证仓库中的回归测试CPython 为此行为提供了完整的回归测试集中体现在两处5.1 ExecTestsos.exec* 家族测试Lib/test/test_os/test_os.py 中的ExecTests类定义了_test_bad_program辅助方法对os.execv、os.execvp、os.execve、os.execvpe逐一验证def _test_bad_program(self, do_exec, exc_typeOSError): bad_filenames [nosuchapp, FakePath(nosuchapp)] if os.name ! nt: # Bytes program names are not supported on Windows. bad_filenames [bnosuchapp, FakePath(bnosuchapp)] for bad_filename in bad_filenames: with self.subTest(bad_filename): with self.assertRaises(exc_type) as ctx: do_exec(bad_filename) self.assertEqual(ctx.exception.filename, os.fspath(bad_filename)) self.assertIn(nosuchapp, str(ctx.exception)) def test_execv_with_bad_program(self): self._test_bad_program(lambda name: os.execv(name, [nosuchapp])) def test_execvp_with_bad_program(self): self._test_bad_program(lambda name: os.execvp(name, [nosuchapp])) def test_execve_with_bad_program(self): self._test_bad_program(lambda name: os.execve(name, [nosuchapp], {})) def test_execvpe_with_bad_program(self): self._test_bad_program(lambda name: os.execvpe(name, [nosuchapp], {}))该测试断言了三件事使用不存在的程序名调用各os.exec*变体时会抛出异常异常的filename属性等于传入的程序名经os.fspath()规范化后的值异常的消息文本中包含程序名nosuchapp。测试覆盖了str、bytes、FakePathos.PathLike模拟对象等多种程序名类型确保filename属性在各种输入形态下都被正确填充。同文件后续的test_execvp_with_bad_path_entry等测试还覆盖了PATH中普通文件导致ENOTDIR即NotADirectoryError的场景验证异常类型与filename的组合行为。5.2 test_posix.pyos.posix_spawn 的同类断言Lib/test/test_os/test_posix.py 中的test_no_such_executable对os.posix_spawn做了类似验证def test_no_such_executable(self): no_such_executable no_such_executable try: pid self.spawn_func(no_such_executable, [no_such_executable], os.environ) # bpo-35794: PermissionError can be raised if there are # directories in the $PATH that are not accessible. except (FileNotFoundError, PermissionError) as exc: self.assertEqual(exc.filename, no_such_executable) ...虽然该测试针对的是os.posix_spawn但它与 NEWS 条目验证的是同一类错误语义进程启动类 API 在失败时异常应携带被查找的程序名。这表明 CPython 在错误诊断一致性上对进程启动 API 家族做了整体收口。六、实战应用如何利用该行为改进自己的代码6.1 编写可诊断的启动包装器假设你正在编写一个启动外部程序的工具函数可以利用filename属性输出更友好的错误信息import os import sys def run_program(program, args): try: os.execvpe(program, [program, *args], os.environ) except OSError as exc: # 3.10 起exc.filename 即为调用者传入的程序名 raise RuntimeError( f无法执行程序 {exc.filename!r}: {exc.strerror} ) from exc即使异常被上层框架层层包装filename字段依然保留着最初的程序路径避免了在字符串中二次解析。6.2 在日志与监控中聚合错误结构化日志可以方便地记录filename字段import logging import os logger logging.getLogger(launcher) try: os.execvp(worker, [worker, --config, /etc/app.conf]) except FileNotFoundError as exc: logger.error( exec failed: program%s errno%s, exc.filename, exc.errno, )6.3 与其他进程启动 API 对比需要注意的是本 NEWS 条目针对的是os.exec*系列以及同一错误语义体系的os.posix_spawn等。subprocess模块在Popen启动失败时同样会抛出携带filename的OSError子类二者在错误诊断语义上是一致的底层execve失败时errno与路径名都会被保留在异常对象中。七、小结这条 NEWS 条目记录了一个小而实用的库行为改进行为os.exec*系列函数在抛出FileNotFoundError或NotADirectoryError时会将OSError.filename设置为调用者传入的程序名实现底层通过 Modules/posixmodule.c 中的posix_path_error/path_error辅助函数在execv/execve系统调用失败后把路径对象写入异常filename属性参见 os.execv 实现 与 os.execve 实现验证Lib/test/test_os/test_os.py 的ExecTests覆盖了全部主要os.exec*变体及str/bytes/PathLike输入形态Lib/test/test_os/test_posix.py 则对os.posix_spawn做了同类断言。对于使用os.exec*系列编写启动器、进程替换工具或容器入口脚本的开发者而言从此可以在异常处理中直接读取exc.filename写出更健壮、更可诊断的错误处理代码。这条变更的完整记录保留在 Misc/NEWS.d/next/Library/2020-05-05-06-05-24.gh-issue-84687.ggjoGl.rst 中读者可以随时在仓库中查阅原文并结合上述源码与测试文件做进一步探究。【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考