sandbox/morph / Doc / library / popen2.rst

:mod:`popen2` --- Subprocesses with accessible I/O streams

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.)

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.

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.

Similar to :class:`Popen3`, but always captures standard error into the same file object as standard output. These are typically created using :func:`popen4`.

Popen3 and Popen4 Objects

Instances of the :class:`Popen3` and :class:`Popen4` classes have the following methods:

The following attributes are also available:

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 is reading from the first process, also in a blocking fashion.

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')

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'
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.