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