# gevent

# `gevent.subprocess` – Cooperative `subprocess` module

Caution

On POSIX platforms, this module is not usable from native threads other than the main thread; attempting to do so will raise a `TypeError`. This module depends on libev’s fork watchers. On POSIX systems, fork watchers are implemented using signals, and the thread to which process-directed signals are delivered is not defined. Because each native thread has its own gevent/libev loop, this means that a fork watcher registered with one loop (thread) may never see the signal about a child it spawned if the signal is sent to a different thread.

Note

The interface of this module is intended to match that of the standard library `subprocess` module. There are some small differences between the Python 2 and Python 3 versions of that module and between the POSIX and Windows versions. The HTML documentation here can only describe one version; for definitive documentation, see the standard library or the source code.

class `Popen`(args, bufsize=None, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=<object object>, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0, threadpool=None, **kwargs)

  Bases: `object`

  The underlying process creation and management in this module is handled by the Popen class. It offers a lot of flexibility so that developers are able to handle the less common cases not covered by the convenience functions.

  See also

  `subprocess.Popen` This class should have the same interface as the standard library class.

  Create new Popen instance.

  Parameters: | kwargs – Only allowed under Python 3; under Python 2, any unrecognized keyword arguments will result in a `TypeError`. Under Python 3, keyword arguments can include `pass_fds`, `start_new_session`, and `restore_signals`.

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

    Interact with process: Send data to stdin. Read data from stdout and stderr, until end-of-file is reached. Wait for process to terminate. The optional input argument should be a string to be sent to the child process, or None, if no data should be sent to the child.

    communicate() returns a tuple (stdout, stderr).

    Parameters: | timeout – Under Python 2, this is a gevent extension; if given and it expires, we will raise `gevent.timeout.Timeout`. Under Python 3, this raises the standard `TimeoutExpired` exception.

    Changed in version 1.1a2: Under Python 2, if the timeout elapses, raise the `gevent.timeout.Timeout` exception. Previously, we silently returned.

    Changed in version 1.1b5: Honor a timeout even if there’s no way to communicate with the child (stdin, stdout, and stderr are not pipes).

  `poll`()

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

  `pipe_cloexec`()

    Create a pipe with FDs set CLOEXEC.

  `wait`(timeout=None)

    Wait for child process to terminate. Returns `returncode` attribute.

    Parameters: | timeout – The floating point number of seconds to wait. Under Python 2, this is a gevent extension, and we simply return if it expires. Under Python 3, if this time elapses without finishing the process, `TimeoutExpired` is raised.

  `send_signal`(sig)

    Send a signal to the process

  `terminate`()

    Terminate the process with SIGTERM

  `kill`()

    Kill the process with SIGKILL

`call`(*popenargs, **kwargs)

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

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

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

`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 Popen constructor. Example:

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

`check_output`(*popenargs, **kwargs)

  Run command with arguments and return its output as a byte string.

  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:

      >>> print(check_output(["ls", "-1", "/dev/null"]).decode('ascii'))
      /dev/null

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

      >>> print(check_output(["/bin/sh", "-c", "echo hello world"], stderr=STDOUT).decode('ascii'))
      hello world

exception `CalledProcessError`(returncode, cmd, output=None)

  Bases: `exceptions.Exception`

  This exception is raised when a process run by check_call() or check_output() returns a non-zero exit status. The exit status will be stored in the returncode attribute; check_output() will also store the output in the output attribute.

Next page: Low-level details