SuperAPI AI 工具集

python-reliable-subprocess-handling

编程与开发

查看项目

更新于 10-16 04:55

技能介绍

用途:记录 Python 异步子进程处理在超时、终止、进程树场景下的陷阱与应对,适合编写调用外部工具、安装器、CLI 包装器的代码时参考。

前置:本技能扩展 engineering-principles,需先加载;假定已加载 writing-python-code(无 shell=True、使用 create_subprocess_exec、处理 TimeoutError)。

主要能力:仓库提供自包含实现 shared/subprocess.py,含超时、进程树终止、调用方取消清理、两条路径上的有界 EOF 等待、输出上限、可选优雅终止窗口、可选 stderr 合并、DEVNULL stdin;配套真实进程测试 shared_tests/test_subprocess_utils.py 与由其派生的 flag 驱动子进程桩 shared_tests/fixtures/tool_stub.py,可复制到项目中改造。

关键陷阱:communicate() 在取消时丢弃已从管道读入的本地缓冲,杀进程后管道 EOF,再调用 communicate() 只能得到空串;应改为分块读入自有 holder(如 StreamCapture)。process.kill() 只终止直接子进程,孙进程仍持有管道写端导致读取阻塞,因此不应把超时上报放在清理之后;进程树终止用 psutil 快照 children(recursive=True) 后发信号,并以 contextlib.suppress 忽略 NoSuchProcess、AccessDenied、ZombieProcess。调用方取消或中途异常若无 teardown(杀进程树、取消 reader、关闭管道、回收),子进程与 reader 会被遗弃;成功路径若子进程遗留持管道孙进程,最后的 gather 也会挂起,两条路径都需要有界等待。

输出呈现:建议静默捕获而非实时流;失败时把尾部输出写入 WARNING 日志,并将最后一行附到用户消息;成功时尾部写 DEBUG;超时时报告超时及最后一行捕获内容。output_tail 会归一化 、去空行、取末尾 N 行。管道子进程的 stdout 为块缓冲,进度输出可能滞留在子进程缓冲中,被 kill 后丢失,自写探针脚本应使用 print(..., flush=True)。

测试替身:假的 StreamReader.read() 必须返回一次数据后返回 b"",否则消费循环会死循环并饿死事件循环;假的 wait() 需含 await asyncio.sleep(0) 让出循环。单元测试伪造 runner,平台层用真实进程覆盖。

限制与未处理项:进程树终止是 psutil ppid 快照,快照之后派生的子进程会逃逸,软杀后幸存者会被重新挂到别处;Windows 无 race 的方案是 Job Objects。macOS 无 CI 分支,按与 Linux 相同 POSIX 语义假设。stdout 与 stderr 默认分开捕获,可用 merge_stderr 合并;不支持向 UI 实时流式进度;取消 reader 后孤儿继续写入被弃管道假定无害但未验证。文档自述为工作备忘而非指南,部分 asyncio 内部行为与版本相关。