1 2:mod:`popen2` --- Subprocesses with accessible I/O streams 3========================================================== 4 5.. module:: popen2 6 :synopsis: Subprocesses with accessible standard I/O streams. 7 :deprecated: 8.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com> 9 10 11.. deprecated:: 2.6 12 This module is obsolete. Use the :mod:`subprocess` module. Check 13 especially the :ref:`subprocess-replacements` section. 14 15This module allows you to spawn processes and connect to their 16input/output/error pipes and obtain their return codes under Unix and Windows. 17 18The :mod:`subprocess` module provides more powerful facilities for spawning new 19processes and retrieving their results. Using the :mod:`subprocess` module is 20preferable to using the :mod:`popen2` module. 21 22The primary interface offered by this module is a trio of factory functions. 23For each of these, if *bufsize* is specified, it specifies the buffer size for 24the I/O pipes. *mode*, if provided, should be the string ``'b'`` or ``'t'``; on 25Windows this is needed to determine whether the file objects should be opened in 26binary or text mode. The default value for *mode* is ``'t'``. 27 28On Unix, *cmd* may be a sequence, in which case arguments will be passed 29directly to the program without shell intervention (as with :func:`os.spawnv`). 30If *cmd* is a string it will be passed to the shell (as with :func:`os.system`). 31 32The only way to retrieve the return codes for the child processes is by using 33the :meth:`poll` or :meth:`wait` methods on the :class:`Popen3` and 34:class:`Popen4` classes; these are only available on Unix. This information is 35not available when using the :func:`popen2`, :func:`popen3`, and :func:`popen4` 36functions, or the equivalent functions in the :mod:`os` module. (Note that the 37tuples returned by the :mod:`os` module's functions are in a different order 38from the ones returned by the :mod:`popen2` module.) 39 40 41.. function:: popen2(cmd[, bufsize[, mode]]) 42 43 Executes *cmd* as a sub-process. Returns the file objects ``(child_stdout, 44 child_stdin)``. 45 46 47.. function:: popen3(cmd[, bufsize[, mode]]) 48 49 Executes *cmd* as a sub-process. Returns the file objects ``(child_stdout, 50 child_stdin, child_stderr)``. 51 52 53.. function:: popen4(cmd[, bufsize[, mode]]) 54 55 Executes *cmd* as a sub-process. Returns the file objects 56 ``(child_stdout_and_stderr, child_stdin)``. 57 58 .. versionadded:: 2.0 59 60On Unix, a class defining the objects returned by the factory functions is also 61available. These are not used for the Windows implementation, and are not 62available on that platform. 63 64 65.. class:: Popen3(cmd[, capturestderr[, bufsize]]) 66 67 This class represents a child process. Normally, :class:`Popen3` instances are 68 created using the :func:`popen2` and :func:`popen3` factory functions described 69 above. 70 71 If not using one of the helper functions to create :class:`Popen3` objects, the 72 parameter *cmd* is the shell command to execute in a sub-process. The 73 *capturestderr* flag, if true, specifies that the object should capture standard 74 error output of the child process. The default is false. If the *bufsize* 75 parameter is specified, it specifies the size of the I/O buffers to/from the 76 child process. 77 78 79.. class:: Popen4(cmd[, bufsize]) 80 81 Similar to :class:`Popen3`, but always captures standard error into the same 82 file object as standard output. These are typically created using 83 :func:`popen4`. 84 85 .. versionadded:: 2.0 86 87 88.. _popen3-objects: 89 90Popen3 and Popen4 Objects 91------------------------- 92 93Instances of the :class:`Popen3` and :class:`Popen4` classes have the following 94methods: 95 96 97.. method:: Popen3.poll() 98 99 Returns ``-1`` if child process hasn't completed yet, or its status code 100 (see :meth:`wait`) otherwise. 101 102 103.. method:: Popen3.wait() 104 105 Waits for and returns the status code of the child process. The status code 106 encodes both the return code of the process and information about whether it 107 exited using the :c:func:`exit` system call or died due to a signal. Functions 108 to help interpret the status code are defined in the :mod:`os` module; see 109 section :ref:`os-process` for the :func:`W\*` family of functions. 110 111The following attributes are also available: 112 113 114.. attribute:: Popen3.fromchild 115 116 A file object that provides output from the child process. For :class:`Popen4` 117 instances, this will provide both the standard output and standard error 118 streams. 119 120 121.. attribute:: Popen3.tochild 122 123 A file object that provides input to the child process. 124 125 126.. attribute:: Popen3.childerr 127 128 A file object that provides error output from the child process, if 129 *capturestderr* was true for the constructor, otherwise ``None``. This will 130 always be ``None`` for :class:`Popen4` instances. 131 132 133.. attribute:: Popen3.pid 134 135 The process ID of the child process. 136 137 138.. _popen2-flow-control: 139 140Flow Control Issues 141------------------- 142 143Any time you are working with any form of inter-process communication, control 144flow needs to be carefully thought out. This remains the case with the file 145objects provided by this module (or the :mod:`os` module equivalents). 146 147When reading output from a child process that writes a lot of data to standard 148error while the parent is reading from the child's standard output, a deadlock 149can occur. A similar situation can occur with other combinations of reads and 150writes. The essential factors are that more than :const:`_PC_PIPE_BUF` bytes 151are being written by one process in a blocking fashion, while the other process 152is reading from the first process, also in a blocking fashion. 153 154.. Example explanation and suggested work-arounds substantially stolen 155 from Martin von Löwis: 156 https://mail.python.org/pipermail/python-dev/2000-September/009460.html 157 158There are several ways to deal with this situation. 159 160The simplest application change, in many cases, will be to follow this model in 161the parent process:: 162 163 import popen2 164 165 r, w, e = popen2.popen3('python slave.py') 166 e.readlines() 167 r.readlines() 168 r.close() 169 e.close() 170 w.close() 171 172with code like this in the child:: 173 174 import os 175 import sys 176 177 # note that each of these print statements 178 # writes a single long string 179 180 print >>sys.stderr, 400 * 'this is a test\n' 181 os.close(sys.stderr.fileno()) 182 print >>sys.stdout, 400 * 'this is another test\n' 183 184In particular, note that ``sys.stderr`` must be closed after writing all data, 185or :meth:`readlines` won't return. Also note that :func:`os.close` must be 186used, as ``sys.stderr.close()`` won't close ``stderr`` (otherwise assigning to 187``sys.stderr`` will silently close it, so no further errors can be printed). 188 189Applications which need to support a more general approach should integrate I/O 190over pipes with their :func:`select` loops, or use separate threads to read each 191of the individual files provided by whichever :func:`popen\*` function or 192:class:`Popen\*` class was used. 193 194 195.. seealso:: 196 197 Module :mod:`subprocess` 198 Module for spawning and managing subprocesses. 199 200