开发工具【免费下载链接】shPython process launching项目地址https://gitcode.com/gh_mirrors/sh/sh点击查看免费下载sh是一个以「调用系统命令就像调用普通 Python 函数一样自然」为设计目标的进程启动库项目名sh描述为Python process launching。本篇指南以官方参考文档docs/source/reference.rst为主体骨架完整梳理 sh 的三大核心类Command、RunningCommand、OProc、异常体系与辅助函数并逐项解析全部特殊关键字参数special kwargs。读完本篇你将掌握 sh 命令对象如何构造与烘焙bake、进程如何被 fork/exec 启动与收尾、如何用_out/_err/_tee/_iter等参数精细控制输入输出以及如何借助_ok_code/_timeout/_done处理退出码、超时与回调最终能够写出可复用的真实进程调用代码。一、Command 类代表一个可执行的程序1.1 核心职责Command类表示系统上存在、可以在某个时刻被运行的程序。一个Command实例本身永远不处于运行状态——真正被启动的是RunningCommand实例底层再包装OProc。这一点对应源码注释的描述RunningCommand是「an executing Command object」而Command只是可执行命令的惰性句柄见 src/sh/init.py。Command实例有两种构造方式手动实例化或通过动态属性查找自动构造import sh ls1 sh.Command(ls) ls2 sh.ls assert ls1 ls2sh.ls之所以可用是因为Command.__getattribute__在属性名不以_开头、且不是bake等保留名时会调用self.bake(name)动态创建一个新的命令对象src/sh/init.py。这也解释了 sh 最经典的「把命令当作函数调用」的语法。1.2 构造参数Command(name, search_pathsNone)name程序在$PATH中的名称或一个完整路径。search_paths可选指定查找程序时要搜索的路径列表默认使用$PATH。from sh import Command ifconfig Command(ifconfig) ifconfig Command(/sbin/ifconfig)底层通过_which(path, search_paths)完成查找找不到可执行文件、无执行权限或文件不可执行时直接抛出CommandNotFound(path)异常见Command.__init__src/sh/init.py。1.3 一个常见陷阱路径与参数必须分开sh.Command的参数必须是单独的程序名不能把整条命令行塞进去# 错误会抛出 CommandNotFound 异常即使给了正确的完整路径 lscmd sh.Command(/bin/ls -l) tarcmd sh.Command(/bin/tar cvf /tmp/test.tar /my/home/directory/)正确做法是两步只用二进制路径构建Command对象在调用时传入参数。lscmd sh.Command(/bin/ls) lscmd(-l) tarcmd sh.Command(/bin/tar) tarcmd(cvf, /tmp/test.tar, /my/home/directory/)1.4 bake()烘焙部分应用参数Command.bake(*args, **kwargs)返回一个新的Command把*args与**kwargs作为默认参数「烘焙」进去之后每次调用返回的 Command 都会自动带上这些参数from sh import ls long_ls ls.bake(-l) print(ls(/var)) # 实际执行 ls -l /var print(ls(/tmp)) # 实际执行 ls -l /tmp从源码看bake会复制自身、累积_partial_call_args特殊关键字参数与_partial_baked_args参数层编译成最终 argv 的动作被推迟到__call__/__str__时执行并且支持多层 bake 中布尔参数的覆盖语义后层keyFalse会抑制前层的keyTrue见 src/sh/init.py。bake 的更多实战用法参见 docs/source/sections/baking.rst。二、RunningCommand 类正在执行的命令2.1 概念与获取方式RunningCommand表示一个「正在或已经被执行」的Command实例它是OProc底层进程包装之上的门面也是用户与 sh 对象交互最多的类。只有当你以_return_cmdTrue执行命令时它才会被返回否则 sh 可能直接返回纯字符串输出。需要特别注意的是RunningCommand的实例表现得非常像字符串这是刻意的设计目的是让「命令输出」用起来更直观。但要警惕只接受真正str的函数例如json.dumps无法直接作用于RunningCommand即使它看起来像字符串。2.2 核心方法wait(timeoutNone) 与退出码异常wait()阻塞等待命令结束并取得退出码若退出码代表失败则抛出相应异常。它被 sh 自动调用除非命令以_bgTrue异步执行——那时你可能需要手动调用它来确保完成。timeout是非负秒数超时则抛出TimeoutException。两个细节值得注意多次调用wait()只有第一次会抛异常当Command实例被用作另一命令的 stdin即管道场景见 docs/source/sections/piping.rst时wait()也会被调用于该实例其异常会被向上传播。p sh.sleep(10, _bgTrue) try: p.wait(timeout1) except sh.TimeoutException: print(we timed out waiting) p.kill()signal 系列signal(sig_num)向进程发送信号通常配合signal模块使用如signal.SIGHUP。signal_group(sig_num)向进程组内每个进程发送信号。terminate()signal(SIGTERM)的快捷方式。kill()signal(SIGKILL)的快捷方式。kill_group()signal_group(SIGKILL)的快捷方式。is_alive()返回进程是否仍然存活bool。这些方法在 src/sh/init.py 中通过_OProc_attr_allowlist白名单直接透传到底层OProcsrc/sh/init.py。2.3 核心属性process底层OProc实例。stdoutproperty先调用wait()再返回进程写入 STDOUT 的内容。stderrproperty先调用wait()再返回 STDERR 内容。exit_codeproperty先调用wait()再返回进程退出码。pid进程 ID。sid进程会话 ID。除非指定_new_sessionFalse否则通常与当前 Python 进程的会话不同。pgid进程组 ID。ctty控制终端设备如果存在。三、OProc 类底层进程包装OProc是RunningCommand之下的底层实现官方文档明确警告不要直接使用它的实例此处记录它仅为了存档说明。wait()阻塞至进程完成聚合输出并填充exit_code。stdout/stderrcollections.deque容量由_internal_bufsize决定存放进程的 STDOUT/STDERR 内容。exit_code进程退出码进程未退出时为None。pid/sid/pgid/ctty进程 ID、会话 ID、进程组 ID、控制终端。signal(sig_num)/signal_group(sig_num)/terminate()/kill()/kill_group()与RunningCommand同名方法同义。OProc内部持有两个线程一个负责 STDIN一个负责 STDOUT 与 STDERR详见下文「架构总览」。四、异常体系4.1 ErrorReturnCode所有「返回码异常」的基类继承自Exception。它有四个实用属性full_cmd完整执行命令字符串可直接复制到命令行验证。stdout进程聚合后的完整 STDOUT。stderr进程聚合后的完整 STDERR。exit_code进程调整后的退出码进程被信号终止时为其负值如 SIGKILL → -9。源码中ErrorReturnCode还配有一个元类ErrorReturnCodeMeta按退出码动态生成ErrorReturnCode_0、ErrorReturnCode_1……等具体子类见 src/sh/init.py 与类型标注 src/sh/init.pyi因此你在except中既可以写sh.ErrorReturnCode也可以精确到sh.ErrorReturnCode_2。4.2 SignalException继承ErrorReturnCode。当命令因收到信号而退出时抛出例如进程被kill。4.3 TimeoutException以下两种情况抛出命令指定了非空_timeout且超时import sh try: sh.sleep(10, _timeout1) except sh.TimeoutException: print(we timed out, as expected)给RunningCommand.wait(timeout...)指定了超时见上文示例。4.4 CommandNotFound在以下任一条件成立时抛出程序在$PATH中找不到没有执行该程序的权限程序未被标记为可执行。后两条初看奇怪但完全符合 Bash 查找可执行程序的真实行为。注意CommandNotFound继承自AttributeError因此它的repr就是缺失属性的名字本身。五、辅助函数5.1 which(name, search_pathsNone)把name解析为程序的绝对路径找不到时返回None。search_paths提供时按该列表查找否则使用环境变量$PATH。5.2 pushd(directory)提供与 Bashpushd行为类似的with上下文进入指定目录上下文结束时自动弹出import sh with sh.pushd(/tmp): sh.touch(a_file)实现上使用可重入锁reentrant lock因此多线程在不同with上下文内各自切换目录时行为是正确的。六、特殊关键字参数Special Kwargs完整参考特殊关键字参数用于改变命令行为不会传给被调用的程序。它们可用在任何命令上但部分不能组合使用——sh 会主动检测冲突并报错。若要为每一个命令运行都设置默认特殊参数请使用default_arguments见 docs/source/sections/default_arguments.rst。在源码中这些参数的默认值集中定义在Command._call_args字典src/sh/init.py并在_extract_call_args中以_前缀从 kwargs 中抽取、剥离再经_kwarg_validators校验合法性src/sh/init.py。下面的默认值即来自该字典少数与文档中标注的略有出入处以源码实际值为准例如_tty_size源码默认(24, 80)。6.1 控制输出Controlling Output_out默认None指定 STDOUT 的重定向目标。可以是字符串 → 视为文件名文件对象或类文件对象整数 → 文件描述符如os.pipe()的返回值io.StringIO对象可调用对象callable。import sh sh.ls(_out/tmp/output)_err默认None指定 STDERR 的重定向目标用法同_out。_err_to_out默认False若为True把绑定到进程 STDOUT 的文件描述符同时复制到 STDERR使 STDERR 与 STDOUT 输出到同一处。_encoding默认sh.DEFAULT_ENCODING进程 STDOUT 的字符编码。默认是 locale 的默认编码源码中定义为DEFAULT_ENCODING getpreferredencoding() or UTF-8src/sh/init.py。_decode_errors默认strict1.07.0 新增Python 如何处理进程输出的解码错误。默认strict可改为任何bytes.decode支持的值如ignore。_tee默认None1.07.0 新增自 1.07.0 起只要对 STDOUT 或 STDERR 使用了重定向sh 内部对应缓冲区就不会再被填充例如下载文件时用回调处理 STDOUT内部 STDOUT 缓冲与管道缓冲都不会存数据。_tee强制其中一个流仍然被填充相当于把输出「分叉」到两处回调/重定向目标 内部缓冲区。取值_teeerr强制填 STDERR_teeout或_teeTrue强制填 STDOUT。源码中注释形象地称之为「as if the output is being Td to both」src/sh/init.py。_truncate_exc默认True1.12.0 新增异常输出是否截断。6.2 执行控制Execution_fg默认False1.12.0 新增以前台模式运行命令使用os.spawnle()派生当前进程的 STDIN/OUT/ERR 被os.dup2()到新进程使新进程成为执行脚本 shell 的前台。仅在你需要启动一个精简、交互式、sh 难以处理的进程时有用例如ssh。⚠️ 警告_fgTrue会绕过 sh 的大量功能——你不会得到进程对象且大部分很可能全部其他特殊 kwargs 都不生效。若想保留 sh 特性又获得类似效果请用import sh import sys sh.your_command(_insys.stdin, _outsys.stdout, _errsys.stderr)_bg默认False后台运行命令。命令立即返回你必须调用RunningCommand.wait()确保其终止参见 docs/source/sections/asynchronous_execution.rst。_bg_exc默认True1.12.9 新增是否自动报告后台命令的异常。若设为False务必自行调用wait()否则后台命令中发生的异常可能被吞掉。_async默认False2.0.0 新增使命令变得可 await。配合_iterTrue与async for可以增量地 await 输出。测试用例test_async展示了await python(py.name, _asyncTrue)在事件循环中的用法tests/sh_test.py。_env默认None一个字典定义进程唯一能访问的环境变量。若不指定则继承调用进程的环境。注意这个字典是进程环境的权威来源。如果你只想修改当前环境中的单个变量必须把「当前环境副本 覆盖后的变量」一起传给 sh参见 docs/source/sections/envs.rst。_timeout默认None给予进程完成的时间秒。超时后向进程发送_timeout_signal定义的信号。_timeout_signal默认signal.SIGKILL当_timeout非空时超时向进程发送的信号。_cwd默认None设置进程当前工作目录的字符串。_ok_code默认0整数、列表或元组包含被视为「正常」不抛异常的退出码。有些行为怪异的程序用非 0 退出码表示成功import sh sh.weird_program(_ok_code[0, 3, 5])如果进程被信号杀死默认会抛出SignalException。要屏蔽此行为可在_ok_code中追加代表该信号的负数import sh # SIGINT、SIGKILL、SIGTERM 杀掉进程时不会抛 SignalException p sh.sleep(3, _bgTrue, _ok_code[0, -2, -9, -15]) # 这里不会抛异常 p.kill()源码中_ok_code会先被规范化为列表None回退为[0]再与ErrorReturnCodeMeta的动态子类机制配合使用src/sh/init.py。测试test_ok_code系列验证了整数、列表、range与异常路径的行为tests/sh_test.py。更多细节见 docs/source/sections/exit_codes.rst。_new_session默认False2.0.0 起默认值由True改为False决定 fork 出的进程是否通过os.setsid()成为独立会话。2.0.0 修改默认值的原因让被启动进程默认待在 Python 脚本的进程组中从而正确接收 SIGINT。_new_group默认False决定 fork 出的进程是否通过os.setpgid()成为独立进程组。_uid默认None1.12.0 新增在子进程调用os.execv前假设的用户 ID。需要 root 权限且不支持 Windows。_preexec_fn默认None1.12.0 新增在子进程调用os.execv前运行的函数。普通用户通常不会使用。_pass_fds默认空集合{}1.13.0 新增一个白名单可迭代对象其中的整型文件描述符将被子进程继承。传入任何值都会导致_close_fdsTrue。_close_fds默认True1.13.0 新增关闭除 stdin、stdout、stderr 之外所有被继承的文件描述符。传入_pass_fds时会自动启用。注意这两个参数不能同时显式设置校验器会报Passing pass_fds forces close_fds to be Truesrc/sh/init.py。6.3 通信控制Communication_in默认None指定进程的标准输入。可以是字符串、queue.Queue、类文件对象或任意可迭代对象参见 docs/source/sections/stdin.rst。_piped默认None取值可为True、out或err。表示该命令正被用作另一命令的输入因此应增量地返回输出而不是一次性聚合参见 docs/source/sections/piping.rst。_iter默认None取值可为True、out或err。使命令进入可迭代模式可以用for/while循环实时遍历输出import sh for line in sh.cat(/tmp/file, _iterTrue): print(line)_iter_noblock默认None与_iter相同但循环在没有输出时不阻塞而是返回errno.EWOULDBLOCKimport sh import errno import time for line in sh.tail(-f, stuff.log, _iter_noblockTrue): if line errno.EWOULDBLOCK: print(doing something else...) time.sleep(0.5) else: print(processing line!)注意_piped与_iter不能同时使用校验器会报You cannot iterate when this command is being piped。_with默认False显式告知 sh 正在with上下文中运行命令。只有当你在with上下文且同时传参时才需要它import sh with sh.contrib.sudo(passwordabc123, _withTrue): print(sh.ls(/root))关于with上下文详见 docs/source/sections/with.rst。_done默认None1.11.0 新增命令完成时必定被调用的回调——即使退出码本应抛异常也会先调用它回调运行完毕后原本要抛的异常照常抛出。回调接收三个参数RunningCommand实例、表示成功的布尔值、退出码。官方示例展示了用它实现「最多 10 个并发」的多进程池import sh from threading import Semaphore pool Semaphore(10) def done(cmd, success, exit_code): pool.release() def do_thing(arg): pool.acquire() return sh.your_parallel_command(arg, _bgTrue, _donedone) procs [] for arg in range(100): procs.append(do_thing(arg)) # essentially a join [p.wait() for p in procs]完整示例见 docs/source/examples/done.rst。6.4 TTY 控制_tty_in默认False即使用os.pipe若为Truesh 为 STDIN 创建一个 TTY相当于模拟终端——就像命令从命令行输入一样。对「要求 STDIN 必须是 TTY」的命令必不可少。_tty_out默认True若为Truesh 为 STDOUT 创建 TTY否则使用os.pipe。对「要求 STDOUT 是 TTY」的命令必要如带颜色的输出相关 FAQ 见 docs/source/sections/faq.rst 中faq_tty_out。_unify_ttys默认False1.13.0 新增若为Truesh 将 STDOUT 与 STDIN 的 TTY 合并为单一伪终端。某些挑剔的程序如 SSH期望面对单个伪终端时必需。_tty_size默认(20, 80)源码实际默认(24, 80)STDOUT TTY 的行, 列尺寸。改变它可能影响程序每行打印多少内容。6.5 性能与优化Performance Optimization_in_bufsize默认0STDIN 缓冲区大小0无缓冲1行缓冲其他数值为对应大小的缓冲。_out_bufsize默认1STDOUT 缓冲区大小取值语义同上。_err_bufsize默认1同_out_bufsize作用于 STDERR。_internal_bufsize默认3 * 1024**2个块命令内部存储 STDOUT/ERR 的量。这个值表示缓冲区块数不是总字节数例如值设为 100 且 STDOUT 行缓冲时可取出 100 行STDOUT 无缓冲时只能取出 100 个字符。源码注释也强调这是 CHUNK 数而非 BYTE 数使用deque溢出时最先的条目被挤出src/sh/init.py。_no_out默认False1.07.0 新增禁用 STDOUT 的内部存储。适合命令产生海量而你不需要的输出——避免这些数据占用 sh 内部内存。_no_err默认False1.07.0 新增禁用 STDERR 的内部存储用途同上。_no_pipe默认False1.07.0 新增类似_no_out显式告知 sh 该命令永远不会被用于管道输出因此不必用内部输出填满其管道缓冲——同样用于节约内存。注意_piped与_no_pipe冲突校验器会报Using a pipe doesnt make sense if youve disabled the pipe。6.6 程序参数Program Arguments这些参数影响命令选项如何被喂给程序。_long_sep默认1.12.0 新增分隔「程序长参数名」与「值」的字符。例如程序期望--name value形式时设_long_sep import sh sh.your_program(keyvalue, _long_sep )将向程序发送[--key value]。若程序期望长参数名与值完全分开传Noneimport sh sh.your_program(keyvalue, _long_sepNone)将发送[--key, value]。_long_prefix默认--1.12.0 新增长参数的前缀字符。有些程序使用单横线且不理解双横线此时可改为-。_arg_preprocess默认None1.12.0 新增高级选项允许基于其他命令参数或变量在运行时重写命令参数。它通常只在配合bakedocs/source/sections/baking.rst时有用目前仅用于构造contrib包装器docs/source/sections/contrib.rstimport sh def processor(args, kwargs): return args, kwargs my_ls sh.bake.ls(_arg_preprocessprocessor)⚠️ 警告_arg_preprocess的函数接口可能随时变动仅限 sh 内部使用非必要不要使用。6.7 其他Misc_log_msg默认None1.12.0 新增自定义Command实例的日志头。默认日志形如import logging import sh logging.basicConfig(levellogging.INFO) sh.ls(-l)INFO:sh.command:Command /bin/ls -l: starting process INFO:sh.command:Command /bin/ls -l, pid 28952: process started INFO:sh.command:Command /bin/ls -l, pid 28952: process completed如果你觉得Command ..段冗长可用_log_msg自定义import logging import sh logging.basicConfig(levellogging.INFO) def custom_log(ran, call_args, pidNone): return ran sh.ls(-l, _log_msgcustom_log)INFO:sh.command:/bin/ls -l: starting process INFO:sh.command:/bin/ls -l: process started INFO:sh.command:/bin/ls -l: process completed回调参数含义ran程序的执行串与参数尽可能接近你在 shell 中输入的样子call_args传给命令的所有特殊 kwargs 的字典pidfork 后进程的 PID默认None——因为_log_msg回调实际上被调用两次第一次在进程 spawn 前构造RunningCommand实例的 logger第二次在进程 spawn 后此时才有 pid。七、架构总览进程如何被启动与收尾docs/source/sections/architecture.rst详细描述了 sh 的进程生命周期理解它能让你更从容地使用上述特殊参数。7.1 启动Launch启动一个进程时打开 STDIN/OUT/ERR 的管道和/或 TTY打开一条用于从子进程向父进程传递 pre-exec 异常的管道打开一条子/父进程启动同步管道os.fork()出子进程。此后存在两个并发进程子进程若_bgTrue忽略SIGHUP若_new_sessionTrue用os.setsid()成为会话首进程否则用os.setpgrp()成为进程组首进程将会话 ID 写入连接父进程的管道用于同步会话/组逻辑完成os.dup2()将之前设置好的 TTY/管道 fd 映射到 STDIN/OUT/ERR若是会话首进程且 STDIN 是 TTY_tty_inTrue获取控制终端成为会话的控制进程若设置了自定义_uid设置 GID/UID关闭所有大于 STDERR 的文件描述符调用os.execv。父进程通过异常管道检查子进程是否报告异常阻塞读取子进程的会话 ID同步确认子进程已完成会话/组切换从而能准确获取其 sid 与 pgid若使用 TTY 作为 STDIN_tty_inTrue关闭 TTY 的回显使发往 STDIN 的数据不被回显到 STDOUT。7.2 运行RunningOProc实例持有两个内部线程一个负责 STDIN一个负责 STDOUT 与 STDERR。STDOUT/ERR 线程持续对连接到 STDOUT/ERR 的 TTY/管道 master 端执行select.select一旦可读就读出数据并聚合到相应位置。7.3 缓冲Buffers理解 sh 的数据流需要区分两类缓冲底层管道/TTY 缓冲STDOUT/ERR 所连管道或 TTY 自身的缓冲。TTY默认输出缓冲为 0输出即时——进程写一个字节sh 收到一个字节管道缓冲则通常为 4–64KB参见pipe(2)。sh 内部缓冲STDOUT、STDERR 各一个。数据从 TTY/管道 master 端读出后、被送往对应输出处理器队列、文件对象、函数等之前暂存于此。直到达到_internal_bufsize指定的大小缓冲才冲刷到输出处理器。7.4 退出ExitSTDIN 线程关闭进程结束后内部线程必须结束因为 STDIN 读端连接进程已关闭再向写端写入将失败。STDOUT/ERR 线程关闭略复杂——进程虽已退出但管道/TTY 缓冲中可能仍有数据待收集。因此线程继续select.select读端直到读不到数据表示结束才退出读循环。退出码处理从被回收的进程取得退出码。若进程因信号终止退出码为该信号的负值——例如 SIGKILL 对应退出码 -9这与_ok_code支持负数、ErrorReturnCode.exit_code的语义一致。Done 回调若指定了_done回调会以RunningCommand实例、成功布尔值、调整后退出码执行回调返回后错误处理继续。也就是说_done无论成败都会被调用且它无法阻止后续ErrorReturnCode异常的抛出。八、速查与延伸阅读特殊参数总表定义见 src/sh/init.pyCommand._call_args校验规则见同文件 src/sh/init.py。参数编译compile_args/_aggregate_keywords在 src/sh/init.py它决定sh.ls(-l, /tmp, colornever)如何变成[-l, /tmp, --colornever]。类型标注可参考 src/sh/init.pyi其中ErrorReturnCode_0至ErrorReturnCode_15等动态异常子类均有声明。相关主题文档退出码 docs/source/sections/exit_codes.rst、重定向 docs/source/sections/redirection.rst、异步执行 docs/source/sections/asynchronous_execution.rst、管道 docs/source/sections/piping.rst、子命令 docs/source/sections/subcommands.rst、环境变量 docs/source/sections/envs.rst、with上下文 docs/source/sections/with.rst。赞分享开发工具【免费下载链接】shPython process launching项目地址https://gitcode.com/gh_mirrors/sh/sh点击查看免费下载相关推荐Swarms 框架 SpreadSheetSwarm 实战指南用 CSV 驱动多智能体并发任务编排与结果落盘Swarms 框架 SpreadSheetSwarm 实战指南用 CSV 驱动多智能体并发任务编排与结果落盘 本文以 swarms 仓库中的 spreadsh开发工具3分钟掌握Java密钥库导入技巧告别繁琐的手动操作3分钟掌握Java密钥库导入技巧告别繁琐的手动操作 你是否曾为Java密钥库管理而头疼想象一下这样的场景你拿到了一个Android平台的私钥和证书文件需open_clip API完全参考函数与参数详解open_clip API完全参考函数与参数详解 1. 核心模型构建接口 1.1 create_model模型实例化主入口 python def creat人工智能深度学习多模态预训练计算机视觉NLP基础模型上一篇pumpkin-book异常检测异常检测公式推导解析下一篇终极指南llm.c中Transformer架构的CUDA实现详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考