cpython/Doc/library/popen2.rst

200 lines
6.9 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:01 -03:00
:mod:`popen2` --- Subprocesses with accessible I/O streams
==========================================================
.. module:: popen2
:synopsis: Subprocesses with accessible standard I/O streams.
2007-08-15 15:41:25 -03:00
:deprecated:
2007-08-15 11:28:01 -03:00
.. sectionauthor:: Drew Csillag <drew_csillag@geocities.com>
.. deprecated:: 2.6
Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68133 | antoine.pitrou | 2009-01-01 16:38:03 +0100 (Thu, 01 Jan 2009) | 1 line fill in actual issue number in tests ........ r68134 | hirokazu.yamamoto | 2009-01-01 16:45:39 +0100 (Thu, 01 Jan 2009) | 2 lines Issue #4797: IOError.filename was not set when _fileio.FileIO failed to open file with `str' filename on Windows. ........ r68141 | benjamin.peterson | 2009-01-01 17:43:12 +0100 (Thu, 01 Jan 2009) | 1 line fix highlighting ........ r68142 | benjamin.peterson | 2009-01-01 18:29:49 +0100 (Thu, 01 Jan 2009) | 2 lines welcome to 2009, Python! ........ r68145 | amaury.forgeotdarc | 2009-01-02 01:03:54 +0100 (Fri, 02 Jan 2009) | 5 lines #4801 _collections module fails to build on cygwin. _PyObject_GC_TRACK is the macro version of PyObject_GC_Track, and according to documentation it should not be used for extension modules. ........ r68146 | ronald.oussoren | 2009-01-02 11:44:46 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue4472: "configure --enable-shared doesn't work on OSX" ........ r68148 | ronald.oussoren | 2009-01-02 11:48:31 +0100 (Fri, 02 Jan 2009) | 2 lines Forgot to add a NEWS item in my previous checkin ........ r68149 | ronald.oussoren | 2009-01-02 11:50:48 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue4780 ........ r68159 | ronald.oussoren | 2009-01-02 15:48:17 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue 1627952 ........ r68160 | ronald.oussoren | 2009-01-02 15:52:09 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue r1737832 ........ r68161 | ronald.oussoren | 2009-01-02 16:00:05 +0100 (Fri, 02 Jan 2009) | 3 lines Fix for issue 1149804 ........ r68162 | ronald.oussoren | 2009-01-02 16:06:00 +0100 (Fri, 02 Jan 2009) | 3 lines Fix for issue 4472 is incompatible with Cygwin, this patch should fix that. ........ r68166 | benjamin.peterson | 2009-01-02 19:26:23 +0100 (Fri, 02 Jan 2009) | 1 line document PyMemberDef ........ r68171 | georg.brandl | 2009-01-02 21:25:14 +0100 (Fri, 02 Jan 2009) | 3 lines #4811: fix markup glitches (mostly remains of the conversion), found by Gabriel Genellina. ........ r68172 | martin.v.loewis | 2009-01-02 21:32:55 +0100 (Fri, 02 Jan 2009) | 2 lines Issue #4075: Use OutputDebugStringW in Py_FatalError. ........ r68173 | martin.v.loewis | 2009-01-02 21:40:14 +0100 (Fri, 02 Jan 2009) | 2 lines Issue #4051: Prevent conflict of UNICODE macros in cPickle. ........ r68174 | benjamin.peterson | 2009-01-02 21:47:27 +0100 (Fri, 02 Jan 2009) | 1 line fix compilation on non-Windows platforms ........ r68179 | raymond.hettinger | 2009-01-02 22:26:45 +0100 (Fri, 02 Jan 2009) | 1 line Issue #4615. Document how to use itertools for de-duping. ........ r68195 | georg.brandl | 2009-01-03 14:45:15 +0100 (Sat, 03 Jan 2009) | 2 lines Remove useless string literal. ........ r68196 | georg.brandl | 2009-01-03 15:29:53 +0100 (Sat, 03 Jan 2009) | 2 lines Fix indentation. ........ r68210 | georg.brandl | 2009-01-03 20:10:12 +0100 (Sat, 03 Jan 2009) | 2 lines Set eol-style correctly for mp_distributing.py. ........ r68214 | georg.brandl | 2009-01-03 20:44:48 +0100 (Sat, 03 Jan 2009) | 2 lines Make indentation consistent. ........ r68215 | georg.brandl | 2009-01-03 21:15:14 +0100 (Sat, 03 Jan 2009) | 2 lines Fix role name. ........ r68217 | georg.brandl | 2009-01-03 21:30:15 +0100 (Sat, 03 Jan 2009) | 2 lines Add rstlint, a little tool to find subtle markup problems and inconsistencies in the Doc sources. ........ r68218 | georg.brandl | 2009-01-03 21:38:59 +0100 (Sat, 03 Jan 2009) | 2 lines Recognize usage of the default role. ........ r68219 | georg.brandl | 2009-01-03 21:47:01 +0100 (Sat, 03 Jan 2009) | 2 lines Fix uses of the default role. ........ r68220 | georg.brandl | 2009-01-03 21:55:06 +0100 (Sat, 03 Jan 2009) | 2 lines Remove trailing whitespace. ........ r68221 | georg.brandl | 2009-01-03 22:04:55 +0100 (Sat, 03 Jan 2009) | 2 lines Remove tabs from the documentation. ........ r68222 | georg.brandl | 2009-01-03 22:11:58 +0100 (Sat, 03 Jan 2009) | 2 lines Disable the line length checker by default. ........
2009-01-03 17:55:17 -04:00
This module is obsolete. Use the :mod:`subprocess` module. Check
especially the :ref:`subprocess-replacements` section.
2007-08-15 11:28:01 -03:00
This module allows you to spawn processes and connect to their
input/output/error pipes and obtain their return codes under Unix and Windows.
The :mod:`subprocess` module provides more powerful facilities for spawning new
processes and retrieving their results. Using the :mod:`subprocess` module is
preferable to using the :mod:`popen2` module.
The primary interface offered by this module is a trio of factory functions.
For each of these, if *bufsize* is specified, it specifies the buffer size for
the I/O pipes. *mode*, if provided, should be the string ``'b'`` or ``'t'``; on
Windows this is needed to determine whether the file objects should be opened in
binary or text mode. The default value for *mode* is ``'t'``.
On Unix, *cmd* may be a sequence, in which case arguments will be passed
directly to the program without shell intervention (as with :func:`os.spawnv`).
If *cmd* is a string it will be passed to the shell (as with :func:`os.system`).
The only way to retrieve the return codes for the child processes is by using
the :meth:`poll` or :meth:`wait` methods on the :class:`Popen3` and
:class:`Popen4` classes; these are only available on Unix. This information is
not available when using the :func:`popen2`, :func:`popen3`, and :func:`popen4`
functions, or the equivalent functions in the :mod:`os` module. (Note that the
tuples returned by the :mod:`os` module's functions are in a different order
from the ones returned by the :mod:`popen2` module.)
.. function:: popen2(cmd[, bufsize[, mode]])
Executes *cmd* as a sub-process. Returns the file objects ``(child_stdout,
child_stdin)``.
.. function:: popen3(cmd[, bufsize[, mode]])
Executes *cmd* as a sub-process. Returns the file objects ``(child_stdout,
child_stdin, child_stderr)``.
.. function:: popen4(cmd[, bufsize[, mode]])
Executes *cmd* as a sub-process. Returns the file objects
``(child_stdout_and_stderr, child_stdin)``.
.. versionadded:: 2.0
On Unix, a class defining the objects returned by the factory functions is also
available. These are not used for the Windows implementation, and are not
available on that platform.
.. class:: Popen3(cmd[, capturestderr[, bufsize]])
This class represents a child process. Normally, :class:`Popen3` instances are
created using the :func:`popen2` and :func:`popen3` factory functions described
above.
If not using one of the helper functions to create :class:`Popen3` objects, the
parameter *cmd* is the shell command to execute in a sub-process. The
*capturestderr* flag, if true, specifies that the object should capture standard
error output of the child process. The default is false. If the *bufsize*
parameter is specified, it specifies the size of the I/O buffers to/from the
child process.
.. class:: Popen4(cmd[, bufsize])
Similar to :class:`Popen3`, but always captures standard error into the same
file object as standard output. These are typically created using
:func:`popen4`.
.. versionadded:: 2.0
.. _popen3-objects:
Popen3 and Popen4 Objects
-------------------------
Instances of the :class:`Popen3` and :class:`Popen4` classes have the following
methods:
.. method:: Popen3.poll()
Returns ``-1`` if child process hasn't completed yet, or its status code
(see :meth:`wait`) otherwise.
2007-08-15 11:28:01 -03:00
.. method:: Popen3.wait()
Waits for and returns the status code of the child process. The status code
encodes both the return code of the process and information about whether it
exited using the :cfunc:`exit` system call or died due to a signal. Functions
to help interpret the status code are defined in the :mod:`os` module; see
section :ref:`os-process` for the :func:`W\*` family of functions.
The following attributes are also available:
.. attribute:: Popen3.fromchild
A file object that provides output from the child process. For :class:`Popen4`
instances, this will provide both the standard output and standard error
streams.
.. attribute:: Popen3.tochild
A file object that provides input to the child process.
.. attribute:: Popen3.childerr
A file object that provides error output from the child process, if
*capturestderr* was true for the constructor, otherwise ``None``. This will
always be ``None`` for :class:`Popen4` instances.
.. attribute:: Popen3.pid
The process ID of the child process.
.. _popen2-flow-control:
Flow Control Issues
-------------------
Any time you are working with any form of inter-process communication, control
flow needs to be carefully thought out. This remains the case with the file
objects provided by this module (or the :mod:`os` module equivalents).
When reading output from a child process that writes a lot of data to standard
error while the parent is reading from the child's standard output, a deadlock
can occur. A similar situation can occur with other combinations of reads and
writes. The essential factors are that more than :const:`_PC_PIPE_BUF` bytes
are being written by one process in a blocking fashion, while the other process
2008-07-28 14:04:48 -03:00
is reading from the first process, also in a blocking fashion.
2007-08-15 11:28:01 -03:00
2007-12-29 06:57:00 -04:00
.. Example explanation and suggested work-arounds substantially stolen
from Martin von Löwis:
http://mail.python.org/pipermail/python-dev/2000-September/009460.html
2007-08-15 11:28:01 -03:00
There are several ways to deal with this situation.
The simplest application change, in many cases, will be to follow this model in
the parent process::
import popen2
r, w, e = popen2.popen3('python slave.py')
e.readlines()
r.readlines()
r.close()
e.close()
w.close()
with code like this in the child::
import os
import sys
# note that each of these print statements
# writes a single long string
print >>sys.stderr, 400 * 'this is a test\n'
os.close(sys.stderr.fileno())
print >>sys.stdout, 400 * 'this is another test\n'
In particular, note that ``sys.stderr`` must be closed after writing all data,
or :meth:`readlines` won't return. Also note that :func:`os.close` must be
used, as ``sys.stderr.close()`` won't close ``stderr`` (otherwise assigning to
``sys.stderr`` will silently close it, so no further errors can be printed).
Applications which need to support a more general approach should integrate I/O
over pipes with their :func:`select` loops, or use separate threads to read each
of the individual files provided by whichever :func:`popen\*` function or
:class:`Popen\*` class was used.
.. seealso::
Module :mod:`subprocess`
Module for spawning and managing subprocesses.