1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28 r"""subprocess - Subprocesses with accessible I/O streams
29
30 This module allows you to spawn processes, connect to their
31 input/output/error pipes, and obtain their return codes. This module
32 intends to replace several other, older modules and functions, like:
33
34 os.system
35 os.spawn*
36 os.popen*
37 popen2.*
38 commands.*
39
40 Information about how the subprocess module can be used to replace these
41 modules and functions can be found below.
42
43
44
45 Using the subprocess module
46 ===========================
47 This module defines one class called Popen:
48
49 class Popen(args, bufsize=0, executable=None,
50 stdin=None, stdout=None, stderr=None,
51 preexec_fn=None, close_fds=False, shell=False,
52 cwd=None, env=None, universal_newlines=False,
53 startupinfo=None, creationflags=0):
54
55
56 Arguments are:
57
58 args should be a string, or a sequence of program arguments. The
59 program to execute is normally the first item in the args sequence or
60 string, but can be explicitly set by using the executable argument.
61
62 On UNIX, with shell=False (default): In this case, the Popen class
63 uses os.execvp() to execute the child program. args should normally
64 be a sequence. A string will be treated as a sequence with the string
65 as the only item (the program to execute).
66
67 On UNIX, with shell=True: If args is a string, it specifies the
68 command string to execute through the shell. If args is a sequence,
69 the first item specifies the command string, and any additional items
70 will be treated as additional shell arguments.
71
72 On Windows: the Popen class uses CreateProcess() to execute the child
73 program, which operates on strings. If args is a sequence, it will be
74 converted to a string using the list2cmdline method. Please note that
75 not all MS Windows applications interpret the command line the same
76 way: The list2cmdline is designed for applications using the same
77 rules as the MS C runtime.
78
79 bufsize, if given, has the same meaning as the corresponding argument
80 to the built-in open() function: 0 means unbuffered, 1 means line
81 buffered, any other positive value means use a buffer of
82 (approximately) that size. A negative bufsize means to use the system
83 default, which usually means fully buffered. The default value for
84 bufsize is 0 (unbuffered).
85
86 stdin, stdout and stderr specify the executed programs' standard
87 input, standard output and standard error file handles, respectively.
88 Valid values are PIPE, an existing file descriptor (a positive
89 integer), an existing file object, and None. PIPE indicates that a
90 new pipe to the child should be created. With None, no redirection
91 will occur; the child's file handles will be inherited from the
92 parent. Additionally, stderr can be STDOUT, which indicates that the
93 stderr data from the applications should be captured into the same
94 file handle as for stdout.
95
96 If preexec_fn is set to a callable object, this object will be called
97 in the child process just before the child is executed.
98
99 If close_fds is true, all file descriptors except 0, 1 and 2 will be
100 closed before the child process is executed.
101
102 if shell is true, the specified command will be executed through the
103 shell.
104
105 If cwd is not None, the current directory will be changed to cwd
106 before the child is executed.
107
108 If env is not None, it defines the environment variables for the new
109 process.
110
111 If universal_newlines is true, the file objects stdout and stderr are
112 opened as a text files, but lines may be terminated by any of '\n',
113 the Unix end-of-line convention, '\r', the Macintosh convention or
114 '\r\n', the Windows convention. All of these external representations
115 are seen as '\n' by the Python program. Note: This feature is only
116 available if Python is built with universal newline support (the
117 default). Also, the newlines attribute of the file objects stdout,
118 stdin and stderr are not updated by the communicate() method.
119
120 The startupinfo and creationflags, if given, will be passed to the
121 underlying CreateProcess() function. They can specify things such as
122 appearance of the main window and priority for the new process.
123 (Windows only)
124
125
126 This module also defines two shortcut functions:
127
128 call(*args, **kwargs):
129 Run command with arguments. Wait for command to complete, then
130 return the returncode attribute.
131
132 The arguments are the same as for the Popen constructor. Example:
133
134 retcode = call(["ls", "-l"])
135
136
137 Exceptions
138 ----------
139 Exceptions raised in the child process, before the new program has
140 started to execute, will be re-raised in the parent. Additionally,
141 the exception object will have one extra attribute called
142 'child_traceback', which is a string containing traceback information
143 from the childs point of view.
144
145 The most common exception raised is OSError. This occurs, for
146 example, when trying to execute a non-existent file. Applications
147 should prepare for OSErrors.
148
149 A ValueError will be raised if Popen is called with invalid arguments.
150
151
152 Security
153 --------
154 Unlike some other popen functions, this implementation will never call
155 /bin/sh implicitly. This means that all characters, including shell
156 metacharacters, can safely be passed to child processes.
157
158
159 Popen objects
160 =============
161 Instances of the Popen class have the following methods:
162
163 poll()
164 Check if child process has terminated. Returns returncode
165 attribute.
166
167 wait()
168 Wait for child process to terminate. Returns returncode attribute.
169
170 communicate(input=None)
171 Interact with process: Send data to stdin. Read data from stdout
172 and stderr, until end-of-file is reached. Wait for process to
173 terminate. The optional stdin argument should be a string to be
174 sent to the child process, or None, if no data should be sent to
175 the child.
176
177 communicate() returns a tuple (stdout, stderr).
178
179 Note: The data read is buffered in memory, so do not use this
180 method if the data size is large or unlimited.
181
182 The following attributes are also available:
183
184 stdin
185 If the stdin argument is PIPE, this attribute is a file object
186 that provides input to the child process. Otherwise, it is None.
187
188 stdout
189 If the stdout argument is PIPE, this attribute is a file object
190 that provides output from the child process. Otherwise, it is
191 None.
192
193 stderr
194 If the stderr argument is PIPE, this attribute is file object that
195 provides error output from the child process. Otherwise, it is
196 None.
197
198 pid
199 The process ID of the child process.
200
201 returncode
202 The child return code. A None value indicates that the process
203 hasn't terminated yet. A negative value -N indicates that the
204 child was terminated by signal N (UNIX only).
205
206
207 Replacing older functions with the subprocess module
208 ====================================================
209 In this section, "a ==> b" means that b can be used as a replacement
210 for a.
211
212 Note: All functions in this section fail (more or less) silently if
213 the executed program cannot be found; this module raises an OSError
214 exception.
215
216 In the following examples, we assume that the subprocess module is
217 imported with "from subprocess import *".
218
219
220 Replacing /bin/sh shell backquote
221 ---------------------------------
222 output=`mycmd myarg`
223 ==>
224 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
225
226
227 Replacing shell pipe line
228 -------------------------
229 output=`dmesg | grep hda`
230 ==>
231 p1 = Popen(["dmesg"], stdout=PIPE)
232 p2 = Popen(["grep", "hda"], stdin=p1.stdout)
233 output = p2.communicate()[0]
234
235
236 Replacing os.system()
237 ---------------------
238 sts = os.system("mycmd" + " myarg")
239 ==>
240 p = Popen("mycmd" + " myarg", shell=True)
241 sts = os.waitpid(p.pid, 0)
242
243 Note:
244
245 * Calling the program through the shell is usually not required.
246
247 * It's easier to look at the returncode attribute than the
248 exitstatus.
249
250 A more real-world example would look like this:
251
252 try:
253 retcode = call("mycmd" + " myarg", shell=True)
254 if retcode < 0:
255 print >>sys.stderr, "Child was terminated by signal", -retcode
256 else:
257 print >>sys.stderr, "Child returned", retcode
258 except OSError, e:
259 print >>sys.stderr, "Execution failed:", e
260
261
262 Replacing os.spawn*
263 -------------------
264 P_NOWAIT example:
265
266 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
267 ==>
268 pid = Popen(["/bin/mycmd", "myarg"]).pid
269
270
271 P_WAIT example:
272
273 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
274 ==>
275 retcode = call(["/bin/mycmd", "myarg"])
276
277
278 Vector example:
279
280 os.spawnvp(os.P_NOWAIT, path, args)
281 ==>
282 Popen([path] + args[1:])
283
284
285 Environment example:
286
287 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
288 ==>
289 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
290
291
292 Replacing os.popen*
293 -------------------
294 pipe = os.popen(cmd, mode='r', bufsize)
295 ==>
296 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
297
298 pipe = os.popen(cmd, mode='w', bufsize)
299 ==>
300 pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
301
302
303 (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
304 ==>
305 p = Popen(cmd, shell=True, bufsize=bufsize,
306 stdin=PIPE, stdout=PIPE, close_fds=True)
307 (child_stdin, child_stdout) = (p.stdin, p.stdout)
308
309
310 (child_stdin,
311 child_stdout,
312 child_stderr) = os.popen3(cmd, mode, bufsize)
313 ==>
314 p = Popen(cmd, shell=True, bufsize=bufsize,
315 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
316 (child_stdin,
317 child_stdout,
318 child_stderr) = (p.stdin, p.stdout, p.stderr)
319
320
321 (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
322 ==>
323 p = Popen(cmd, shell=True, bufsize=bufsize,
324 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
325 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
326
327
328 Replacing popen2.*
329 ------------------
330 Note: If the cmd argument to popen2 functions is a string, the command
331 is executed through /bin/sh. If it is a list, the command is directly
332 executed.
333
334 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
335 ==>
336 p = Popen(["somestring"], shell=True, bufsize=bufsize
337 stdin=PIPE, stdout=PIPE, close_fds=True)
338 (child_stdout, child_stdin) = (p.stdout, p.stdin)
339
340
341 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
342 ==>
343 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
344 stdin=PIPE, stdout=PIPE, close_fds=True)
345 (child_stdout, child_stdin) = (p.stdout, p.stdin)
346
347 The popen2.Popen3 and popen3.Popen4 basically works as subprocess.Popen,
348 except that:
349
350 * subprocess.Popen raises an exception if the execution fails
351 * the capturestderr argument is replaced with the stderr argument.
352 * stdin=PIPE and stdout=PIPE must be specified.
353 * popen2 closes all filedescriptors by default, but you have to specify
354 close_fds=True with subprocess.Popen.
355
356
357 """
358
359 import sys
360 mswindows = (sys.platform == "win32")
361
362 import os
363 import types
364 import traceback
365
366 if mswindows:
367 import threading
368 import msvcrt
369 if 0:
370 import pywintypes
371 from win32api import GetStdHandle, STD_INPUT_HANDLE, \
372 STD_OUTPUT_HANDLE, STD_ERROR_HANDLE
373 from win32api import GetCurrentProcess, DuplicateHandle, \
374 GetModuleFileName, GetVersion
375 from win32con import DUPLICATE_SAME_ACCESS, SW_HIDE
376 from win32pipe import CreatePipe
377 from win32process import CreateProcess, STARTUPINFO, \
378 GetExitCodeProcess, STARTF_USESTDHANDLES, \
379 STARTF_USESHOWWINDOW, CREATE_NEW_CONSOLE
380 from win32event import WaitForSingleObject, INFINITE, WAIT_OBJECT_0
381 else:
382 from _subprocess import *
383 class STARTUPINFO:
384 dwFlags = 0
385 hStdInput = None
386 hStdOutput = None
387 hStdError = None