blob: 4c4a56ad5102b76587e380510b6f2a90609eb408 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001
2:mod:`subprocess` --- Subprocess management
3===========================================
4
5.. module:: subprocess
6 :synopsis: Subprocess management.
7.. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
8.. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
9
10
Georg Brandl116aa622007-08-15 14:28:22 +000011The :mod:`subprocess` module allows you to spawn new processes, connect to their
12input/output/error pipes, and obtain their return codes. This module intends to
13replace several other, older modules and functions, such as::
14
15 os.system
16 os.spawn*
Georg Brandl116aa622007-08-15 14:28:22 +000017
18Information about how the :mod:`subprocess` module can be used to replace these
19modules and functions can be found in the following sections.
20
Benjamin Peterson41181742008-07-02 20:22:54 +000021.. seealso::
22
23 :pep:`324` -- PEP proposing the subprocess module
24
Georg Brandl116aa622007-08-15 14:28:22 +000025
26Using the subprocess Module
27---------------------------
28
29This module defines one class called :class:`Popen`:
30
31
32.. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0)
33
34 Arguments are:
35
Benjamin Petersond18de0e2008-07-31 20:21:46 +000036 *args* should be a string, or a sequence of program arguments. The program
Benjamin Petersonfa0d7032009-06-01 22:42:33 +000037 to execute is normally the first item in the args sequence or the string if
38 a string is given, but can be explicitly set by using the *executable*
39 argument. When *executable* is given, the first item in the args sequence
40 is still treated by most programs as the command name, which can then be
41 different from the actual executable name. On Unix, it becomes the display
42 name for the executing program in utilities such as :program:`ps`.
Georg Brandl116aa622007-08-15 14:28:22 +000043
44 On Unix, with *shell=False* (default): In this case, the Popen class uses
45 :meth:`os.execvp` to execute the child program. *args* should normally be a
46 sequence. A string will be treated as a sequence with the string as the only
47 item (the program to execute).
48
49 On Unix, with *shell=True*: If args is a string, it specifies the command string
50 to execute through the shell. If *args* is a sequence, the first item specifies
51 the command string, and any additional items will be treated as additional shell
52 arguments.
53
54 On Windows: the :class:`Popen` class uses CreateProcess() to execute the child
55 program, which operates on strings. If *args* is a sequence, it will be
56 converted to a string using the :meth:`list2cmdline` method. Please note that
57 not all MS Windows applications interpret the command line the same way:
58 :meth:`list2cmdline` is designed for applications using the same rules as the MS
59 C runtime.
60
61 *bufsize*, if given, has the same meaning as the corresponding argument to the
62 built-in open() function: :const:`0` means unbuffered, :const:`1` means line
63 buffered, any other positive value means use a buffer of (approximately) that
64 size. A negative *bufsize* means to use the system default, which usually means
65 fully buffered. The default value for *bufsize* is :const:`0` (unbuffered).
66
67 The *executable* argument specifies the program to execute. It is very seldom
68 needed: Usually, the program to execute is defined by the *args* argument. If
69 ``shell=True``, the *executable* argument specifies which shell to use. On Unix,
70 the default shell is :file:`/bin/sh`. On Windows, the default shell is
Georg Brandlbcc484e2009-08-13 11:51:54 +000071 specified by the :envvar:`COMSPEC` environment variable. The only reason you
72 would need to specify ``shell=True`` on Windows is where the command you
73 wish to execute is actually built in to the shell, eg ``dir``, ``copy``.
74 You don't need ``shell=True`` to run a batch file, nor to run a console-based
75 executable.
Georg Brandl116aa622007-08-15 14:28:22 +000076
77 *stdin*, *stdout* and *stderr* specify the executed programs' standard input,
Georg Brandlaf265f42008-12-07 15:06:20 +000078 standard output and standard error file handles, respectively. Valid values
79 are :data:`PIPE`, an existing file descriptor (a positive integer), an
80 existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
81 to the child should be created. With ``None``, no redirection will occur;
82 the child's file handles will be inherited from the parent. Additionally,
83 *stderr* can be :data:`STDOUT`, which indicates that the stderr data from the
84 applications should be captured into the same file handle as for stdout.
Georg Brandl116aa622007-08-15 14:28:22 +000085
86 If *preexec_fn* is set to a callable object, this object will be called in the
87 child process just before the child is executed. (Unix only)
88
89 If *close_fds* is true, all file descriptors except :const:`0`, :const:`1` and
90 :const:`2` will be closed before the child process is executed. (Unix only).
91 Or, on Windows, if *close_fds* is true then no handles will be inherited by the
92 child process. Note that on Windows, you cannot set *close_fds* to true and
93 also redirect the standard handles by setting *stdin*, *stdout* or *stderr*.
94
95 If *shell* is :const:`True`, the specified command will be executed through the
96 shell.
97
98 If *cwd* is not ``None``, the child's current directory will be changed to *cwd*
99 before it is executed. Note that this directory is not considered when
100 searching the executable, so you can't specify the program's path relative to
101 *cwd*.
102
Christian Heimesa342c012008-04-20 21:01:16 +0000103 If *env* is not ``None``, it must be a mapping that defines the environment
104 variables for the new process; these are used instead of inheriting the current
105 process' environment, which is the default behavior.
Georg Brandl116aa622007-08-15 14:28:22 +0000106
R. David Murray1055e892009-04-16 18:15:32 +0000107 .. note::
R. David Murrayf4ac1492009-04-15 22:35:15 +0000108
R. David Murray1055e892009-04-16 18:15:32 +0000109 If specified, *env* must provide any variables required
110 for the program to execute. On Windows, in order to run a
111 `side-by-side assembly`_ the specified *env* **must** include a valid
R. David Murrayf4ac1492009-04-15 22:35:15 +0000112 :envvar:`SystemRoot`.
113
R. David Murray1055e892009-04-16 18:15:32 +0000114 .. _side-by-side assembly: http://en.wikipedia.org/wiki/Side-by-Side_Assembly
115
Georg Brandl116aa622007-08-15 14:28:22 +0000116 If *universal_newlines* is :const:`True`, the file objects stdout and stderr are
117 opened as text files, but lines may be terminated by any of ``'\n'``, the Unix
Georg Brandlc575c902008-09-13 17:46:05 +0000118 end-of-line convention, ``'\r'``, the old Macintosh convention or ``'\r\n'``, the
Georg Brandl116aa622007-08-15 14:28:22 +0000119 Windows convention. All of these external representations are seen as ``'\n'``
120 by the Python program.
121
122 .. note::
123
124 This feature is only available if Python is built with universal newline support
125 (the default). Also, the newlines attribute of the file objects :attr:`stdout`,
Georg Brandle11787a2008-07-01 19:10:52 +0000126 :attr:`stdin` and :attr:`stderr` are not updated by the :meth:`communicate` method.
Georg Brandl116aa622007-08-15 14:28:22 +0000127
128 The *startupinfo* and *creationflags*, if given, will be passed to the
129 underlying CreateProcess() function. They can specify things such as appearance
130 of the main window and priority for the new process. (Windows only)
131
132
Georg Brandlaf265f42008-12-07 15:06:20 +0000133.. data:: PIPE
134
135 Special value that can be used as the *stdin*, *stdout* or *stderr* argument
136 to :class:`Popen` and indicates that a pipe to the standard stream should be
137 opened.
138
139
140.. data:: STDOUT
141
142 Special value that can be used as the *stderr* argument to :class:`Popen` and
143 indicates that standard error should go into the same handle as standard
144 output.
Georg Brandl48310cd2009-01-03 21:18:54 +0000145
Georg Brandlaf265f42008-12-07 15:06:20 +0000146
Georg Brandl116aa622007-08-15 14:28:22 +0000147Convenience Functions
148^^^^^^^^^^^^^^^^^^^^^
149
Brett Cannona23810f2008-05-26 19:04:21 +0000150This module also defines four shortcut functions:
Georg Brandl116aa622007-08-15 14:28:22 +0000151
152
153.. function:: call(*popenargs, **kwargs)
154
155 Run command with arguments. Wait for command to complete, then return the
156 :attr:`returncode` attribute.
157
158 The arguments are the same as for the Popen constructor. Example::
159
160 retcode = call(["ls", "-l"])
161
Philip Jenveyab7481a2009-05-22 05:46:35 +0000162 .. warning::
163
164 Like :meth:`Popen.wait`, this will deadlock if the child process
165 generates enough output to a stdout or stderr pipe such that it blocks
166 waiting for the OS pipe buffer to accept more data.
167
Georg Brandl116aa622007-08-15 14:28:22 +0000168
169.. function:: check_call(*popenargs, **kwargs)
170
171 Run command with arguments. Wait for command to complete. If the exit code was
Benjamin Petersone5384b02008-10-04 22:00:42 +0000172 zero then return, otherwise raise :exc:`CalledProcessError`. The
Georg Brandl116aa622007-08-15 14:28:22 +0000173 :exc:`CalledProcessError` object will have the return code in the
174 :attr:`returncode` attribute.
175
176 The arguments are the same as for the Popen constructor. Example::
177
178 check_call(["ls", "-l"])
179
Philip Jenveyab7481a2009-05-22 05:46:35 +0000180 .. warning::
181
182 See the warning for :func:`call`.
183
Georg Brandl116aa622007-08-15 14:28:22 +0000184
Georg Brandlf9734072008-12-07 15:30:06 +0000185.. function:: check_output(*popenargs, **kwargs)
186
187 Run command with arguments and return its output as a byte string.
188
Benjamin Petersonaa069002009-01-23 03:26:36 +0000189 If the exit code was non-zero it raises a :exc:`CalledProcessError`. The
190 :exc:`CalledProcessError` object will have the return code in the
191 :attr:`returncode`
192 attribute and output in the :attr:`output` attribute.
Georg Brandlf9734072008-12-07 15:30:06 +0000193
Benjamin Peterson25c95f12009-05-08 20:42:26 +0000194 The arguments are the same as for the :class:`Popen` constructor. Example::
Georg Brandlf9734072008-12-07 15:30:06 +0000195
196 >>> subprocess.check_output(["ls", "-l", "/dev/null"])
197 'crw-rw-rw- 1 root root 1, 3 Oct 18 2007 /dev/null\n'
198
199 The stdout argument is not allowed as it is used internally.
Benjamin Peterson25c95f12009-05-08 20:42:26 +0000200 To capture standard error in the result, use ``stderr=subprocess.STDOUT``::
Georg Brandlf9734072008-12-07 15:30:06 +0000201
202 >>> subprocess.check_output(
Mark Dickinson934896d2009-02-21 20:59:32 +0000203 ["/bin/sh", "-c", "ls non_existent_file ; exit 0"],
Georg Brandlf9734072008-12-07 15:30:06 +0000204 stderr=subprocess.STDOUT)
Mark Dickinson934896d2009-02-21 20:59:32 +0000205 'ls: non_existent_file: No such file or directory\n'
Georg Brandlf9734072008-12-07 15:30:06 +0000206
207 .. versionadded:: 3.1
208
209
Brett Cannona23810f2008-05-26 19:04:21 +0000210.. function:: getstatusoutput(cmd)
211 Return ``(status, output)`` of executing *cmd* in a shell.
212
213 Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
214 ``(status, output)``. *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the
215 returned output will contain output or error messages. A trailing newline is
216 stripped from the output. The exit status for the command can be interpreted
217 according to the rules for the C function :cfunc:`wait`. Example::
218
219 >>> import subprocess
220 >>> subprocess.getstatusoutput('ls /bin/ls')
221 (0, '/bin/ls')
222 >>> subprocess.getstatusoutput('cat /bin/junk')
223 (256, 'cat: /bin/junk: No such file or directory')
224 >>> subprocess.getstatusoutput('/bin/junk')
225 (256, 'sh: /bin/junk: not found')
226
Georg Brandl7d418902008-12-27 19:08:11 +0000227 Availability: UNIX.
228
Brett Cannona23810f2008-05-26 19:04:21 +0000229
230.. function:: getoutput(cmd)
Georg Brandlf9734072008-12-07 15:30:06 +0000231 Return output (stdout and stderr) of executing *cmd* in a shell.
Brett Cannona23810f2008-05-26 19:04:21 +0000232
233 Like :func:`getstatusoutput`, except the exit status is ignored and the return
234 value is a string containing the command's output. Example::
235
236 >>> import subprocess
237 >>> subprocess.getoutput('ls /bin/ls')
238 '/bin/ls'
239
Georg Brandl7d418902008-12-27 19:08:11 +0000240 Availability: UNIX.
241
Brett Cannona23810f2008-05-26 19:04:21 +0000242
Georg Brandl116aa622007-08-15 14:28:22 +0000243Exceptions
244^^^^^^^^^^
245
246Exceptions raised in the child process, before the new program has started to
247execute, will be re-raised in the parent. Additionally, the exception object
248will have one extra attribute called :attr:`child_traceback`, which is a string
249containing traceback information from the childs point of view.
250
251The most common exception raised is :exc:`OSError`. This occurs, for example,
252when trying to execute a non-existent file. Applications should prepare for
253:exc:`OSError` exceptions.
254
255A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid
256arguments.
257
258check_call() will raise :exc:`CalledProcessError`, if the called process returns
259a non-zero return code.
260
261
262Security
263^^^^^^^^
264
265Unlike some other popen functions, this implementation will never call /bin/sh
266implicitly. This means that all characters, including shell metacharacters, can
267safely be passed to child processes.
268
269
270Popen Objects
271-------------
272
273Instances of the :class:`Popen` class have the following methods:
274
275
276.. method:: Popen.poll()
277
Christian Heimes7f044312008-01-06 17:05:40 +0000278 Check if child process has terminated. Set and return :attr:`returncode`
279 attribute.
Georg Brandl116aa622007-08-15 14:28:22 +0000280
281
282.. method:: Popen.wait()
283
Christian Heimes7f044312008-01-06 17:05:40 +0000284 Wait for child process to terminate. Set and return :attr:`returncode`
285 attribute.
Georg Brandl116aa622007-08-15 14:28:22 +0000286
Georg Brandl734e2682008-08-12 08:18:18 +0000287 .. warning::
288
289 This will deadlock if the child process generates enough output to a
290 stdout or stderr pipe such that it blocks waiting for the OS pipe buffer
291 to accept more data. Use :meth:`communicate` to avoid that.
292
Georg Brandl116aa622007-08-15 14:28:22 +0000293
294.. method:: Popen.communicate(input=None)
295
296 Interact with process: Send data to stdin. Read data from stdout and stderr,
297 until end-of-file is reached. Wait for process to terminate. The optional
Georg Brandle11787a2008-07-01 19:10:52 +0000298 *input* argument should be a byte string to be sent to the child process, or
Georg Brandl116aa622007-08-15 14:28:22 +0000299 ``None``, if no data should be sent to the child.
300
Georg Brandlaf265f42008-12-07 15:06:20 +0000301 :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
Georg Brandl116aa622007-08-15 14:28:22 +0000302
Guido van Rossum0d3fb8a2007-11-26 23:23:18 +0000303 Note that if you want to send data to the process's stdin, you need to create
304 the Popen object with ``stdin=PIPE``. Similarly, to get anything other than
305 ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
306 ``stderr=PIPE`` too.
307
Christian Heimes7f044312008-01-06 17:05:40 +0000308 .. note::
Georg Brandl116aa622007-08-15 14:28:22 +0000309
Christian Heimes7f044312008-01-06 17:05:40 +0000310 The data read is buffered in memory, so do not use this method if the data
311 size is large or unlimited.
312
Georg Brandl116aa622007-08-15 14:28:22 +0000313
Christian Heimesa342c012008-04-20 21:01:16 +0000314.. method:: Popen.send_signal(signal)
315
316 Sends the signal *signal* to the child.
317
318 .. note::
319
320 On Windows only SIGTERM is supported so far. It's an alias for
321 :meth:`terminate`.
322
Christian Heimesa342c012008-04-20 21:01:16 +0000323
324.. method:: Popen.terminate()
325
326 Stop the child. On Posix OSs the method sends SIGTERM to the
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000327 child. On Windows the Win32 API function :cfunc:`TerminateProcess` is called
Christian Heimesa342c012008-04-20 21:01:16 +0000328 to stop the child.
329
Christian Heimesa342c012008-04-20 21:01:16 +0000330
331.. method:: Popen.kill()
332
333 Kills the child. On Posix OSs the function sends SIGKILL to the child.
334 On Windows :meth:`kill` is an alias for :meth:`terminate`.
335
Christian Heimesa342c012008-04-20 21:01:16 +0000336
Georg Brandl116aa622007-08-15 14:28:22 +0000337The following attributes are also available:
338
Georg Brandl734e2682008-08-12 08:18:18 +0000339.. warning::
340
Georg Brandle720c0a2009-04-27 16:20:50 +0000341 Use :meth:`communicate` rather than :attr:`.stdin.write <stdin>`,
342 :attr:`.stdout.read <stdout>` or :attr:`.stderr.read <stderr>` to avoid
343 deadlocks due to any of the other OS pipe buffers filling up and blocking the
344 child process.
Georg Brandl734e2682008-08-12 08:18:18 +0000345
346
Georg Brandl116aa622007-08-15 14:28:22 +0000347.. attribute:: Popen.stdin
348
Georg Brandlaf265f42008-12-07 15:06:20 +0000349 If the *stdin* argument was :data:`PIPE`, this attribute is a file object
350 that provides input to the child process. Otherwise, it is ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000351
352
353.. attribute:: Popen.stdout
354
Georg Brandlaf265f42008-12-07 15:06:20 +0000355 If the *stdout* argument was :data:`PIPE`, this attribute is a file object
356 that provides output from the child process. Otherwise, it is ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000357
358
359.. attribute:: Popen.stderr
360
Georg Brandlaf265f42008-12-07 15:06:20 +0000361 If the *stderr* argument was :data:`PIPE`, this attribute is a file object
362 that provides error output from the child process. Otherwise, it is
363 ``None``.
Georg Brandl116aa622007-08-15 14:28:22 +0000364
365
366.. attribute:: Popen.pid
367
368 The process ID of the child process.
369
370
371.. attribute:: Popen.returncode
372
Christian Heimes7f044312008-01-06 17:05:40 +0000373 The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
374 by :meth:`communicate`). A ``None`` value indicates that the process
375 hasn't terminated yet.
Georg Brandl48310cd2009-01-03 21:18:54 +0000376
Christian Heimes7f044312008-01-06 17:05:40 +0000377 A negative value ``-N`` indicates that the child was terminated by signal
378 ``N`` (Unix only).
Georg Brandl116aa622007-08-15 14:28:22 +0000379
380
Benjamin Petersondcf97b92008-07-02 17:30:14 +0000381.. _subprocess-replacements:
382
Georg Brandl116aa622007-08-15 14:28:22 +0000383Replacing Older Functions with the subprocess Module
384----------------------------------------------------
385
386In this section, "a ==> b" means that b can be used as a replacement for a.
387
388.. note::
389
390 All functions in this section fail (more or less) silently if the executed
391 program cannot be found; this module raises an :exc:`OSError` exception.
392
393In the following examples, we assume that the subprocess module is imported with
394"from subprocess import \*".
395
396
397Replacing /bin/sh shell backquote
398^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
399
400::
401
402 output=`mycmd myarg`
403 ==>
404 output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
405
406
Benjamin Petersonf10a79a2008-10-11 00:49:57 +0000407Replacing shell pipeline
408^^^^^^^^^^^^^^^^^^^^^^^^
Georg Brandl116aa622007-08-15 14:28:22 +0000409
410::
411
412 output=`dmesg | grep hda`
413 ==>
414 p1 = Popen(["dmesg"], stdout=PIPE)
415 p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
416 output = p2.communicate()[0]
417
418
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000419Replacing :func:`os.system`
420^^^^^^^^^^^^^^^^^^^^^^^^^^^
Georg Brandl116aa622007-08-15 14:28:22 +0000421
422::
423
424 sts = os.system("mycmd" + " myarg")
425 ==>
426 p = Popen("mycmd" + " myarg", shell=True)
Georg Brandld80344f2009-08-13 12:26:19 +0000427 sts = os.waitpid(p.pid, 0)[1]
Georg Brandl116aa622007-08-15 14:28:22 +0000428
429Notes:
430
431* Calling the program through the shell is usually not required.
432
433* It's easier to look at the :attr:`returncode` attribute than the exit status.
434
435A more realistic example would look like this::
436
437 try:
438 retcode = call("mycmd" + " myarg", shell=True)
439 if retcode < 0:
Collin Winterc79461b2007-09-01 23:34:30 +0000440 print("Child was terminated by signal", -retcode, file=sys.stderr)
Georg Brandl116aa622007-08-15 14:28:22 +0000441 else:
Collin Winterc79461b2007-09-01 23:34:30 +0000442 print("Child returned", retcode, file=sys.stderr)
Georg Brandl116aa622007-08-15 14:28:22 +0000443 except OSError as e:
Collin Winterc79461b2007-09-01 23:34:30 +0000444 print("Execution failed:", e, file=sys.stderr)
Georg Brandl116aa622007-08-15 14:28:22 +0000445
446
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000447Replacing the :func:`os.spawn <os.spawnl>` family
448^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Georg Brandl116aa622007-08-15 14:28:22 +0000449
450P_NOWAIT example::
451
452 pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
453 ==>
454 pid = Popen(["/bin/mycmd", "myarg"]).pid
455
456P_WAIT example::
457
458 retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
459 ==>
460 retcode = call(["/bin/mycmd", "myarg"])
461
462Vector example::
463
464 os.spawnvp(os.P_NOWAIT, path, args)
465 ==>
466 Popen([path] + args[1:])
467
468Environment example::
469
470 os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
471 ==>
472 Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
473
474
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000475
476Replacing :func:`os.popen`, :func:`os.popen2`, :func:`os.popen3`
477^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Georg Brandl116aa622007-08-15 14:28:22 +0000478
479::
480
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000481 (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
Georg Brandl116aa622007-08-15 14:28:22 +0000482 ==>
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000483 p = Popen(cmd, shell=True, bufsize=bufsize,
484 stdin=PIPE, stdout=PIPE, close_fds=True)
485 (child_stdin, child_stdout) = (p.stdin, p.stdout)
Georg Brandl116aa622007-08-15 14:28:22 +0000486
487::
488
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000489 (child_stdin,
490 child_stdout,
491 child_stderr) = os.popen3(cmd, mode, bufsize)
Georg Brandl116aa622007-08-15 14:28:22 +0000492 ==>
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000493 p = Popen(cmd, shell=True, bufsize=bufsize,
494 stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
495 (child_stdin,
496 child_stdout,
497 child_stderr) = (p.stdin, p.stdout, p.stderr)
498
499::
500
501 (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
502 ==>
503 p = Popen(cmd, shell=True, bufsize=bufsize,
504 stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
505 (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
506
507Return code handling translates as follows::
508
509 pipe = os.popen(cmd, 'w')
510 ...
511 rc = pipe.close()
512 if rc != None and rc % 256:
Ezio Melotti713e0422009-09-13 08:13:21 +0000513 print("There were some errors")
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000514 ==>
515 process = Popen(cmd, 'w', stdin=PIPE)
516 ...
517 process.stdin.close()
518 if process.wait() != 0:
Ezio Melotti713e0422009-09-13 08:13:21 +0000519 print("There were some errors")
Benjamin Peterson87c8d872009-06-11 22:54:11 +0000520
521
522Replacing functions from the :mod:`popen2` module
523^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
524
525.. note::
526
527 If the cmd argument to popen2 functions is a string, the command is executed
528 through /bin/sh. If it is a list, the command is directly executed.
529
530::
531
532 (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
533 ==>
534 p = Popen(["somestring"], shell=True, bufsize=bufsize,
535 stdin=PIPE, stdout=PIPE, close_fds=True)
536 (child_stdout, child_stdin) = (p.stdout, p.stdin)
537
538::
539
540 (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
541 ==>
542 p = Popen(["mycmd", "myarg"], bufsize=bufsize,
543 stdin=PIPE, stdout=PIPE, close_fds=True)
544 (child_stdout, child_stdin) = (p.stdout, p.stdin)
545
546:class:`popen2.Popen3` and :class:`popen2.Popen4` basically work as
547:class:`subprocess.Popen`, except that:
548
549* :class:`Popen` raises an exception if the execution fails.
550
551* the *capturestderr* argument is replaced with the *stderr* argument.
552
553* ``stdin=PIPE`` and ``stdout=PIPE`` must be specified.
554
555* popen2 closes all file descriptors by default, but you have to specify
556 ``close_fds=True`` with :class:`Popen`.