Runner & run: Executes shell commands

class invoke.runner.Runner

Abstract core command-running API.

Actual command runners should subclass & implement the following:

  • run: Command execution hooking directly into the subprocess’ stdout/stderr pipes and returning their eventual values as distinct strings. Specifically, have a signature of def run(self, command, warn, hide): (see runner.run for semantics of these) and return a 4-tuple of (stdout, stderr, exitcode, exception).
  • run_pty: Execution utilizing a pseudo-terminal, which is then expected to only return a useful stdout (with stderr usually empty.) Has same signature and return value as run.

For an implementation example, see the source code for Local.

class invoke.runner.Local

Execute a command on the local system in a subprocess.

invoke.runner.run(command, warn=False, hide=None, pty=False, echo=False, runner=<class 'invoke.runner.Local'>)

Execute command (via runner) returning a Result object.

A Failure exception (containing a reference to the Result that would otherwise have been returned) is raised if the command terminates with a nonzero return code. This behavior may be disabled by setting warn=True.

To disable copying the command’s stdout and/or stderr to the controlling terminal, specify hide='out' (or 'stdout'), hide='err' (or 'stderr') or hide='both' (or True). The default value is None, meaning to print everything; False will also disable hiding.

Note

Stdout and stderr are always captured and stored in the Result object, regardless of hide‘s value.

By default, run connects directly to the invoked process and reads its stdout/stderr streams. Some programs will buffer differently (or even behave differently) in this situation compared to using an actual terminal or pty. To use a pty, specify pty=True.

Warning

Due to their nature, ptys have a single output stream, so the ability to tell stdout apart from stderr is not possible when pty=True. As such, all output will appear on your local stdout and be captured into the stdout result attribute. Stderr and stderr will always be empty when pty=True.

run does not echo the commands it runs by default; to make it do so, say echo=True.

The runner argument allows overriding the actual execution mechanism, and must be a class exposing two methods, run and run_pty, whose signatures must match function(command, warn, hide) - all of which match the above descriptions, re: types and default values.

These methods must return a tuple of (stdout, stderr, exited, exception), where stdout and stderr are strings, exited is an integer, and exception is an exception object or None.

class invoke.runner.Result(stdout, stderr, exited, pty, exception=None)

A container for information about the result of a command execution.

Result instances have the following attributes:

  • stdout: The subprocess’ standard output, as a multiline string.
  • stderr: Same as stdout but containing standard error (unless the process was invoked via a pty; see run.)
  • exited: An integer representing the subprocess’ exit/return code.
  • return_code: An alias to exited.
  • ok: A boolean equivalent to exited == 0.
  • failed: The inverse of ok: True if the program exited with a nonzero return code.
  • pty: A boolean describing whether the subprocess was invoked with a pty or not; see run.
  • exception: Typically None, but may be an exception object if pty was True and run() had to swallow an apparently-spurious OSError. Solely for sanity checking/debugging purposes.

Result objects’ truth evaluation is equivalent to their ok attribute’s value.

Previous topic

Parser: Core parsing state machine

Next topic

tasks: Task class & task-generating decorators

This Page