runners¶
- class invoke.runners.Runner(context: Context)¶
部分抽象的核心命令运行API。
此类本身不可用，必须派生子类，实现许多方法，如
start，wait和returncode。有关子类实现示例，请参阅的源代码Local。在 1.0 版本加入.
- __init__(context: Context) None¶
创建一个新的流道，并在某些流道上添加句柄
Context。- 参数:
context -- 一个
Context实例，用于传输默认选项并提供对其他上下文信息的访问(例如，面向远程的Runner可能需要一个Context包含有关主机名和端口的信息的子类。)..注：：Context习惯于Runner实例 must 包含的默认配置值Runner有问题的班级。这至少意味着每个缺省值Runner.run关键字参数，如echo和warn。- 抛出:
exceptions.ValueError -- 如果不是所有预期的缺省值都在
context。
- program_finished¶
A
threading.Event信令程序完成。通常设置在
wait回归。一些IO机制依赖于此来知道何时退出无限读取循环。
- read_chunk_size = 1000¶
每次流读取迭代要读取的字节数(最大)。
- input_sleep = 0.01¶
在stdin读取循环和其他快速循环的每次迭代上休眠的秒数。
- warned_about_pty_fallback¶
是否已发出PTY回退警告。
- watchers: List['StreamWatcher']¶
一份名单
StreamWatcher供使用的实例respond。在运行时由run。
- run(command: str, **kwargs: Any) Result | None¶
执行
command，返回Result一旦完工。默认情况下，此方法是同步的(仅在子进程完成后才返回)，并允许与子进程进行交互式键盘通信。
它可以改为异步行为(提前返回并需要与结果对象交互以管理子流程生命周期)，如果指定
asynchronous=True。此外，您可以通过以下语句完全解除该子流程与Invoke的控制的关联(允许它在Python退出后自行保留)disown=True。有关这两种情况的详细信息，请参阅下面的每kwarg文档。备注
所有kwarg将默认为在此实例的
context属性，特别是在其配置的run子树(例如run.echo属性的默认值。echo关键字等)。基本默认值在下面的参数列表中描述。- 参数:
command (str) -- 要执行的Shell命令。
asynchronous (bool) -- 当设置为时
True(默认False)，启用异步行为，如下所示：-禁用与控制终端的连接，这意味着您将看不到子进程输出，并且它将不会响应您的键盘输入-类似于hide=True和in_stream=False(虽然明确给出(out|err|in)_stream类似文件的对象仍将被视为正常对象)。-run在启动子进程后立即返回，其返回值将成为Promise而不是Result。-Promise对象主要用于其join方法，该方法会一直阻塞，直到子进程退出(类似于线程化API)，然后返回最终的Result或引发异常，就像同步run会的。-与线程和类似的API一样，用户asynchronous=True应该确保join他们的Promise对象以防止解释器关闭问题。-处理此类清理的一种简单方法是使用Promise作为上下文管理器-它将自动join在上下文块的出口处。。。添加的版本：：1.4disown (bool) -- 当设置为时
True(默认False)，立即返回如下内容asynchronous=True，但不执行与该子进程相关的任何后台工作(它被完全忽略)。这允许使用Shell背景或类似技术(例如拖尾)的子过程&，nohup)，以在运行调用的Python流程的生命周期之后继续存在。。。注意：如果您不确定是要这个还是asynchronous，您可能想要asynchronous好了！具体来说，disown=True具有以下行为：-返回值为None而不是一个Result或者说子类。-没有启动I/O工作线程，因此您将无权访问子进程的stdout/stderr，您的stdin将不会被转发，(out|err|in)_stream将被忽略，并且诸如watchers将不起作用。-没有检查退出码，所以如果子进程无法干净地退出，您不会收到任何错误。-pty=True可能无法正常运行(子进程可能根本不运行；这似乎是Python中的潜在错误pty.fork)，除非您的命令行包含诸如nohup或者(内置Shell)disown。。。添加的版本：：1.4dry (bool) -- 是否进行模拟运行，而不是真正调用给定命令。看见
--dry(这会在全局范围内打开此功能)，以了解有关此行为的详细信息。。。版本添加：：1.3echo (bool) -- 控制是否
run在执行命令之前，将命令字符串打印到本地标准输出。默认：False。。。注：：hide=True将覆盖echo=True如果两个都给的话。echo_format -- 一个字符串，当传递给Python的内置
.format方法时，将更改输出的格式。run.echo设置为True。目前，只有{command}支持将其作为参数。默认以ANSI转义粗体打印完整的命令字符串。echo_stdin (bool) -- 是否将数据写入
in_stream返回到out_stream。换句话说，在正常的交互用法中，该参数控制Invoke是否将您键入的内容镜像回您的终端。默认情况下(当None)，此行为由以下因素触发： * Not using a pty to run the subcommand (i.e.pty=False), as ptys natively echo stdin to stdout on their own; * 并且当控制终端调用其自身时(根据in_stream)似乎是有效的终端设备或TTY。(具体而言，当isatty产生一种True给出结果时的结果in_stream.)..注意：：此属性倾向于False当通过管道将另一个程序的输出传输到调用会话中时，或者当在另一个程序中运行调用时(例如，从自身运行调用)。如果这两个属性都为True，则将发生回显；如果其中一个为False，则不会执行回显。什么时候不是None，则此参数将覆盖自动检测并强制或禁用回显。encoding (str) -- 覆盖子进程对其stdout/stderr流使用哪种编码的自动检测(默认为返回值
default_encoding)。err_stream -- 相同于
out_stream，除标准误差外，默认为sys.stderr。env (dict) -- 默认情况下，子流程接收Invoke自己的环境的副本(即
os.environ)。在这里提供一个字典来更新子环境。例如,run('command', env={'PYTHONPATH': '/some/virtual/env/maybe'})将修改PYTHONPATHEnv var，而子环境的其余部分看起来与父环境相同。。。另请参阅：：replace_env用于将‘UPDATE’更改为‘REPLACE’。fallback (bool) -- 控制自动回退行为重新：在以下情况下提供PTY时出现问题
pty=True。这是否有任何效果取决于具体的Runner正在调用的子类。默认：True。hide -- 允许调用方禁用
run将子进程的stdout和stderr复制到控制终端的默认行为。指定hide='out'(或'stdout')来仅隐藏标准输出流，hide='err'(或'stderr')仅隐藏stderr，或hide='both'(或True)以隐藏这两个流。缺省值为None，意思是打印所有内容；False还将禁用隐藏。。。注意：：stdout和stderr始终被捕获并存储在Result对象，而不管hide的值。..注：：hide=True还将重写echo=True如果两者都提供(作为kwargs或通过CONFIG/CLI)。in_stream -- 一个类似文件的流对象，用作子进程的标准输入。如果
None(默认设置)，sys.stdin将会被使用。如果False将完全禁用stdin镜像(尽管写入子进程的stdin的其他功能，如自动响应，仍将起作用)。在以下情况下，禁用标准输入镜像会有所帮助sys.stdin是行为不端的非流对象，例如被测试的线束或无头命令运行器。out_stream -- 子进程的标准输出应写入的类似文件的流对象。如果
None(默认设置)，sys.stdout将会被使用。pty (bool) -- 默认情况下，
run直接连接到被调用的进程并读取其stdout/stderr流。在这种情况下，与使用实际终端或伪终端(PTY)相比，一些程序将缓冲(甚至行为)不同。要使用PTY而不是默认行为，请指定pty=True。。。警告：由于pty的性质，pty只有一个输出流，因此区分stdout和stderr的能力是 not possible 什么时候pty=True。因此，所有输出都将显示在out_stream(见下文)，并被捕获到stdout结果属性。err_stream和stderr将始终为空，当pty=True。replace_env (bool) -- 什么时候
True，使子进程接收给定给env作为其整个Shell环境，而不是更新os.environ(这是默认行为)。默认：False。shell (str) -- 要使用的Shell二进制文件。默认：
/bin/bash(在Unix上；COMSPEC或cmd.exe在Windows上。)timeout -- 使运行程序向子进程提交中断并引发
CommandTimedOut，如果命令花费的时间超过timeout执行的秒数。默认为None，意味着不会超时。。。版本添加：：1.3warn (bool) -- 是否发出警告并继续，而不是引发
UnexpectedExit当执行的命令以非零状态退出时。默认：False。。。注意：此设置对异常没有影响，异常仍将被引发，通常捆绑在ThreadException对象(如果它们由IO辅助线程引发)。同样，WatcherError提出的例外情况StreamWatcher实例也将忽略此设置，并且通常捆绑在内部Failure对象(以便保留执行上下文)。同上CommandTimedOut-基本上，任何阻止命令实际进入“带退出代码退出”的操作都会忽略此标志。watchers -- 一份名单
StreamWatcher实例，这些实例将用于扫描程序stdout或stderr并可将其写入其stdin(通常bytes对象)以响应模式或其他试探法。看见 自动响应程序输出 有关此功能的详细信息，请参阅。默认：[]。
- 返回:
Result，或其子类。- 加薪:
UnexpectedExit，如果命令退出非零，并且warn曾经是False。- 加薪:
Failure，如果命令甚至没有干净地退出，例如，如果StreamWatcher已提高WatcherError。- 加薪:
ThreadException(如果后台I/O线程遇到除WatcherError)。
在 1.0 版本加入.
- create_io_threads() Tuple[Dict[Callable, ExceptionHandlingThread], List[str], List[str]]¶
创建并返回IO线程工作对象的字典。
调用方需要处理持久化和/或启动包装的线程。
- generate_result(**kwargs: Any) Result¶
创建并返回合适的
Result实例从给定的kwargs。子类可能希望重写它，以便操纵事物或生成
Result子类(例如，除了默认类之外还包含其他元数据的子类)。在 1.0 版本加入.
- read_proc_output(reader: Callable) Generator[str, None, None]¶
从子进程的OUT/ERR流中反复读取和解码字节。
- 参数:
reader -- 文字读取器函数/Partial，包装所讨论的实际流对象，它需要读取许多字节，并返回相同数量的字节(或
None)。reader应该是对任一项的引用read_proc_stdout或read_proc_stderr，它执行特定于平台/库的实际读取调用。- 返回:
产生弦的发电机。具体地说，每个结果字符串都是解码的结果
read_chunk_size从子进程的OUT/ERR流读取的字节数。
在 1.0 版本加入.
- write_our_output(stream: IO, string: str) None¶
写
string至stream。也可呼叫
.flush()在……上面stream以确保真正的终端流不会被缓冲。- 参数:
stream -- 一个类似文件的流对象，映射到
out_stream或err_stream的参数run。string -- Unicode字符串对象。
- 返回:
None。
在 1.0 版本加入.
- handle_stdout(buffer_: List[str], hide: bool, output: IO) None¶
读取进程的stdout，存储到缓冲区&打印/解析。
旨在用作线程目标。仅当子进程中的所有标准输出都已读取时才终止。
- 参数:
buffer -- 与主线程共享的捕获缓冲区。
hide (bool) -- 是否将数据重放到
output。output -- 不隐藏时要写入数据的输出流(类似文件的对象)。
- 返回:
None。
在 1.0 版本加入.
- handle_stderr(buffer_: List[str], hide: bool, output: IO) None¶
读取进程的stderr，存储到缓冲区&打印/解析。
等同于
handle_stdout除了从中读取的流；有关API的详细信息，请参阅其文档字符串。在 1.0 版本加入.
- read_our_stdin(input_: IO) str | None¶
从本地标准输入流中读取和解码字节。
- 参数:
input -- 要从中读取的实际流对象。映射到
in_stream在……里面run，通常也会是这样sys.stdin，但可以是任何类似流的对象。- 返回:
Unicode字符串，对读取的字节进行解码的结果(如果管道已关闭/到达EOF，则这可能是空字符串)；或
None如果标准输入还没有准备好阅读。
在 1.0 版本加入.
- handle_stdin(input_: IO, output: IO, echo: bool = False) None¶
读取本地标准输入，根据需要复制到进程的标准输入。
旨在用作线程目标。
备注
因为实际终端stdin流没有明确定义的“end”，所以如果检测到这样的流(基于可调用的
.fileno())此方法将等待直到program_finished已设置，然后终止。当流看起来不是来自终端时，与
handle_stdout-流只是简单地read()直到它返回空值。- 参数:
input -- 要从中读取的流(类似文件的对象)。
output -- 可能发生回显的流(类似文件的对象)。
echo (bool) -- 用于标准输入-标准输出回显的用户覆盖选项。
- 返回:
None。
在 1.0 版本加入.
- should_echo_stdin(input_: IO, output: IO) bool¶
确定数据是否从
input_应该回响到output。使用者
handle_stdin；测试以下对象的属性input_和output。- 参数:
input -- 输入流(类似文件的对象)。
output -- 输出流(类文件对象)。
- 返回:
A
bool。
在 1.0 版本加入.
- respond(buffer_: List[str]) None¶
中的模式写入程序的标准输入
buffer_。这些模式和响应是由
StreamWatcher实例中的watchers粗鲁的run-请参见 自动响应程序输出 了解概念性概述。- 参数:
buffer -- 此线程的特定IO流的捕获缓冲区。
- 返回:
None。
在 1.0 版本加入.
- generate_env(env: Dict[str, Any], replace_env: bool) Dict[str, Any]¶
根据用户输入和行为返回合适的环境字典。
- 参数:
env (dict) -- 提供覆盖或完整环境的字典，视情况而定。
replace_env (bool) -- 是否
env更新或用来代替的值os.environ。
- 返回:
Shell环境变量的词典。
在 1.0 版本加入.
- property has_dead_threads: bool¶
检测是否有任何IO线程似乎已意外终止。
在流程完成等待期间使用(传入
wait)以确保在IO处理线程出错/死亡时不会死锁我们的子进程。- 返回:
True如果任何线程似乎已因异常而终止，False否则的话。
在 1.0 版本加入.
- write_proc_stdin(data: str) None¶
写入编码
data到正在运行的进程的stdin。- 参数:
data -- Unicode字符串。
- 返回:
None。
在 1.0 版本加入.
- property process_is_finished: bool¶
确定我们的子进程是否已终止。
备注
此方法的实现应该是非阻塞的，因为它在查询/轮询循环中使用。
- 返回:
True如果子进程已完成运行，False否则的话。
在 1.0 版本加入.
- start(command: str, shell: str, env: Dict[str, Any]) None¶
启动执行
command(通过shell同env)。通常，这意味着使用分叉子进程或请求在远程系统上开始执行。
在大多数情况下，此方法还将设置在其他方法中使用的特定于子类的成员变量
wait和/或returncode。- 参数:
在 1.0 版本加入.
- read_proc_stdout(num_bytes: int) bytes | None¶
朗读
num_bytes来自正在运行的进程的stdout流。- 参数:
num_bytes (int) -- 最大要读取的字节数。
- 返回:
字符串/字节对象。
在 1.0 版本加入.
- read_proc_stderr(num_bytes: int) bytes | None¶
朗读
num_bytes来自正在运行的进程的stderr流。- 参数:
num_bytes (int) -- 最大要读取的字节数。
- 返回:
字符串/字节对象。
在 1.0 版本加入.
- send_interrupt(interrupt: KeyboardInterrupt) None¶
向正在运行的子进程提交中断信号。
在几乎所有实现中，默认行为都是所需的：提交
子进程的stdin管道。但是，我们将其保留为公共方法，以防需要增加或替换此默认值。- 参数:
interrupt -- 本地来源的
KeyboardInterrupt导致方法调用。- 返回:
None。
在 1.0 版本加入.
- returncode() int | None¶
返回命令执行产生的数字返回/退出代码。
- 返回:
int，如果可以确定任何合理的返回代码，或者None在这种情况下，这是不可能的。
在 1.0 版本加入.
- stop() None¶
如有必要，执行最终清理。
此方法在
finally子句中的子句run方法。根据子类的不同，它可能是无操作的，也可能执行关闭网络连接或打开文件等操作。- 返回:
None
在 1.0 版本加入.
- __weakref__¶
对象的弱引用列表
- class invoke.runners.Local(context: Context)¶
在子进程中的本地系统上执行命令。
备注
当在没有控制终端的情况下执行调用本身时(例如，当
sys.stdin缺乏一个有用的fileno)，则不可能将我们的PTY句柄呈现给本地子进程。在这种情况下，Local会退回到表现得好像pty=False(根据降级执行总比没有好的理论)，并向stderr打印一个警告。要禁用此行为，请执行以下操作
fallback=False。在 1.0 版本加入.
- __init__(context: Context) None¶
创建一个新的流道，并在某些流道上添加句柄
Context。- 参数:
context -- 一个
Context实例，用于传输默认选项并提供对其他上下文信息的访问(例如，面向远程的Runner可能需要一个Context包含有关主机名和端口的信息的子类。)..注：：Context习惯于Runner实例 must 包含的默认配置值Runner有问题的班级。这至少意味着每个缺省值Runner.run关键字参数，如echo和warn。- 抛出:
exceptions.ValueError -- 如果不是所有预期的缺省值都在
context。
- read_proc_stdout(num_bytes: int) bytes | None¶
朗读
num_bytes来自正在运行的进程的stdout流。- 参数:
num_bytes (int) -- 最大要读取的字节数。
- 返回:
字符串/字节对象。
在 1.0 版本加入.
- read_proc_stderr(num_bytes: int) bytes | None¶
朗读
num_bytes来自正在运行的进程的stderr流。- 参数:
num_bytes (int) -- 最大要读取的字节数。
- 返回:
字符串/字节对象。
在 1.0 版本加入.
- start(command: str, shell: str, env: Dict[str, Any]) None¶
启动执行
command(通过shell同env)。通常，这意味着使用分叉子进程或请求在远程系统上开始执行。
在大多数情况下，此方法还将设置在其他方法中使用的特定于子类的成员变量
wait和/或returncode。- 参数:
在 1.0 版本加入.
- property process_is_finished: bool¶
确定我们的子进程是否已终止。
备注
此方法的实现应该是非阻塞的，因为它在查询/轮询循环中使用。
- 返回:
True如果子进程已完成运行，False否则的话。
在 1.0 版本加入.
- class invoke.runners.Result(stdout: str = '', stderr: str = '', encoding: str | None = None, command: str = '', shell: str = '', env: Dict[str, Any] | None = None, exited: int = 0, pty: bool = False, hide: Tuple[str, ...] = ())¶
用于存储有关命令执行结果的信息的容器。
所有参数都公开为具有相同名称和类型的属性。
- 参数:
stdout (str) -- 子进程的标准输出。
stderr (str) -- 相同于
stdout但包含标准错误(除非流程是通过PTY调用的，在这种情况下，它将为空；请参见Runner.run。)encoding (str) -- 本地Shell环境使用的字符串编码。
command (str) -- 已执行的命令。
shell (str) -- 用于执行的Shell二进制文件。
env (dict) -- 用于执行的Shell环境。(缺省值为空词典，
{}，不是None如签名所示。)exited (int) -- 表示子进程的退出/返回代码的整数。。。注：：这可能是
None子进程未运行到完成的情况下，例如自动响应失败或到达超时时。pty (bool) -- 描述是否使用PTY调用子流程的布尔值；请参见
Runner.run。hide (tuple) -- 流名称的元组(无、一个或两个
('stdout', 'stderr'))，在执行生成命令时对用户隐藏；这是从hide的参数Runner.run。例如,run('command', hide='stdout')将产生一个Result哪里result.hide == ('stdout',)；hide=True或hide='both'在.中的结果result.hide == ('stdout', 'stderr')及hide=False(缺省设置)生成result.hide == ()(空元组。)
备注
Result对象的真实性评价等同于其ok属性的值。因此，可以使用类似以下内容的快捷表达式：if run("some shell command"): do_something() else: handle_problem()
然而，请记住 Zen of Python #2 。
在 1.0 版本加入.
- __init__(stdout: str = '', stderr: str = '', encoding: str | None = None, command: str = '', shell: str = '', env: Dict[str, Any] | None = None, exited: int = 0, pty: bool = False, hide: Tuple[str, ...] = ())¶
- __weakref__¶
对象的弱引用列表
- class invoke.runners.Promise(runner: Runner)¶
对未来的承诺
Result，是由异步执行产生的。此类的主要API成员为
join；实例也可以用作上下文管理器，它将自动调用join当数据块退出时。在这种情况下，上下文管理器产生self。Promise还公开了许多Result属性，特别是派生自run而不是命令执行的结果。例如,command是在这里复制的，但是stdout不是的。在 1.4 版本加入.
- join() Result¶
块，直到关联子进程退出，返回/引发结果。
它的作用与同步执行的
run，即：各种后台线程(例如IO工作线程)本身被联接；
如果子进程正常退出，则会引发
Result被退回；在任何其他情况下(不可预见的异常、IO子线程
ThreadException，Failure，WatcherError)此处提出了相关的例外情况。
看见
run文档或相关类的文档，以获取更多详细信息。