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
andreturncode
. For a subclass implementation example, see the source code forLocal
.-
__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-orientedRunner
might want aContext
subclass holding info about hostnames and ports.)Note
The
Context
given toRunner
instances must contain default config values for theRunner
class in question. At a minimum, this means values for each of the defaultRunner.run
keyword arguments such asecho
andwarn
.Raises exceptions.ValueError: if not all expected default values are found in context
.
-
run
(command, **kwargs)¶ Execute
command
, returning an instance ofResult
.Note
All kwargs will default to the values found in this instance’s
context
attribute, specifically in its configuration’srun
subtree (e.g.run.echo
provides the default value for theecho
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. Specifyhide='out'
(or'stdout'
) to hide only the stdout stream,hide='err'
(or'stderr'
) to hide only stderr, orhide='both'
(orTrue
) 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 ofhide
‘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, specifypty=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 onout_stream
(see below) and be captured into thestdout
result attribute.err_stream
andstderr
will always be empty whenpty=True
. - fallback (bool) – Controls auto-fallback behavior re: problems offering a pty when
pty=True
. Whether this has any effect depends on the specificRunner
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 tosys.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 givenkwargs
.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 ofstdout_reader
orstderr_reader
.) - Decode the bytes into a string according to
self.encoding
(typically derived fromdefault_encoding
or runtime keyword args). - Save a copy of the bytes in
buffer_
, typically alist
, which the caller will expect to be mutated. - If
hide
isFalse
, write bytes tooutput
, a stream such assys.stdout
.
- Read bytes from
-
should_use_pty
(pty, fallback)¶ Should execution attempt to use a pseudo-terminal?
Parameters:
-
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/orreturncode
.
-
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)
isFalse
), it’s not possible to present a handle on our PTY to local subprocesses. In such situations,Local
will fallback to behaving as ifpty=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), sayfallback=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 theirok
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.
-
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; seeRunner.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, andFalse
otherwise.
-
__weakref__
¶ list of weak references to the object (if defined)
-