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