subprocess — 子进程管理 ¶

频繁使用的自变量 ¶

为支持各种使用案例， Popen constructor (and the convenience functions) accept a large number of optional arguments. For most typical use cases, many of these arguments can be safely left at their default values. The arguments that are most commonly needed are:

args is required for all calls and should be a string, or a sequence of program arguments. Providing a sequence of arguments is generally preferred, as it allows the module to take care of any required escaping and quoting of arguments (e.g. to permit spaces in file names). If passing a single string, either shell 必须是 True (see below) or else the string must simply name the program to be executed without specifying any arguments.

stdin , stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are PIPE , DEVNULL , an existing file descriptor (a positive integer), an existing file object, and None . PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. With the default settings of None , no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, stderr 可以是 STDOUT , which indicates that the stderr data from the child process should be captured into the same file handle as for stdout .

若 encoding or errors 被指定，或 text (also known as universal_newlines ) is true, the file objects stdin , stdout and stderr will be opened in text mode using the encoding and errors specified in the call or the defaults for io.TextIOWrapper .

For stdin , line ending characters '\n' in the input will be converted to the default line separator os.linesep . For stdout and stderr , all line endings in the output will be converted to '\n' . For more information see the documentation of the io.TextIOWrapper class when the newline argument to its constructor is None .

If text mode is not used, stdin , stdout and stderr will be opened as binary streams. No encoding or line ending conversion is performed.

3.6 版新增： 添加 encoding and errors 参数。

3.7 版新增： 添加 text parameter as an alias for universal_newlines .

注意

The newlines attribute of the file objects Popen.stdin , Popen.stdout and Popen.stderr are not updated by the Popen.communicate() 方法。

若 shell is True , the specified command will be executed through the shell. This can be useful if you are using Python primarily for the enhanced control flow it offers over most system shells and still want convenient access to other shell features such as shell pipes, filename wildcards, environment variable expansion, and expansion of ~ to a user’s home directory. However, note that Python itself offers implementations of many shell-like features (in particular, glob , fnmatch , os.walk() , os.path.expandvars() , os.path.expanduser() ，和 shutil ).

3.3 版改变： 当 universal_newlines is True , the class uses the encoding locale.getpreferredencoding(False) 而不是 locale.getpreferredencoding() 。见 io.TextIOWrapper 类，了解有关此变化的更多信息。

注意

阅读 安全注意事项 章节先于使用 shell=True .

这些选项及所有其它选项的更详细描述在 Popen 构造函数文档编制。

Popen 构造函数 ¶

此模块中底层进程的创建和管理的处理是通过 Popen 类。它提供了很大的灵活性，以便开发者能够处理方便函数未涵盖的不常见情况。

class subprocess. Popen ( args , bufsize=-1 , executable=None , stdin=None , stdout=None , stderr=None , preexec_fn=None , close_fds=True , shell=False , cwd=None , env=None , universal_newlines=None , startupinfo=None , creationflags=0 , restore_signals=True , start_new_session=False , pass_fds=() , * , group=None , extra_groups=None , user=None , umask=-1 , encoding=None , errors=None , text=None ) ¶

在新进程中执行子级程序。在 POSIX (便携式操作系统接口)，类使用 os.execvp() 类似行为来执行子级程序。在 Windows，类使用 Windows CreateProcess() 函数。自变量到 Popen 如下所示。

args should be a sequence of program arguments or else a single string or 像路径对象 . By default, the program to execute is the first item in args if args is a sequence. If args is a string, the interpretation is platform-dependent and described below. See the shell and executable arguments for additional differences from the default behavior. Unless otherwise stated, it is recommended to pass args as a sequence.

An example of passing some arguments to an external program as a sequence is:

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])
											

在 POSIX (便携式操作系统接口)，若 args is a string, the string is interpreted as the name or path of the program to execute. However, this can only be done if not passing arguments to the program.

注意

It may not be obvious how to break a shell command into a sequence of arguments, especially in complex cases. shlex.split() can illustrate how to determine the correct tokenization for args :

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!
												

Note in particular that options (such as -input ) and arguments (such as eggs.txt ) that are separated by whitespace in the shell go in separate list elements, while arguments that need quoting or backslash escaping when used in the shell (such as filenames containing spaces or the echo command shown above) are single list elements.

On Windows, if args is a sequence, it will be converted to a string in a manner described in 在 Windows 将自变量序列转换成字符串 . This is because the underlying CreateProcess() operates on strings.

3.6 版改变： args parameter accepts a 像路径对象 if shell is False and a sequence containing path-like objects on POSIX.

3.8 版改变： args parameter accepts a 像路径对象 if shell is False and a sequence containing bytes and path-like objects on Windows.

shell argument (which defaults to False ) specifies whether to use the shell as the program to execute. If shell is True , it is recommended to pass args as a string rather than as a sequence.

On POSIX with shell=True , the shell defaults to /bin/sh 。若 args is a string, the string specifies the command to execute through the shell. This means that the string must be formatted exactly as it would be when typed at the shell prompt. This includes, for example, quoting or backslash escaping filenames with spaces in them. If args is a sequence, the first item specifies the command string, and any additional items will be treated as additional arguments to the shell itself. That is to say, Popen does the equivalent of:

Popen(['/bin/sh', '-c', args[0], args[1], ...])
											

在 Windows 采用 shell=True ， COMSPEC environment variable specifies the default shell. The only time you need to specify shell=True on Windows is when the command you wish to execute is built into the shell (e.g. dir or copy ). You do not need shell=True to run a batch file or console-based executable.

注意

阅读 安全注意事项 章节先于使用 shell=True .

bufsize will be supplied as the corresponding argument to the open() function when creating the stdin/stdout/stderr pipe file objects:

• 0 means unbuffered (read and write are one system call and can return short)

• 1 means line buffered (only usable if universal_newlines=True i.e., in a text mode)

• any other positive value means use a buffer of approximately that size

• negative bufsize (the default) means the system default of io.DEFAULT_BUFFER_SIZE will be used.

Changed in version 3.3.1: bufsize now defaults to -1 to enable buffering by default to match the behavior that most code expects. In versions prior to Python 3.2.4 and 3.3.1 it incorrectly defaulted to 0 which was unbuffered and allowed short reads. This was unintentional and did not match the behavior of Python 2 as most code expected.

executable argument specifies a replacement program to execute. It is very seldom needed. When shell=False , executable replaces the program to execute specified by args . However, the original args is still passed to the program. Most programs treat the program specified by args as the command name, which can then be different from the program actually executed. On POSIX, the args name becomes the display name for the executable in utilities such as ps 。若 shell=True , on POSIX the executable argument specifies a replacement shell for the default /bin/sh .

3.6 版改变： executable parameter accepts a 像路径对象 on POSIX.

3.8 版改变： executable parameter accepts a bytes and 像路径对象 在 Windows。

stdin , stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are PIPE , DEVNULL , an existing file descriptor (a positive integer), an existing 文件对象 ，和 None . PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. With the default settings of None , no redirection will occur; the child’s file handles will be inherited from the parent. Additionally, stderr 可以是 STDOUT , which indicates that the stderr data from the applications should be captured into the same file handle as for stdout.

若 preexec_fn is set to a callable object, this object will be called in the child process just before the child is executed. (POSIX only)

警告

preexec_fn parameter is not safe to use in the presence of threads in your application. The child process could deadlock before exec is called. If you must use it, keep it trivial! Minimize the number of libraries you call into.

注意

若需要为子级修改环境使用 env 参数而不是处理它在 preexec_fn . start_new_session 参数可以代替以前常用的 preexec_fn 以在子级中调用 os.setsid()。

3.8 版改变： preexec_fn parameter is no longer supported in subinterpreters. The use of the parameter in a subinterpreter raises RuntimeError . The new restriction may affect applications that are deployed in mod_wsgi, uWSGI, and other embedded environments.

若 close_fds is true, all file descriptors except 0 , 1 and 2 will be closed before the child process is executed. Otherwise when close_fds is false, file descriptors obey their inheritable flag as described in 文件描述符的继承 .

On Windows, if close_fds is true then no handles will be inherited by the child process unless explicitly passed in the handle_list 元素的 STARTUPINFO.lpAttributeList , or by standard handle redirection.

3.2 版改变： 默认为 close_fds was changed from False to what is described above.

3.7 版改变： On Windows the default for close_fds was changed from False to True when redirecting the standard handles. It’s now possible to set close_fds to True when redirecting the standard handles.

pass_fds is an optional sequence of file descriptors to keep open between the parent and child. Providing any pass_fds forces close_fds to be True . (POSIX only)

3.2 版改变： pass_fds 参数被添加。

若 cwd 不是 None , the function changes the working directory to cwd before executing the child. cwd can be a string, bytes or 像路径 object. In particular, the function looks for executable (or for the first item in args ) relative to cwd if the executable path is a relative path.

3.6 版改变： cwd parameter accepts a 像路径对象 on POSIX.

3.7 版改变： cwd parameter accepts a 像路径对象 在 Windows。

3.8 版改变： cwd parameter accepts a bytes object on Windows.

若 restore_signals is true (the default) all signals that Python has set to SIG_IGN are restored to SIG_DFL in the child process before the exec. Currently this includes the SIGPIPE, SIGXFZ and SIGXFSZ signals. (POSIX only)

3.2 版改变： restore_signals 被添加。

若 start_new_session is true the setsid() system call will be made in the child process prior to the execution of the subprocess. (POSIX only)

3.2 版改变： start_new_session 被添加。

若 group 不是 None , the setregid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via grp.getgrnam() and the value in gr_gid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

可用性 : POSIX

3.9 版新增。

若 extra_groups 不是 None , the setgroups() system call will be made in the child process prior to the execution of the subprocess. Strings provided in extra_groups will be looked up via grp.getgrnam() and the values in gr_gid will be used. Integer values will be passed verbatim. (POSIX only)

可用性 : POSIX

3.9 版新增。

若 user 不是 None , the setreuid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via pwd.getpwnam() and the value in pw_uid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

可用性 : POSIX

3.9 版新增。

若 umask is not negative, the umask() system call will be made in the child process prior to the execution of the subprocess.

可用性 : POSIX

3.9 版新增。

若 env 不是 None ，它必须是为新进程定义环境变量的映射；使用这些代替继承当前进程环境的默认行为。

注意

若指定， env 必须提供要执行程序要求的任何变量。在 Windows，为运行 并行汇编 指定 env must 包括有效 SystemRoot .

若 encoding or errors 被指定，或 text is true, the file objects stdin , stdout and stderr are opened in text mode with the specified encoding and errors , as described above in 频繁使用的自变量 . universal_newlines argument is equivalent to text and is provided for backwards compatibility. By default, file objects are opened in binary mode.

3.6 版新增： encoding and errors 被添加。

3.7 版新增： text was added as a more readable alias for universal_newlines .

若给定， startupinfo will be a STARTUPINFO object, which is passed to the underlying CreateProcess 函数。 creationflags , if given, can be one or more of the following flags:

• CREATE_NEW_CONSOLE

• CREATE_NEW_PROCESS_GROUP

• ABOVE_NORMAL_PRIORITY_CLASS

• BELOW_NORMAL_PRIORITY_CLASS

• HIGH_PRIORITY_CLASS

• IDLE_PRIORITY_CLASS

• NORMAL_PRIORITY_CLASS

• REALTIME_PRIORITY_CLASS

• CREATE_NO_WINDOW

• DETACHED_PROCESS

• CREATE_DEFAULT_ERROR_MODE

• CREATE_BREAKAWAY_FROM_JOB

Popen objects are supported as context managers via the with statement: on exit, standard file descriptors are closed, and the process is waited for.

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())
											

Popen 和此模块中使用它的其它函数会引发 审计事件 subprocess.Popen 采用自变量 executable , args , cwd ，和 env 。值对于 args 可能是单字符串或字符串列表，从属平台。

3.2 版改变： 添加上下文管理器支持。

3.6 版改变： Popen 析构函数现在发射 ResourceWarning warning if the child process is still running.

3.8 版改变： Popen can use os.posix_spawn() in some cases for better performance. On Windows Subsystem for Linux and QEMU User Emulation, Popen constructor using os.posix_spawn() no longer raise an exception on errors like missing program, but the child process fails with a non-zero returncode .

异常 ¶

Exceptions raised in the child process, before the new program has started to execute, will be re-raised in the parent.

The most common exception raised is OSError . This occurs, for example, when trying to execute a non-existent file. Applications should prepare for OSError exceptions. Note that, when shell=True , OSError will be raised by the child only if the selected shell itself was not found. To determine if the shell failed to find the requested application, it is necessary to check the return code or output from the subprocess.

A ValueError 会被引发若 Popen is called with invalid arguments.

check_call() and check_output() 会引发 CalledProcessError if the called process returns a non-zero return code.

All of the functions and methods that accept a timeout parameter, such as call() and Popen.communicate() 会引发 TimeoutExpired if the timeout expires before the process exits.

Exceptions defined in this module all inherit from SubprocessError .

3.3 版新增： SubprocessError 基类被添加。

Windows 常量 ¶

subprocess 模块暴露以下常量。

subprocess. STD_INPUT_HANDLE ¶

The standard input device. Initially, this is the console input buffer, CONIN$ .

subprocess. STD_OUTPUT_HANDLE ¶

The standard output device. Initially, this is the active console screen buffer, CONOUT$ .

subprocess. STD_ERROR_HANDLE ¶

The standard error device. Initially, this is the active console screen buffer, CONOUT$ .

subprocess. SW_HIDE ¶

Hides the window. Another window will be activated.

subprocess. STARTF_USESTDHANDLES ¶

Specifies that the STARTUPINFO.hStdInput , STARTUPINFO.hStdOutput ，和 STARTUPINFO.hStdError attributes contain additional information.

subprocess. STARTF_USESHOWWINDOW ¶

Specifies that the STARTUPINFO.wShowWindow attribute contains additional information.

subprocess. CREATE_NEW_CONSOLE ¶

The new process has a new console, instead of inheriting its parent’s console (the default).

subprocess. CREATE_NEW_PROCESS_GROUP ¶

A Popen creationflags parameter to specify that a new process group will be created. This flag is necessary for using os.kill() on the subprocess.

此标志会被忽略，若 CREATE_NEW_CONSOLE 被指定。

subprocess. ABOVE_NORMAL_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have an above average priority.

3.7 版新增。

subprocess. BELOW_NORMAL_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have a below average priority.

3.7 版新增。

subprocess. HIGH_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have a high priority.

3.7 版新增。

subprocess. IDLE_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have an idle (lowest) priority.

3.7 版新增。

subprocess. NORMAL_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have an normal priority. (default)

3.7 版新增。

subprocess. REALTIME_PRIORITY_CLASS ¶

A Popen creationflags parameter to specify that a new process will have realtime priority. You should almost never use REALTIME_PRIORITY_CLASS, because this interrupts system threads that manage mouse input, keyboard input, and background disk flushing. This class can be appropriate for applications that “talk” directly to hardware or that perform brief tasks that should have limited interruptions.

3.7 版新增。

subprocess. CREATE_NO_WINDOW ¶

A Popen creationflags parameter to specify that a new process will not create a window.

3.7 版新增。

subprocess. DETACHED_PROCESS ¶

A Popen creationflags parameter to specify that a new process will not inherit its parent’s console. This value cannot be used with CREATE_NEW_CONSOLE.

3.7 版新增。

subprocess. CREATE_DEFAULT_ERROR_MODE ¶

A Popen creationflags parameter to specify that a new process does not inherit the error mode of the calling process. Instead, the new process gets the default error mode. This feature is particularly useful for multithreaded shell applications that run with hard errors disabled.

3.7 版新增。

subprocess. CREATE_BREAKAWAY_FROM_JOB ¶

A Popen creationflags parameter to specify that a new process is not associated with the job.

3.7 版新增。

替换 /bin/sh Shell 命令代入 ¶

output=$(mycmd myarg)
									

变为：

output = check_output(["mycmd", "myarg"])
									

替换 Shell 管道 ¶

output=$(dmesg | grep hda)
									

变为：

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]
									

p1.stdout.close() call after starting the p2 is important in order for p1 to receive a SIGPIPE if p2 exits before p1.

Alternatively, for trusted input, the shell’s own pipeline support may still be used directly:

output=$(dmesg | grep hda)
									

变为：

output=check_output("dmesg | grep hda", shell=True)
									

替换 os.system() ¶

sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)
									

注意事项：

• Calling the program through the shell is usually not required.

• call() return value is encoded differently to that of os.system() .

• os.system() function ignores SIGINT and SIGQUIT signals while the command is running, but the caller must do this separately when using the subprocess 模块。

更现实范例看起来像这样：

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)
									

替换 os.spawn 系列 ¶

P_NOWAIT 范例：

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid
									

P_WAIT 范例：

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])
									

向量范例：

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])
									

环境范例：

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
									

替换 os.popen() , os.popen2() , os.popen3() ¶

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)
									

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)
									

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
									

返回代码处理翻译如下：

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")
									

替换函数来自 popen2 模块 ¶

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)
									

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)
									

popen2.Popen3 and popen2.Popen4 basically work as subprocess.Popen , except that:

• Popen 引发异常若执行失败。

• capturestderr 自变量被替换采用 stderr 自变量。

• stdin=PIPE and stdout=PIPE 必须指定。

• popen2 closes all file descriptors by default, but you have to specify close_fds=True with Popen to guarantee this behavior on all platforms or past Python versions.

在 Windows 将自变量序列转换成字符串 ¶

在 Windows， args sequence is converted to a string that can be parsed using the following rules (which correspond to the rules used by the MS C runtime):

1. Arguments are delimited by white space, which is either a space or a tab.

2. A string surrounded by double quotation marks is interpreted as a single argument, regardless of white space contained within. A quoted string can be embedded in an argument.

3. A double quotation mark preceded by a backslash is interpreted as a literal double quotation mark.

4. Backslashes are interpreted literally, unless they immediately precede a double quotation mark.

5. If backslashes immediately precede a double quotation mark, every pair of backslashes is interpreted as a literal backslash. If the number of backslashes is odd, the last backslash escapes the next double quotation mark as described in rule 3.