runners

invoke.runners.isatty(stream)

Check if a stream is a tty.

Not all file-like objects implement the isatty method.

class invoke.runners.Runner(context)

Partially-abstract core command-running API.

This class is not usable by itself and must be subclassed, implementing a number of methods such as start, wait and returncode. For a subclass implementation example, see the source code for Local.

__init__(context)

Create a new runner with a handle on some Context.

Parameters:context

a Context instance, used to transmit default options and provide access to other contextualized information (e.g. a remote-oriented Runner might want a Context subclass holding info about hostnames and ports.)

Note

The Context given to Runner instances must contain default config values for the Runner class in question. At a minimum, this means values for each of the default Runner.run keyword arguments such as echo and warn.

Raises exceptions.ValueError:
 if not all expected default values are found in context.
context = None

The Context given to the same-named argument of __init__.

run(command, **kwargs)

Execute command, returning an instance of Result.

Note

All kwargs will default to the values found in this instance’s context attribute, specifically in its configuration’s run subtree (e.g. run.echo provides the default value for the echo keyword, etc). The base default values are described in the parameter list below.

Parameters:
  • command (str) – The shell command to execute.
  • warn (bool) – Whether to warn and continue, instead of raising Failure, when the executed command exits with a nonzero status. Default: False.
  • hide

    Allows the caller to disable run‘s default behavior of copying the subprocess’ stdout and stderr to the controlling terminal. Specify hide='out' (or 'stdout') to hide only the stdout stream, hide='err' (or 'stderr') to hide only stderr, or hide='both' (or True) to hide both streams.

    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.

  • pty (bool) –

    By default, run connects directly to the invoked process and reads its stdout/stderr streams. Some programs will buffer (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 out_stream (see below) and be captured into the stdout result attribute. err_stream and stderr will always be empty when pty=True.

  • fallback (bool) – Controls auto-fallback behavior re: problems offering a pty when pty=True. Whether this has any effect depends on the specific Runner subclass being invoked. Default: True.
  • echo (bool) – Controls whether run prints the command string to local stdout prior to executing it. Default: False.
  • encoding (str) – Override auto-detection of which encoding the subprocess is using for its stdout/stderr streams (which defaults to the return value of default_encoding).
  • out_stream – A file-like stream object to which the subprocess’ standard error should be written. If None (the default), sys.stdout will be used.
  • err_stream – Same as out_stream, except for standard error, and defaulting to sys.stderr.
Returns:

Result, or a subclass thereof.

Raises:

Failure (if the command exited nonzero & warn=False)

Raises:

ThreadException (if the background I/O threads encounter exceptions)

generate_result(**kwargs)

Create & return a suitable Result instance from the given kwargs.

Subclasses may wish to override this in order to manipulate things or generate a Result subclass (e.g. ones containing additional metadata besides the default).

io(reader, output, buffer_, hide)

Perform I/O (reading, capturing & writing).

Specifically:

  • Read bytes from reader, giving it some number of bytes to read at a time. (Typically this function is the result of stdout_reader or stderr_reader.)
  • Decode the bytes into a string according to self.encoding (typically derived from default_encoding or runtime keyword args).
  • Save a copy of the bytes in buffer_, typically a list, which the caller will expect to be mutated.
  • If hide is False, write bytes to output, a stream such as sys.stdout.
should_use_pty(pty, fallback)

Should execution attempt to use a pseudo-terminal?

Parameters:
  • pty (bool) – Whether the user explicitly asked for a pty.
  • fallback (bool) – Whether falling back to non-pty execution should be allowed, in situations where pty=True but a pty could not be allocated.
start(command)

Initiate execution of command, e.g. in a subprocess.

Typically, this will also set subclass-specific member variables used in other methods such as wait and/or returncode.

stdout_reader()

Return a function suitable for reading from a running command’s stdout.

stderr_reader()

Return a function suitable for reading from a running command’s stderr.

default_encoding()

Return a string naming the expected encoding of subprocess streams.

This return value should be suitable for use by methods such as codecs.iterdecode.

wait()

Block until the running command appears to have exited.

returncode()

Return the numeric return/exit code resulting from command execution.

__weakref__

list of weak references to the object (if defined)

class invoke.runners.Local(context)

Execute a command on the local system in a subprocess.

Note

When Invoke itself is executed without a valid PTY (i.e. os.isatty(sys.stdin) is False), it’s not possible to present a handle on our PTY to local subprocesses. In such situations, Local will fallback to behaving as if pty=False, on the theory that degraded execution is better than none at all, as well as printing a warning to stderr.

To disable this behavior (i.e. if os.isatty is causing false negatives in your environment), say fallback=False.

class invoke.runners.Result(command, stdout, stderr, exited, pty)

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

See individual attribute/method documentation below for details.

Note

Result objects’ truth evaluation is equivalent to their ok attribute’s value. Therefore, quick-and-dirty expressions like the following are possible:

if run("some shell command"):
    do_something()
else:
    handle_problem()
command = None

The command which was executed.

exited = None

An integer representing the subprocess’ exit/return code.

return_code = None

An alias for exited.

stdout = None

The subprocess’ standard output, as a multiline string.

stderr = None

Same as stdout but containing standard error (unless the process was invoked via a pty; see Runner.run.)

pty = None

A boolean describing whether the subprocess was invoked with a pty or not; see Runner.run.

ok

A boolean equivalent to exited == 0.

failed

The inverse of ok.

I.e., True if the program exited with a nonzero return code, and False otherwise.

__weakref__

list of weak references to the object (if defined)