python-subprocess2 2.0.2

python-subprocess2

对python subprocess模块的扩展。导入subprocess2将扩展全局“subprocess”模块（只有添加，没有修改，因此是安全的）。

您也可以导入并使用subprocess2而不是subprocess模块。进行全局扩展允许您的应用程序或库利用这些扩展，而无需修改其他代码库。例如，如果您有一个库正在打开管道并将其传递给您的应用程序，则无需修改即可使用接收到的对象上的附加Popen方法。

仅安装subprocess2模块不会对父subprocess模块产生影响，直到它被导入，然后仅添加。

Popen

Popen类的扩展

waitUpTo

此方法增加了在等待子进程完成时指定超时的时间的能力。

Popen.waitUpTo (timeoutSeconds, pollInterval) - 等待一定数量的秒数以使进程结束。

@param timeoutSeconds <float> - 要等待的秒数

@param pollInterval <float> (默认 .05) - 每次轮询之间的秒数

@return - 应用程序的返回码，或者如果没有终止则为 None。

waitOrTerminate

此方法允许指定超时，类似于 waitUpTo，但还会在超时时终止或杀死应用程序（请参阅以下文档）。

Popen.waitOrTerminate(self, timeoutSeconds, pollInterval=DEFAULT_POLL_INTERVAL, terminateToKillSeconds=SUBPROCESS2_DEFAULT_TERMINATE_TO_KILL_SECONDS)

‘’’

waitOrTerminate - 等待一定数量的秒数以使进程结束。

如果进程在超时后仍在运行，则将发送 SIGTERM。

可选地，在某个可配置的时间间隔后可以发送额外的 SIGKILL。请参阅下面的 #terminateToKillSeconds 文档。

@param timeoutSeconds <float> - 要等待的秒数

@param pollInterval <float> (默认 .05)- 每次轮询之间的秒数

@param terminateToKillSeconds <float/None> (默认 1.5) - 如果应用程序在 #timeoutSeconds 之前没有结束，则将调用 terminate()。

• 如果将其设置为 None，则在调用 .terminate 之后将发生额外的 #pollInterval 睡眠，以允许应用程序进行清理。如果应用程序已完成，则返回码为应用程序的返回码，如果没有完成，则返回 None。

• 如果将其设置为 0，则不会发送终止信号，而是直接杀死。因为应用程序不能捕获此信号，所以返回码将为 None。

• 如果将其设置为 > 0，则在 .terminate 和 .kill 之间最多给出该数量的秒数。如果应用程序在 KILL 之前没有终止，则返回码将为 None。

Windows 注意 - 在 Windows 上 SIGTERM 和 SIGKILL 是同一件事。

@return dict { ‘returnCode’ : <int or None> , ‘actionTaken’ : <int mask of SUBPROCESS2_PROCESS_*> }

返回表示结果的字典

“returnCode” 与应用程序的返回码匹配，或根据上述 #terminateToKillSeconds 文档中的 None。

“actionTaken” 是 SUBPROCESS2_PROCESS_* 变量的掩码。如果应用程序正常完成，它将是 SUBPROCESS2_PROCESS_COMPLETED，否则将是一些 SUBPROCESS2_PROCESS_TERMINATED 和/或 SUBPROCESS2_PROCESS_KILLED 的掩码

‘’’

后台任务管理

现代计算的一个好处是能够多任务处理。您的应用程序可能希望同时启动几个子进程，并让它们同时收集输出。标准的 python “subprocess” 模块不通过它的 API 提供简单的做法来实现这一点。

subprocess2 通过添加“后台任务”的概念扩展了 Popen 模块。当您在一个管道对象上调用“runInBackground”时，它将创建并启动一个线程来自动处理该进程。

在管道上调用“runInBackground”将返回一个“BackgroundTaskInfo”选项，该选项将根据子进程的状态动态更新。

如果打开流（stdout、stderr），它们将自动以非阻塞方式分别读取到该对象的“stdoutData”和“stderrData”。

当子进程终止时，将设置“returnCode”字段，并将“isFinished”标记为 True。

默认情况下，数据将存储为字节。要使用特定的编码解码（例如 utf-8），请将编码名称作为“encoding”参数传递。

您可以使用此功能快速分配10个进程，收集它们的所有数据，并等待它们完成。其他用途可能包括长时间运行的关联进程，例如几个搜索收集数据，所有这些都被用于更新显示。

方法签名

def runInBackground(self, pollInterval=.1, encoding=False)

‘’’

runInBackground - 创建一个后台线程来管理此进程，自动从流中读取数据，并执行任何清理操作

返回的对象是一个“BackgroundTaskInfo”对象，表示进程的状态。它在程序运行时自动更新，

如果stdout或stderr是流，它们将自动从流中读取并填充到这个对象中。

@see BackgroundTaskInfo 以获取更多信息或 https://htmlpreview.github.io/?https://raw.githubusercontent.com/kata198/python-subprocess2/master/doc/subprocess2.BackgroundTask.html

@param pollInterval - 轮询之间的空闲时间

@param encoding - 默认为False。如果提供，则使用此字段的值作为编解码器名称来解码数据（例如，“utf-8”）。否则，数据将作为字节存储。

‘’’

返回的对象

class BackgroundTaskInfo(object)

‘’’

BackgroundTaskInfo - 表示已发送到后台运行的任务。将随着该进程状态的改变而更新。

可以像对象或字典一样使用。

此对象在后台程序运行时自动填充其数据，由线程管理。

字段

stdoutData - 如果stdout是管道，则自动从stdout读取的字节，如果stderr设置为subprocess.STDOUT，则从stderr读取

stderrData - 如果与stdout不同的管道，则自动从stderr读取的字节

isFinished - 当后台应用程序正在运行时为False，完成时为True

returnCode - 如果程序尚未完成，则为None，否则返回数值返回码

timeElapsed - 自上次更新以来经过的秒数（更新发生在调用runInBackground时提供的“pollInterval”非常接近时）

‘’’

例如

import subprocess2 as subprocess

pipe1 = subprocess.Popen(……, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

pipe2 = subprocess.Popen(……, stdout=subprocess.PIPE)

pipe1Info = pipe1.runInBackground()

pipe2Info = pipe2.runInBackground()

将有两个后台进程运行，自动收集它们的输出，并自动清理。

如果您稍后决定等待直到某个管道完成，您可以通过在BackgroundTaskInfo上调用“waitToFinish”将它们拉回前台（同时保持流的自动填充），以阻塞当前上下文。

def waitToFinish(self, timeout=None, pollInterval=.1)

‘’’

waitToFinish - 以可选的超时时间等待，直到后台任务完成。

@param timeout <None/float> - None为无限期等待，否则为最大等待秒数

@param pollInterval <float> - 每次轮询之间的秒数。如果交互性不重要，则保持较高，如果重要则保持较低。

@return - 如果进程未完成（并且发生超时），则返回None，否则返回进程的返回码。

‘’’

因此，继续上面的例子

pipe1Info = pipe1.runInBackground()

……艰难的工作……

sys.stdout.write(‘当前输出: ‘ + pipe1Info.stdoutData.decode(‘utf-8’))

……更多艰难的工作……

returnCode = pipe1Info.waitToFinish()