Doc/library/subprocess.rst

   1
   2 :mod:`subprocess` --- Subprocess management
   3 ===========================================
   4
   5 .. module:: subprocess
   6    :synopsis: Subprocess management.
   7 .. moduleauthor:: Peter Åstrand <astrand@lysator.liu.se>
   8 .. sectionauthor:: Peter Åstrand <astrand@lysator.liu.se>
   9
  10
  11 .. versionadded:: 2.4
  12
  13 The :mod:`subprocess` module allows you to spawn new processes, connect to their
  14 input/output/error pipes, and obtain their return codes.  This module intends to
  15 replace several other, older modules and functions, such as::
  16
  17    os.system
  18    os.spawn*
  19    os.popen*
  20    popen2.*
  21    commands.*
  22
  23 Information about how the :mod:`subprocess` module can be used to replace these
  24 modules and functions can be found in the following sections.
  25
  26
  27 Using the subprocess Module
  28 ---------------------------
  29
  30 This module defines one class called :class:`Popen`:
  31
  32
  33 .. class:: Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0)
  34
  35    Arguments are:
  36
  37    *args* should be a string, or a sequence of program arguments.  The program to
  38    execute is normally the first item in the args sequence or string, but can be
  39    explicitly set by using the executable argument.
  40
  41    On Unix, with *shell=False* (default): In this case, the Popen class uses
  42    :meth:`os.execvp` to execute the child program. *args* should normally be a
  43    sequence.  A string will be treated as a sequence with the string as the only
  44    item (the program to execute).
  45
  46    On Unix, with *shell=True*: If args is a string, it specifies the command string
  47    to execute through the shell.  If *args* is a sequence, the first item specifies
  48    the command string, and any additional items will be treated as additional shell
  49    arguments.
  50
  51    On Windows: the :class:`Popen` class uses CreateProcess() to execute the child
  52    program, which operates on strings.  If *args* is a sequence, it will be
  53    converted to a string using the :meth:`list2cmdline` method.  Please note that
  54    not all MS Windows applications interpret the command line the same way:
  55    :meth:`list2cmdline` is designed for applications using the same rules as the MS
  56    C runtime.
  57
  58    *bufsize*, if given, has the same meaning as the corresponding argument to the
  59    built-in open() function: :const:`0` means unbuffered, :const:`1` means line
  60    buffered, any other positive value means use a buffer of (approximately) that
  61    size.  A negative *bufsize* means to use the system default, which usually means
  62    fully buffered.  The default value for *bufsize* is :const:`0` (unbuffered).
  63
  64    The *executable* argument specifies the program to execute. It is very seldom
  65    needed: Usually, the program to execute is defined by the *args* argument. If
  66    ``shell=True``, the *executable* argument specifies which shell to use. On Unix,
  67    the default shell is :file:`/bin/sh`.  On Windows, the default shell is
  68    specified by the :envvar:`COMSPEC` environment variable.
  69
  70    *stdin*, *stdout* and *stderr* specify the executed programs' standard input,
  71    standard output and standard error file handles, respectively.  Valid values are
  72    ``PIPE``, an existing file descriptor (a positive integer), an existing file
  73    object, and ``None``.  ``PIPE`` indicates that a new pipe to the child should be
  74    created.  With ``None``, no redirection will occur; the child's file handles
  75    will be inherited from the parent.  Additionally, *stderr* can be ``STDOUT``,
  76    which indicates that the stderr data from the applications should be captured
  77    into the same file handle as for stdout.
  78
  79    If *preexec_fn* is set to a callable object, this object will be called in the
  80    child process just before the child is executed. (Unix only)
  81
  82    If *close_fds* is true, all file descriptors except :const:`0`, :const:`1` and
  83    :const:`2` will be closed before the child process is executed. (Unix only).
  84    Or, on Windows, if *close_fds* is true then no handles will be inherited by the
  85    child process.  Note that on Windows, you cannot set *close_fds* to true and
  86    also redirect the standard handles by setting *stdin*, *stdout* or *stderr*.
  87
  88    If *shell* is :const:`True`, the specified command will be executed through the
  89    shell.
  90
  91    If *cwd* is not ``None``, the child's current directory will be changed to *cwd*
  92    before it is executed.  Note that this directory is not considered when
  93    searching the executable, so you can't specify the program's path relative to
  94    *cwd*.
  95
  96    If *env* is not ``None``, it defines the environment variables for the new
  97    process.
  98
  99    If *universal_newlines* is :const:`True`, the file objects stdout and stderr are
 100    opened as text files, but lines may be terminated by any of ``'\n'``, the Unix
 101    end-of-line convention, ``'\r'``, the Macintosh convention or ``'\r\n'``, the
 102    Windows convention. All of these external representations are seen as ``'\n'``
 103    by the Python program.
 104
 105    .. note::
 106
 107       This feature is only available if Python is built with universal newline support
 108       (the default).  Also, the newlines attribute of the file objects :attr:`stdout`,
 109       :attr:`stdin` and :attr:`stderr` are not updated by the communicate() method.
 110
 111    The *startupinfo* and *creationflags*, if given, will be passed to the
 112    underlying CreateProcess() function.  They can specify things such as appearance
 113    of the main window and priority for the new process.  (Windows only)
 114
 115
 116 Convenience Functions
 117 ^^^^^^^^^^^^^^^^^^^^^
 118
 119 This module also defines two shortcut functions:
 120
 121
 122 .. function:: call(*popenargs, **kwargs)
 123
 124    Run command with arguments.  Wait for command to complete, then return the
 125    :attr:`returncode` attribute.
 126
 127    The arguments are the same as for the Popen constructor.  Example::
 128
 129       retcode = call(["ls", "-l"])
 130
 131
 132 .. function:: check_call(*popenargs, **kwargs)
 133
 134    Run command with arguments.  Wait for command to complete. If the exit code was
 135    zero then return, otherwise raise :exc:`CalledProcessError.` The
 136    :exc:`CalledProcessError` object will have the return code in the
 137    :attr:`returncode` attribute.
 138
 139    The arguments are the same as for the Popen constructor.  Example::
 140
 141       check_call(["ls", "-l"])
 142
 143    .. versionadded:: 2.5
 144
 145
 146 Exceptions
 147 ^^^^^^^^^^
 148
 149 Exceptions raised in the child process, before the new program has started to
 150 execute, will be re-raised in the parent.  Additionally, the exception object
 151 will have one extra attribute called :attr:`child_traceback`, which is a string
 152 containing traceback information from the childs point of view.
 153
 154 The most common exception raised is :exc:`OSError`.  This occurs, for example,
 155 when trying to execute a non-existent file.  Applications should prepare for
 156 :exc:`OSError` exceptions.
 157
 158 A :exc:`ValueError` will be raised if :class:`Popen` is called with invalid
 159 arguments.
 160
 161 check_call() will raise :exc:`CalledProcessError`, if the called process returns
 162 a non-zero return code.
 163
 164
 165 Security
 166 ^^^^^^^^
 167
 168 Unlike some other popen functions, this implementation will never call /bin/sh
 169 implicitly.  This means that all characters, including shell metacharacters, can
 170 safely be passed to child processes.
 171
 172
 173 Popen Objects
 174 -------------
 175
 176 Instances of the :class:`Popen` class have the following methods:
 177
 178
 179 .. method:: Popen.poll()
 180
 181    Check if child process has terminated.  Set and return :attr:`returncode`
 182    attribute.
 183
 184
 185 .. method:: Popen.wait()
 186
 187    Wait for child process to terminate.  Set and return :attr:`returncode`
 188    attribute.
 189
 190
 191 .. method:: Popen.communicate(input=None)
 192
 193    Interact with process: Send data to stdin.  Read data from stdout and stderr,
 194    until end-of-file is reached.  Wait for process to terminate. The optional
 195    *input* argument should be a string to be sent to the child process, or
 196    ``None``, if no data should be sent to the child.
 197
 198    :meth:`communicate` returns a tuple ``(stdout, stderr)``.
 199
 200    Note that if you want to send data to the process's stdin, you need to create
 201    the Popen object with ``stdin=PIPE``.  Similarly, to get anything other than
 202    ``None`` in the result tuple, you need to give ``stdout=PIPE`` and/or
 203    ``stderr=PIPE`` too.
 204
 205    .. note::
 206
 207       The data read is buffered in memory, so do not use this method if the data
 208       size is large or unlimited.
 209
 210
 211 The following attributes are also available:
 212
 213 .. attribute:: Popen.stdin
 214
 215    If the *stdin* argument is ``PIPE``, this attribute is a file object that
 216    provides input to the child process.  Otherwise, it is ``None``.
 217
 218
 219 .. attribute:: Popen.stdout
 220
 221    If the *stdout* argument is ``PIPE``, this attribute is a file object that
 222    provides output from the child process.  Otherwise, it is ``None``.
 223
 224
 225 .. attribute:: Popen.stderr
 226
 227    If the *stderr* argument is ``PIPE``, this attribute is file object that
 228    provides error output from the child process.  Otherwise, it is ``None``.
 229
 230
 231 .. attribute:: Popen.pid
 232
 233    The process ID of the child process.
 234
 235
 236 .. attribute:: Popen.returncode
 237
 238    The child return code, set by :meth:`poll` and :meth:`wait` (and indirectly
 239    by :meth:`communicate`).  A ``None`` value indicates that the process
 240    hasn't terminated yet.
 241
 242    A negative value ``-N`` indicates that the child was terminated by signal
 243    ``N`` (Unix only).
 244
 245
 246 Replacing Older Functions with the subprocess Module
 247 ----------------------------------------------------
 248
 249 In this section, "a ==> b" means that b can be used as a replacement for a.
 250
 251 .. note::
 252
 253    All functions in this section fail (more or less) silently if the executed
 254    program cannot be found; this module raises an :exc:`OSError` exception.
 255
 256 In the following examples, we assume that the subprocess module is imported with
 257 "from subprocess import \*".
 258
 259
 260 Replacing /bin/sh shell backquote
 261 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 262
 263 ::
 264
 265    output=`mycmd myarg`
 266    ==>
 267    output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
 268
 269
 270 Replacing shell pipe line
 271 ^^^^^^^^^^^^^^^^^^^^^^^^^
 272
 273 ::
 274
 275    output=`dmesg | grep hda`
 276    ==>
 277    p1 = Popen(["dmesg"], stdout=PIPE)
 278    p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
 279    output = p2.communicate()[0]
 280
 281
 282 Replacing os.system()
 283 ^^^^^^^^^^^^^^^^^^^^^
 284
 285 ::
 286
 287    sts = os.system("mycmd" + " myarg")
 288    ==>
 289    p = Popen("mycmd" + " myarg", shell=True)
 290    sts = os.waitpid(p.pid, 0)
 291
 292 Notes:
 293
 294 * Calling the program through the shell is usually not required.
 295
 296 * It's easier to look at the :attr:`returncode` attribute than the exit status.
 297
 298 A more realistic example would look like this::
 299
 300    try:
 301        retcode = call("mycmd" + " myarg", shell=True)
 302        if retcode < 0:
 303            print >>sys.stderr, "Child was terminated by signal", -retcode
 304        else:
 305            print >>sys.stderr, "Child returned", retcode
 306    except OSError, e:
 307        print >>sys.stderr, "Execution failed:", e
 308
 309
 310 Replacing os.spawn\*
 311 ^^^^^^^^^^^^^^^^^^^^
 312
 313 P_NOWAIT example::
 314
 315    pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
 316    ==>
 317    pid = Popen(["/bin/mycmd", "myarg"]).pid
 318
 319 P_WAIT example::
 320
 321    retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
 322    ==>
 323    retcode = call(["/bin/mycmd", "myarg"])
 324
 325 Vector example::
 326
 327    os.spawnvp(os.P_NOWAIT, path, args)
 328    ==>
 329    Popen([path] + args[1:])
 330
 331 Environment example::
 332
 333    os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
 334    ==>
 335    Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})
 336
 337
 338 Replacing os.popen\*
 339 ^^^^^^^^^^^^^^^^^^^^
 340
 341 ::
 342
 343    pipe = os.popen(cmd, mode='r', bufsize)
 344    ==>
 345    pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
 346
 347 ::
 348
 349    pipe = os.popen(cmd, mode='w', bufsize)
 350    ==>
 351    pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
 352
 353 ::
 354
 355    (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
 356    ==>
 357    p = Popen(cmd, shell=True, bufsize=bufsize,
 358              stdin=PIPE, stdout=PIPE, close_fds=True)
 359    (child_stdin, child_stdout) = (p.stdin, p.stdout)
 360
 361 ::
 362
 363    (child_stdin,
 364     child_stdout,
 365     child_stderr) = os.popen3(cmd, mode, bufsize)
 366    ==>
 367    p = Popen(cmd, shell=True, bufsize=bufsize,
 368              stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
 369    (child_stdin,
 370     child_stdout,
 371     child_stderr) = (p.stdin, p.stdout, p.stderr)
 372
 373 ::
 374
 375    (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
 376    ==>
 377    p = Popen(cmd, shell=True, bufsize=bufsize,
 378              stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
 379    (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)
 380
 381
 382 Replacing popen2.\*
 383 ^^^^^^^^^^^^^^^^^^^
 384
 385 .. note::
 386
 387    If the cmd argument to popen2 functions is a string, the command is executed
 388    through /bin/sh.  If it is a list, the command is directly executed.
 389
 390 ::
 391
 392    (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
 393    ==>
 394    p = Popen(["somestring"], shell=True, bufsize=bufsize,
 395              stdin=PIPE, stdout=PIPE, close_fds=True)
 396    (child_stdout, child_stdin) = (p.stdout, p.stdin)
 397
 398 ::
 399
 400    (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
 401    ==>
 402    p = Popen(["mycmd", "myarg"], bufsize=bufsize,
 403              stdin=PIPE, stdout=PIPE, close_fds=True)
 404    (child_stdout, child_stdin) = (p.stdout, p.stdin)
 405
 406 The popen2.Popen3 and popen2.Popen4 basically works as subprocess.Popen, except
 407 that:
 408
 409 * subprocess.Popen raises an exception if the execution fails
 410
 411 * the *capturestderr* argument is replaced with the *stderr* argument.
 412
 413 * stdin=PIPE and stdout=PIPE must be specified.
 414
 415 * popen2 closes all file descriptors by default, but you have to specify
 416   close_fds=True with subprocess.Popen.
 417