rest25/library/popen2.rst => rest262/library/popen2.rst
f1
2:mod:`popen2` --- Subprocesses with accessible I/O streams
3==========================================================
4
5.. module:: popen2
n6-   :platform: Unix, Windows
7   :synopsis: Subprocesses with accessible standard I/O streams.
n7+   :deprecated:
8.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
9
n10+ 
11+.. deprecated:: 2.6
12+   This module is obsolete.  Use the :mod:`subprocess` module.  Check
13+   especially the :ref:`subprocess-replacements` section.
10
11This module allows you to spawn processes and connect to their
12input/output/error pipes and obtain their return codes under Unix and Windows.
13
n14-Note that starting with Python 2.0, this functionality is available using
n18+The :mod:`subprocess` module provides more powerful facilities for spawning new
15-functions from the :mod:`os` module which have the same names as the factory
19+processes and retrieving their results.  Using the :mod:`subprocess` module is
16-functions here, but the order of the return values is more intuitive in the
20+preferable to using the :mod:`popen2` module.
17-:mod:`os` module variants.
18
19The primary interface offered by this module is a trio of factory functions.
20For each of these, if *bufsize* is specified,  it specifies the buffer size for
21the I/O pipes.  *mode*, if provided, should be the string ``'b'`` or ``'t'``; on
22Windows this is needed to determine whether the file objects should be opened in
23binary or text mode.  The default value for *mode* is ``'t'``.
24
25On Unix, *cmd* may be a sequence, in which case arguments will be passed
86
87Popen3 and Popen4 Objects
88-------------------------
89
90Instances of the :class:`Popen3` and :class:`Popen4` classes have the following
91methods:
92
93
n94-.. method:: XXX Class.poll()
n97+.. method:: Popen3.poll()
95
n96-   Returns ``-1`` if child process hasn't completed yet, or its return  code
n99+   Returns ``-1`` if child process hasn't completed yet, or its status code
97-   otherwise.
100+   (see :meth:`wait`) otherwise.
98
99
n100-.. method:: XXX Class.wait()
n103+.. method:: Popen3.wait()
101
102   Waits for and returns the status code of the child process.  The status code
103   encodes both the return code of the process and information about whether it
104   exited using the :cfunc:`exit` system call or died due to a signal.  Functions
105   to help interpret the status code are defined in the :mod:`os` module; see
106   section :ref:`os-process` for the :func:`W\*` family of functions.
107
108The following attributes are also available:
109
110
n111-.. attribute:: XXX Class.fromchild
n114+.. attribute:: Popen3.fromchild
112
113   A file object that provides output from the child process.  For :class:`Popen4`
114   instances, this will provide both the standard output and standard error
115   streams.
116
117
n118-.. attribute:: XXX Class.tochild
n121+.. attribute:: Popen3.tochild
119
120   A file object that provides input to the child process.
121
122
n123-.. attribute:: XXX Class.childerr
n126+.. attribute:: Popen3.childerr
124
125   A file object that provides error output from the child process, if
126   *capturestderr* was true for the constructor, otherwise ``None``.  This will
127   always be ``None`` for :class:`Popen4` instances.
128
129
n130-.. attribute:: XXX Class.pid
n133+.. attribute:: Popen3.pid
131
132   The process ID of the child process.
133
134
135.. _popen2-flow-control:
136
137Flow Control Issues
138-------------------
141flow needs to be carefully thought out.  This remains the case with the file
142objects provided by this module (or the :mod:`os` module equivalents).
143
144When reading output from a child process that writes a lot of data to standard
145error while the parent is reading from the child's standard output, a deadlock
146can occur.  A similar situation can occur with other combinations of reads and
147writes.  The essential factors are that more than :const:`_PC_PIPE_BUF` bytes
148are being written by one process in a blocking fashion, while the other process
n149-is reading from the other process, also in a blocking fashion.
n152+is reading from the first process, also in a blocking fashion.
150
n151-.. % Example explanation and suggested work-arounds substantially stolen
n154+.. Example explanation and suggested work-arounds substantially stolen
152-.. % from Martin von Löwis:
155+   from Martin von Löwis:
153-.. % http://mail.python.org/pipermail/python-dev/2000-September/009460.html
156+   http://mail.python.org/pipermail/python-dev/2000-September/009460.html
154
155There are several ways to deal with this situation.
156
157The simplest application change, in many cases, will be to follow this model in
158the parent process::
159
160   import popen2
161
183used, as ``sys.stderr.close()`` won't close ``stderr`` (otherwise assigning to
184``sys.stderr`` will silently close it, so no further errors can be printed).
185
186Applications which need to support a more general approach should integrate I/O
187over pipes with their :func:`select` loops, or use separate threads to read each
188of the individual files provided by whichever :func:`popen\*` function or
189:class:`Popen\*` class was used.
190
t194+ 
195+.. seealso::
196+ 
197+   Module :mod:`subprocess`
198+      Module for spawning and managing subprocesses.
199+ 
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op