f | |
| :mod:`popen2` --- Subprocesses with accessible I/O streams |
| ========================================================== |
| |
| .. module:: popen2 |
n | :platform: Unix, Windows |
| :synopsis: Subprocesses with accessible standard I/O streams. |
n | :deprecated: |
| .. sectionauthor:: Drew Csillag <drew_csillag@geocities.com> |
| |
n | |
| .. deprecated:: 2.6 |
| This module is obsolete. Use the :mod:`subprocess` module. Check |
| especially the :ref:`subprocess-replacements` section. |
| |
| This module allows you to spawn processes and connect to their |
| input/output/error pipes and obtain their return codes under Unix and Windows. |
| |
n | Note that starting with Python 2.0, this functionality is available using |
n | The :mod:`subprocess` module provides more powerful facilities for spawning new |
| functions from the :mod:`os` module which have the same names as the factory |
| processes and retrieving their results. Using the :mod:`subprocess` module is |
| functions here, but the order of the return values is more intuitive in the |
| preferable to using the :mod:`popen2` module. |
| :mod:`os` module variants. |
| |
| 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 |
| |
| Popen3 and Popen4 Objects |
| ------------------------- |
| |
| Instances of the :class:`Popen3` and :class:`Popen4` classes have the following |
| methods: |
| |
| |
n | .. method:: XXX Class.poll() |
n | .. method:: Popen3.poll() |
| |
n | Returns ``-1`` if child process hasn't completed yet, or its return code |
n | Returns ``-1`` if child process hasn't completed yet, or its status code |
| otherwise. |
| (see :meth:`wait`) otherwise. |
| |
| |
n | .. method:: XXX Class.wait() |
n | .. 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: |
| |
| |
n | .. attribute:: XXX Class.fromchild |
n | .. 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. |
| |
| |
n | .. attribute:: XXX Class.tochild |
n | .. attribute:: Popen3.tochild |
| |
| A file object that provides input to the child process. |
| |
| |
n | .. attribute:: XXX Class.childerr |
n | .. 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. |
| |
| |
n | .. attribute:: XXX Class.pid |
n | .. attribute:: Popen3.pid |
| |
| The process ID of the child process. |
| |
| |
| .. _popen2-flow-control: |
| |
| Flow Control Issues |
| ------------------- |
| 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 |
n | is reading from the other process, also in a blocking fashion. |
n | is reading from the first process, also in a blocking fashion. |
| |
n | .. % Example explanation and suggested work-arounds substantially stolen |
n | .. Example explanation and suggested work-arounds substantially stolen |
| .. % from Martin von Löwis: |
| from Martin von Löwis: |
| .. % http://mail.python.org/pipermail/python-dev/2000-September/009460.html |
| http://mail.python.org/pipermail/python-dev/2000-September/009460.html |
| |
| 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 |
| |
| 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. |
| |
t | |
| .. seealso:: |
| |
| Module :mod:`subprocess` |
| Module for spawning and managing subprocesses. |
| |