← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.11-docs-html/_sources/library/popen2.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-2.7.11-docs-html/_sources/library/popen2.txt
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
 
 
15
 
This module allows you to spawn processes and connect to their
16
 
input/output/error pipes and obtain their return codes under Unix and Windows.
17
 
 
18
 
The :mod:`subprocess` module provides more powerful facilities for spawning new
19
 
processes and retrieving their results.  Using the :mod:`subprocess` module is
20
 
preferable to using the :mod:`popen2` module.
21
 
 
22
 
The primary interface offered by this module is a trio of factory functions.
23
 
For each of these, if *bufsize* is specified,  it specifies the buffer size for
24
 
the I/O pipes.  *mode*, if provided, should be the string ``'b'`` or ``'t'``; on
25
 
Windows this is needed to determine whether the file objects should be opened in
26
 
binary or text mode.  The default value for *mode* is ``'t'``.
27
 
 
28
 
On Unix, *cmd* may be a sequence, in which case arguments will be passed
29
 
directly to the program without shell intervention (as with :func:`os.spawnv`).
30
 
If *cmd* is a string it will be passed to the shell (as with :func:`os.system`).
31
 
 
32
 
The only way to retrieve the return codes for the child processes is by using
33
 
the :meth:`poll` or :meth:`wait` methods on the :class:`Popen3` and
34
 
:class:`Popen4` classes; these are only available on Unix.  This information is
35
 
not available when using the :func:`popen2`, :func:`popen3`, and :func:`popen4`
36
 
functions, or the equivalent functions in the :mod:`os` module. (Note that the
37
 
tuples returned by the :mod:`os` module's functions are in a different order
38
 
from 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
 
 
60
 
On Unix, a class defining the objects returned by the factory functions is also
61
 
available.  These are not used for the Windows implementation, and are not
62
 
available 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
 
 
90
 
Popen3 and Popen4 Objects
91
 
-------------------------
92
 
 
93
 
Instances of the :class:`Popen3` and :class:`Popen4` classes have the following
94
 
methods:
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
 
 
111
 
The 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
 
 
140
 
Flow Control Issues
141
 
-------------------
142
 
 
143
 
Any time you are working with any form of inter-process communication, control
144
 
flow needs to be carefully thought out.  This remains the case with the file
145
 
objects provided by this module (or the :mod:`os` module equivalents).
146
 
 
147
 
When reading output from a child process that writes a lot of data to standard
148
 
error while the parent is reading from the child's standard output, a deadlock
149
 
can occur.  A similar situation can occur with other combinations of reads and
150
 
writes.  The essential factors are that more than :const:`_PC_PIPE_BUF` bytes
151
 
are being written by one process in a blocking fashion, while the other process
152
 
is 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
 
 
158
 
There are several ways to deal with this situation.
159
 
 
160
 
The simplest application change, in many cases, will be to follow this model in
161
 
the 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
 
 
172
 
with 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
 
 
184
 
In particular, note that ``sys.stderr`` must be closed after writing all data,
185
 
or :meth:`readlines` won't return.  Also note that :func:`os.close` must be
186
 
used, 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
 
 
189
 
Applications which need to support a more general approach should integrate I/O
190
 
over pipes with their :func:`select` loops, or use separate threads to read each
191
 
of 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