subprocess

Subprocesses with accessible I/O streams

This module allows you to spawn processes, connect to their
input/output/error pipes, and obtain their return codes.

For a complete description of this module see the Python documentation.

Main API
========
run(...): Runs a command, waits for it to complete, then returns a
          CompletedProcess instance.
Popen(...): A class for flexibly executing a command in a new process

Constants
---------
DEVNULL: Special value that indicates that os.devnull should be used
PIPE:    Special value that indicates a pipe should be created
STDOUT:  Special value that indicates that stderr should go to stdout


Older API
=========
call(...): Runs a command, waits for it to complete, then returns
    the return code.
check_call(...): Same as call() but raises CalledProcessError()
    if return code is not 0
check_output(...): Same as check_call() but returns the contents of
    stdout instead of a return code
getoutput(...): Runs a command in the shell, waits for it to complete,
    then returns the output
getstatusoutput(...): Runs a command in the shell, waits for it to complete,
    then returns a (exitcode, output) tuple

Classes

CalledProcessError

Raised when run() is called with check=True and the process
    returns a non-zero exit status.

    Attributes:
      cmd, returncode, stdout, stderr, output

with_traceback(...)

  Exception.with_traceback(tb) --
      set self.__traceback__ to tb and return self.

args = <attribute 'args' of 'BaseException' objects>

stdout = <property object at 0x7f75e3207290>
  Alias for output attribute, to match stderr

CompletedProcess

A process that has finished running.

    This is returned by run().

    Attributes:
      args: The list or str args passed to run().
      returncode: The exit code of the process, negative for signals.
      stdout: The standard output (None if not captured).
      stderr: The standard error (None if not captured).

check_returncode(self)

  Raise CalledProcessError if the exit code is non-zero.

Popen

 Execute a child program in a new process.

    For a complete description of the arguments see the Python documentation.

    Arguments:
      args: A string, or a sequence of program arguments.

      bufsize: supplied as the buffering argument to the open() function when
          creating the stdin/stdout/stderr pipe file objects

      executable: A replacement program to execute.

      stdin, stdout and stderr: These specify the executed programs' standard
          input, standard output and standard error file handles, respectively.

      preexec_fn: (POSIX only) An object to be called in the child process
          just before the child is executed.

      close_fds: Controls closing or inheriting of file descriptors.

      shell: If true, the command will be executed through the shell.

      cwd: Sets the current directory before the child is executed.

      env: Defines the environment variables for the new process.

      text: If true, decode stdin, stdout and stderr using the given encoding
          (if set) or the system default otherwise.

      universal_newlines: Alias of text, provided for backwards compatibility.

      startupinfo and creationflags (Windows only)

      restore_signals (POSIX only)

      start_new_session (POSIX only)

      group (POSIX only)

      extra_groups (POSIX only)

      user (POSIX only)

      umask (POSIX only)

      pass_fds (POSIX only)

      encoding and errors: Text mode encoding and error handling to use for
          file objects stdin, stdout and stderr.

    Attributes:
        stdin, stdout, stderr, pid, returncode

communicate(self, input=None, timeout=None)

  Interact with process: Send data to stdin and close it.
          Read data from stdout and stderr, until end-of-file is
          reached.  Wait for process to terminate.

          The optional "input" argument should be data to be sent to the
          child process, or None, if no data should be sent to the child.
          communicate() returns a tuple (stdout, stderr).

          By default, all communication is in bytes, and therefore any
          "input" should be bytes, and the (stdout, stderr) will be bytes.
          If in text mode (indicated by self.text_mode), any "input" should
          be a string, and (stdout, stderr) will be strings decoded
          according to locale encoding, or by "encoding" if set. Text mode
          is triggered by setting any of text, encoding, errors or
          universal_newlines.

kill(self)

  Kill the process with SIGKILL

poll(self)

  Check if child process has terminated. Set and return returncode
          attribute.

send_signal(self, sig)

  Send a signal to the process.

terminate(self)

  Terminate the process with SIGTERM

wait(self, timeout=None)

  Wait for child process to terminate; returns self.returncode.

universal_newlines = <property object at 0x7f75e3207420>

SubprocessError

with_traceback(...)

  Exception.with_traceback(tb) --
      set self.__traceback__ to tb and return self.

args = <attribute 'args' of 'BaseException' objects>

TimeoutExpired

This exception is raised when the timeout expires while waiting for a
    child process.

    Attributes:
        cmd, output, stdout, stderr, timeout

with_traceback(...)

  Exception.with_traceback(tb) --
      set self.__traceback__ to tb and return self.

args = <attribute 'args' of 'BaseException' objects>

stdout = <property object at 0x7f75e32072e0>

Functions

call

call(*popenargs, timeout=None, **kwargs)

  Run command with arguments.  Wait for command to complete or
      timeout, then return the returncode attribute.

      The arguments are the same as for the Popen constructor.  Example:

      retcode = call(["ls", "-l"])

check_call

check_call(*popenargs, **kwargs)

  Run command with arguments.  Wait for command to complete.  If
      the exit code was zero then return, otherwise raise
      CalledProcessError.  The CalledProcessError object will have the
      return code in the returncode attribute.

      The arguments are the same as for the call function.  Example:

      check_call(["ls", "-l"])

check_output

check_output(*popenargs, timeout=None, **kwargs)

  Run command with arguments and return its output.

      If the exit code was non-zero it raises a CalledProcessError.  The
      CalledProcessError object will have the return code in the returncode
      attribute and output in the output attribute.

      The arguments are the same as for the Popen constructor.  Example:

      >>> check_output(["ls", "-l", "/dev/null"])
      b'crw-rw-rw- 1 root root 1, 3 Oct 18  2007 /dev/null\n'

      The stdout argument is not allowed as it is used internally.
      To capture standard error in the result, use stderr=STDOUT.

      >>> check_output(["/bin/sh", "-c",
      ...               "ls -l non_existent_file ; exit 0"],
      ...              stderr=STDOUT)
      b'ls: non_existent_file: No such file or directory\n'

      There is an additional optional argument, "input", allowing you to
      pass a string to the subprocess's stdin.  If you use this argument
      you may not also use the Popen constructor's "stdin" argument, as
      it too will be used internally.  Example:

      >>> check_output(["sed", "-e", "s/foo/bar/"],
      ...              input=b"when in the course of fooman events\n")
      b'when in the course of barman events\n'

      By default, all communication is in bytes, and therefore any "input"
      should be bytes, and the return value will be bytes.  If in text mode,
      any "input" should be a string, and the return value will be a string
      decoded according to locale encoding, or by "encoding" if set. Text mode
      is triggered by setting any of text, encoding, errors or universal_newlines.

getoutput

getoutput(cmd)

  Return output (stdout or stderr) of executing cmd in a shell.

      Like getstatusoutput(), except the exit status is ignored and the return
      value is a string containing the command's output.  Example:

      >>> import subprocess
      >>> subprocess.getoutput('ls /bin/ls')
      '/bin/ls'

getstatusoutput

getstatusoutput(cmd)

  Return (exitcode, output) of executing cmd in a shell.

      Execute the string 'cmd' in a shell with 'check_output' and
      return a 2-tuple (status, output). The locale encoding is used
      to decode the output and process newlines.

      A trailing newline is stripped from the output.
      The exit status for the command can be interpreted
      according to the rules for the function 'wait'. Example:

      >>> import subprocess
      >>> subprocess.getstatusoutput('ls /bin/ls')
      (0, '/bin/ls')
      >>> subprocess.getstatusoutput('cat /bin/junk')
      (1, 'cat: /bin/junk: No such file or directory')
      >>> subprocess.getstatusoutput('/bin/junk')
      (127, 'sh: /bin/junk: not found')
      >>> subprocess.getstatusoutput('/bin/kill $')
      (-15, '')

list2cmdline

list2cmdline(seq)


      Translate a sequence of arguments into a command line
      string, using the same rules as the MS C runtime:

      1) Arguments are delimited by white space, which is either a
         space or a tab.

      2) A string surrounded by double quotation marks is
         interpreted as a single argument, regardless of white space
         contained within.  A quoted string can be embedded in an
         argument.

      3) A double quotation mark preceded by a backslash is
         interpreted as a literal double quotation mark.

      4) Backslashes are interpreted literally, unless they
         immediately precede a double quotation mark.

      5) If backslashes immediately precede a double quotation mark,
         every pair of backslashes is interpreted as a literal
         backslash.  If the number of backslashes is odd, the last
         backslash escapes the next double quotation mark as
         described in rule 3.

run

run(*popenargs, input=None, capture_output=False, timeout=None, check=False, **kwargs)

  Run command with arguments and return a CompletedProcess instance.

      The returned instance will have attributes args, returncode, stdout and
      stderr. By default, stdout and stderr are not captured, and those attributes
      will be None. Pass stdout=PIPE and/or stderr=PIPE in order to capture them,
      or pass capture_output=True to capture both.

      If check is True and the exit code was non-zero, it raises a
      CalledProcessError. The CalledProcessError object will have the return code
      in the returncode attribute, and output & stderr attributes if those streams
      were captured.

      If timeout is given, and the process takes too long, a TimeoutExpired
      exception will be raised.

      There is an optional argument "input", allowing you to
      pass bytes or a string to the subprocess's stdin.  If you use this argument
      you may not also use the Popen constructor's "stdin" argument, as
      it will be used internally.

      By default, all communication is in bytes, and therefore any "input" should
      be bytes, and the stdout and stderr will be bytes. If in text mode, any
      "input" should be a string, and stdout and stderr will be strings decoded
      according to locale encoding, or by "encoding" if set. Text mode is
      triggered by setting any of text, encoding, errors or universal_newlines.

      The other arguments are the same as for the Popen constructor.

Other members

DEVNULL = -3

PIPE = -1

STDOUT = -2

Modules