Doc/library/popen2.rst

   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 :cfunc:`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    http://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