命令执行

命令执行提供了在本机执行相关命令的功能(如需在集群中执行命令请参考 命令执行(集群中)

函数原型

和命令执行相关的两个函数为 runexec,二者所接收的参数和返回值都是一样的,仅在行为有所不同。

  • exec 会将命令的执行结果输出到终端,并在出现异常(例如退出码非 0)时中断脚本执行
  • run 不会将命令的执行结果输出到终端,同时在出现异常时也不会中断脚本执行(可利用返回的 result.error 和 result.code 查看)

第一个参数:要执行的命令

run 接收的第一个参数为要执行的命令,这一命令支持传递一个 str list 或是一个字符串。如果传递的是 str list 的话会进行参数 join

命令的行为根据 参数 bash 的行为而有所不同,具体请参考 要执行的命令

参数 bash(默认为 True)

是否使用 bash (login shell),默认是打开的,在某些异常情况下可以关闭

具体效果请参考 将执行的命令

参数 timeout(默认为 60s)

需要特别注意,所有命令的 timeout 默认为 60s,因此对于一些会长期运行的程序请手动指定一个 timeout

timeout 指定的是超时时间,接收的为一个数字(代表秒数)或一个 time.Duration 对象

如果设定为 0 或负数可以关闭超时功能,但任何情况均不推荐该做法,一个更好的方式是将 timeout 设定为一个预计不可能达到的时间

timeout 参数支持传递 float 或 Duration 对象在 ambot-script engine v1.3 系中 v1.3.8 或更高版本、v1.4 系中 v1.4.0-rc.16 或更高版本引入

低版本仅支持传递整数作为超时秒数

参数 env(默认为空)

设定额外使用的环境变量,支持传递 List[str] 或 Dict[str, str] 类型

参数 merge(默认为 True)

是否将 stdout 和 stderr 合并至 stdout,默认打开(打开后 result.stdout 直接包含了 stderr 的内容,而 stderr 不会有返回值)

返回结果

exec 的返回值仅在 ambot-script engine v1.3 系中 v1.3.8 或更高版本、v1.4 系中 v1.4.0-rc.16 或更高版本才会返回

返回的类型为 subprocess.Result,其包括

error 错误 str/None

为进程的错误信息,一般只有在要调用的程序不存在时才会出现。在 exec 中只有 None 会被返回(有错误的会导致脚本直接被中断执行)

code 退出码 int

为进程的退出码,0 代表成功。在 exec 中只有 0 会被返回(非 0 退出码会导致脚本直接被中断执行)

stdout 标准输出内容 bytes

当调用参数 merge=False 时为进程的 stdout

当调用参数 merge=True 时(默认)为进程的 stdout+stderr

stderr 标准错误内容 bytes

当调用参数 merge=False 时为进程的 stderr

当调用参数 merge=True 时(默认)为空

高级功能

assert

对于 result 进行 assert 时等价于

assert(result.code==0, result.error == None)

将执行的命令

要执行的命令会受到 bash 参数的影响

  • 对于 bash=False 时
    • 传递的字符串会被 shlex.split 后执行
    • 传递的列表会被直接执行,列表的第一个参数为要执行的程序(如果不为路径则从 PATH 环境变量中搜索执行)
  • 对于 bash=True (默认)时
    • 传递的字符串会作为 ["bash", "-c", "<something>" ] 中的第三个参数
    • 传递的列表会被 shlex.join 后作为上述的第三个参数执行