子进程 ¶

源代码： Lib/asyncio/subprocess.py , Lib/asyncio/base_subprocess.py

---

此节描述的高级 async/await asyncio API 能创建和管理子进程。

这里是 asyncio 如何运行 Shell 命令并获得其结果的范例：

import asyncio
async def run(cmd):
    proc = await asyncio.create_subprocess_shell(
        cmd,
        stdout=asyncio.subprocess.PIPE,
        stderr=asyncio.subprocess.PIPE)
    stdout, stderr = await proc.communicate()
    print(f'[{cmd!r} exited with {proc.returncode}]')
    if stdout:
        print(f'[stdout]\n{stdout.decode()}')
    if stderr:
        print(f'[stderr]\n{stderr.decode()}')
asyncio.run(run('ls /zzz'))
					

将打印：

['ls /zzz' exited with 1]
[stderr]
ls: /zzz: No such file or directory
					

因为所有 asyncio 子进程函数是异步的，且 asyncio 提供了许多操控这些函数的工具，平行执行和监视多个子进程，很容易。修改以上范例同时运行几个命令，的确没什么：

async def main():
    await asyncio.gather(
        run('ls /zzz'),
        run('sleep 1; echo "hello"'))
asyncio.run(main())
					

另请参阅 范例 小节。

创建子进程 ¶

协程 asyncio. create_subprocess_exec ( program , *args , stdin=None , stdout=None , stderr=None , loop=None , limit=None , **kwds ) ¶

创建子进程。

The limit 自变量设置缓冲限制为 StreamReader 包裹器对于 Process.stdout and Process.stderr (若 subprocess.PIPE 被传递给 stdout and stderr 自变量)。

返回 Process 实例。

见文档编制为 loop.subprocess_exec() 了解其它参数。

从 3.8 版起弃用，将在 3.10 版中移除： The loop 参数。

协程 asyncio. create_subprocess_shell ( cmd , stdin=None , stdout=None , stderr=None , loop=None , limit=None , **kwds ) ¶

运行 cmd Shell 命令。

The limit 自变量设置缓冲限制为 StreamReader 包裹器对于 Process.stdout and Process.stderr (若 subprocess.PIPE 被传递给 stdout and stderr 自变量)。

返回 Process 实例。

见文档编制为 loop.subprocess_shell() 了解其它参数。

重要

It is the application’s responsibility to ensure that all whitespace and special characters are quoted appropriately to avoid shell injection vulnerabilities. The shlex.quote() function can be used to properly escape whitespace and special shell characters in strings that are going to be used to construct shell commands.

从 3.8 版起弃用，将在 3.10 版中移除： The loop 参数。

注意

子进程可用于 Windows 若 ProactorEventLoop is used. See Windows 中的子进程支持 了解细节。

另请参阅

asyncio also has the following 低级 APIs to work with subprocesses: loop.subprocess_exec() , loop.subprocess_shell() , loop.connect_read_pipe() , loop.connect_write_pipe() , as well as the 子进程传输 and 子进程协议 .

常量 ¶

asyncio.subprocess. PIPE ¶

Can be passed to the stdin , stdout or stderr 参数。

若 PIPE 被传递给 stdin 自变量， Process.stdin 属性将指向 StreamWriter 实例。

若 PIPE 被传递给 stdout or stderr 自变量， Process.stdout and Process.stderr 属性将指向 StreamReader 实例。

asyncio.subprocess. STDOUT ¶

Special value that can be used as the stderr argument and indicates that standard error should be redirected into standard output.

asyncio.subprocess. DEVNULL ¶

Special value that can be used as the stdin , stdout or stderr argument to process creation functions. It indicates that the special file os.devnull will be used for the corresponding subprocess stream.

与子进程交互 ¶

Both create_subprocess_exec() and create_subprocess_shell() functions return instances of the Process 类。 Process is a high-level wrapper that allows communicating with subprocesses and watching for their completion.

class asyncio.subprocess. Process ¶

An object that wraps OS processes created by the create_subprocess_exec() and create_subprocess_shell() 函数。

This class is designed to have a similar API to the subprocess.Popen class, but there are some notable differences:

• unlike Popen, Process instances do not have an equivalent to the poll() 方法；

• the communicate() and wait() methods don’t have a timeout parameter: use the wait_for() 函数；

• the Process.wait() method is asynchronous, whereas subprocess.Popen.wait() method is implemented as a blocking busy loop;

• the universal_newlines parameter is not supported.

此类是 非线程安全 .

另请参阅 子进程和线程 章节。

协程 wait ( ) ¶

Wait for the child process to terminate.

设置并返回 returncode 属性。

注意

This method can deadlock when using stdout=PIPE or stderr=PIPE and the child process generates so much output that it blocks waiting for the OS pipe buffer to accept more data. Use the communicate() method when using pipes to avoid this condition.

协程 communicate ( input=None ) ¶

Interact with process:

1. send data to stdin (若 input 不是 None );

2. read data from stdout and stderr , until EOF is reached;

3. wait for process to terminate.

可选 input argument is the data ( bytes object) that will be sent to the child process.

返回元组 (stdout_data, stderr_data) .

若 BrokenPipeError or ConnectionResetError exception is raised when writing input into stdin , the exception is ignored. This condition occurs when the process exits before all data are written into stdin .

If it is desired to send data to the process’ stdin , the process needs to be created with stdin=PIPE 。同样，要获取任何东西除了 None in the result tuple, the process has to be created with stdout=PIPE and/or stderr=PIPE 自变量。

Note, that the data read is buffered in memory, so do not use this method if the data size is large or unlimited.

send_signal ( signal ) ¶

发送信号 signal to the child process.

注意

在 Windows， SIGTERM 是别名化的 terminate() . CTRL_C_EVENT and CTRL_BREAK_EVENT can be sent to processes started with a creationflags 参数包括 CREATE_NEW_PROCESS_GROUP .

terminate ( ) ¶

停止子级进程。

On POSIX systems this method sends signal.SIGTERM to the child process.

On Windows the Win32 API function TerminateProcess() is called to stop the child process.

kill ( ) ¶

杀除子级进程。

On POSIX systems this method sends SIGKILL to the child process.

On Windows this method is an alias for terminate() .

stdin ¶

标准输入流 ( StreamWriter ) 或 None if the process was created with stdin=None .

stdout ¶

标准输出流 ( StreamReader ) 或 None if the process was created with stdout=None .

stderr ¶

标准错误流 ( StreamReader ) 或 None if the process was created with stderr=None .

警告

使用 communicate() method rather than process.stdin.write() , await process.stdout.read() or await process.stderr.read . This avoids deadlocks due to streams pausing reading or writing and blocking the child process.

pid ¶

Process identification number (PID).

Note that for processes created by the create_subprocess_shell() function, this attribute is the PID of the spawned shell.

returncode ¶

Return code of the process when it exits.

A None value indicates that the process has not terminated yet.

负值 -N 指示子级被终止，通过信号 N (仅 POSIX)。

子进程和线程 ¶

Standard asyncio event loop supports running subprocesses from different threads by default.

On Windows subprocesses are provided by ProactorEventLoop only (default), SelectorEventLoop has no subprocess support.

On UNIX child watchers are used for subprocess finish waiting, see 进程看守程序 for more info.

3.8 版改变： UNIX switched to use ThreadedChildWatcher for spawning subprocesses from different threads without any limitation.

Spawning a subprocess with inactive current child watcher raises RuntimeError .

Note that alternative event loop implementations might have own limitations; please refer to their documentation.

另请参阅

The asyncio 中的并发和多线程 章节。

范例 ¶

范例使用 Process 类控制子进程和 StreamReader 类从其标准输出中读取。

子进程的创建通过 create_subprocess_exec() 函数：

import asyncio
import sys
async def get_date():
    code = 'import datetime; print(datetime.datetime.now())'
    # Create the subprocess; redirect the standard output
    # into a pipe.
    proc = await asyncio.create_subprocess_exec(
        sys.executable, '-c', code,
        stdout=asyncio.subprocess.PIPE)
    # Read one line of output.
    data = await proc.stdout.readline()
    line = data.decode('ascii').rstrip()
    # Wait for the subprocess exit.
    await proc.wait()
    return line
date = asyncio.run(get_date())
print(f"Current date: {date}")
					

另请参阅 相同范例 使用低级 API 编写。

内容表

• 子进程
  • 创建子进程
  • 常量
  • 与子进程交互
    • 子进程和线程
    • 范例

上一话题

同步原语

下一话题

队列

本页

• 报告 Bug
• 展示源