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.
  13
  14 This module allows you to spawn processes and connect to their
  15 input/output/error pipes and obtain their return codes under Unix and Windows.
  16
  17 The :mod:`subprocess` module provides more powerful facilities for spawning new
  18 processes and retrieving their results.  Using the :mod:`subprocess` module is
  19 preferable to using the :mod:`popen2` module.
  20
  21 The primary interface offered by this module is a trio of factory functions.
  22 For each of these, if *bufsize* is specified,  it specifies the buffer size for
  23 the I/O pipes.  *mode*, if provided, should be the string ``'b'`` or ``'t'``; on
  24 Windows this is needed to determine whether the file objects should be opened in
  25 binary or text mode.  The default value for *mode* is ``'t'``.
  26
  27 On Unix, *cmd* may be a sequence, in which case arguments will be passed
  28 directly to the program without shell intervention (as with :func:`os.spawnv`).
  29 If *cmd* is a string it will be passed to the shell (as with :func:`os.system`).
  30
  31 The only way to retrieve the return codes for the child processes is by using
  32 the :meth:`poll` or :meth:`wait` methods on the :class:`Popen3` and
  33 :class:`Popen4` classes; these are only available on Unix.  This information is
  34 not available when using the :func:`popen2`, :func:`popen3`, and :func:`popen4`
  35 functions, or the equivalent functions in the :mod:`os` module. (Note that the
  36 tuples returned by the :mod:`os` module's functions are in a different order
  37 from the ones returned by the :mod:`popen2` module.)
  38
  39
  40 .. function:: popen2(cmd[, bufsize[, mode]])
  41
  42    Executes *cmd* as a sub-process.  Returns the file objects ``(child_stdout,
  43    child_stdin)``.
  44
  45
  46 .. function:: popen3(cmd[, bufsize[, mode]])
  47
  48    Executes *cmd* as a sub-process.  Returns the file objects ``(child_stdout,
  49    child_stdin, child_stderr)``.
  50
  51
  52 .. function:: popen4(cmd[, bufsize[, mode]])
  53
  54    Executes *cmd* as a sub-process.  Returns the file objects
  55    ``(child_stdout_and_stderr, child_stdin)``.
  56
  57    .. versionadded:: 2.0
  58
  59 On Unix, a class defining the objects returned by the factory functions is also
  60 available.  These are not used for the Windows implementation, and are not
  61 available on that platform.
  62
  63
  64 .. class:: Popen3(cmd[, capturestderr[, bufsize]])
  65
  66    This class represents a child process.  Normally, :class:`Popen3` instances are
  67    created using the :func:`popen2` and :func:`popen3` factory functions described
  68    above.
  69
  70    If not using one of the helper functions to create :class:`Popen3` objects, the
  71    parameter *cmd* is the shell command to execute in a sub-process.  The
  72    *capturestderr* flag, if true, specifies that the object should capture standard
  73    error output of the child process. The default is false.  If the *bufsize*
  74    parameter is specified, it specifies the size of the I/O buffers to/from the
  75    child process.
  76
  77
  78 .. class:: Popen4(cmd[, bufsize])
  79
  80    Similar to :class:`Popen3`, but always captures standard error into the same
  81    file object as standard output.  These are typically created using
  82    :func:`popen4`.
  83
  84    .. versionadded:: 2.0
  85
  86
  87 .. _popen3-objects:
  88
  89 Popen3 and Popen4 Objects
  90 -------------------------
  91
  92 Instances of the :class:`Popen3` and :class:`Popen4` classes have the following
  93 methods:
  94
  95
  96 .. method:: Popen3.poll()
  97
  98    Returns ``-1`` if child process hasn't completed yet, or its status code
  99    (see :meth:`wait`) otherwise.
 100
 101
 102 .. method:: Popen3.wait()
 103
 104    Waits for and returns the status code of the child process.  The status code
 105    encodes both the return code of the process and information about whether it
 106    exited using the :cfunc:`exit` system call or died due to a signal.  Functions
 107    to help interpret the status code are defined in the :mod:`os` module; see
 108    section :ref:`os-process` for the :func:`W\*` family of functions.
 109
 110 The following attributes are also available:
 111
 112
 113 .. attribute:: Popen3.fromchild
 114
 115    A file object that provides output from the child process.  For :class:`Popen4`
 116    instances, this will provide both the standard output and standard error
 117    streams.
 118
 119
 120 .. attribute:: Popen3.tochild
 121
 122    A file object that provides input to the child process.
 123
 124
 125 .. attribute:: Popen3.childerr
 126
 127    A file object that provides error output from the child process, if
 128    *capturestderr* was true for the constructor, otherwise ``None``.  This will
 129    always be ``None`` for :class:`Popen4` instances.
 130
 131
 132 .. attribute:: Popen3.pid
 133
 134    The process ID of the child process.
 135
 136
 137 .. _popen2-flow-control:
 138
 139 Flow Control Issues
 140 -------------------
 141
 142 Any time you are working with any form of inter-process communication, control
 143 flow needs to be carefully thought out.  This remains the case with the file
 144 objects provided by this module (or the :mod:`os` module equivalents).
 145
 146 When reading output from a child process that writes a lot of data to standard
 147 error while the parent is reading from the child's standard output, a deadlock
 148 can occur.  A similar situation can occur with other combinations of reads and
 149 writes.  The essential factors are that more than :const:`_PC_PIPE_BUF` bytes
 150 are being written by one process in a blocking fashion, while the other process
 151 is reading from the other process, also in a blocking fashion.
 152
 153 .. Example explanation and suggested work-arounds substantially stolen
 154    from Martin von Löwis:
 155    http://mail.python.org/pipermail/python-dev/2000-September/009460.html
 156
 157 There are several ways to deal with this situation.
 158
 159 The simplest application change, in many cases, will be to follow this model in
 160 the parent process::
 161
 162    import popen2
 163
 164    r, w, e = popen2.popen3('python slave.py')
 165    e.readlines()
 166    r.readlines()
 167    r.close()
 168    e.close()
 169    w.close()
 170
 171 with code like this in the child::
 172
 173    import os
 174    import sys
 175
 176    # note that each of these print statements
 177    # writes a single long string
 178
 179    print >>sys.stderr, 400 * 'this is a test\n'
 180    os.close(sys.stderr.fileno())
 181    print >>sys.stdout, 400 * 'this is another test\n'
 182
 183 In particular, note that ``sys.stderr`` must be closed after writing all data,
 184 or :meth:`readlines` won't return.  Also note that :func:`os.close` must be
 185 used, as ``sys.stderr.close()`` won't close ``stderr`` (otherwise assigning to
 186 ``sys.stderr`` will silently close it, so no further errors can be printed).
 187
 188 Applications which need to support a more general approach should integrate I/O
 189 over pipes with their :func:`select` loops, or use separate threads to read each
 190 of the individual files provided by whichever :func:`popen\*` function or
 191 :class:`Popen\*` class was used.
 192
 193
 194 .. seealso::
 195
 196    Module :mod:`subprocess`
 197       Module for spawning and managing subprocesses.
 198