runners
¶
-
class
fabric.runners.
Remote
(*args, **kwargs)¶ Run a shell command over an SSH connection.
This class subclasses
invoke.runners.Runner
; please see its documentation for most public API details.Note
Remote
’s__init__
method expects aConnection
(or subclass) instance for itscontext
argument.New in version 2.0.
-
__init__
(*args, **kwargs)¶ Thin wrapper for superclass’
__init__
; please see it for details.Additional keyword arguments defined here are listed below.
Parameters: inline_env (bool) – Whether to ‘inline’ shell env vars as prefixed parameters, instead of trying to submit them via Channel.update_environment
. Default::False
.Changed in version 2.3: Added the
inline_env
parameter.
-
close_proc_stdin
()¶ Close running process’ stdin.
Returns: None
.New in version 1.3.
-
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).New in version 1.0.
-
kill
()¶ Forcibly terminate the subprocess.
Typically only used by the timeout functionality.
This is often a “best-effort” attempt, e.g. remote subprocesses often must settle for simply shutting down the local side of the network connection and hoping the remote end eventually gets the message.
-
process_is_finished
¶ Determine whether our subprocess has terminated.
Note
The implementation of this method should be nonblocking, as it is used within a query/poll loop.
Returns: True
if the subprocess has finished running,False
otherwise.New in version 1.0.
-
read_proc_stderr
(num_bytes)¶ Read
num_bytes
from the running process’ stderr stream.Parameters: num_bytes (int) – Number of bytes to read at maximum. Returns: A string/bytes object. New in version 1.0.
-
read_proc_stdout
(num_bytes)¶ Read
num_bytes
from the running process’ stdout stream.Parameters: num_bytes (int) – Number of bytes to read at maximum. Returns: A string/bytes object. New in version 1.0.
-
returncode
()¶ Return the numeric return/exit code resulting from command execution.
Returns: int
New in version 1.0.
-
send_interrupt
(interrupt)¶ Submit an interrupt signal to the running subprocess.
In almost all implementations, the default behavior is what will be desired: submit
to the subprocess’ stdin pipe. However, we leave this as a public method in case this default needs to be augmented or replaced.
Parameters: interrupt – The locally-sourced KeyboardInterrupt
causing the method call.Returns: None
.New in version 1.0.
-
start
(command, shell, env, timeout=None)¶ Initiate execution of
command
(viashell
, withenv
).Typically this means use of a forked subprocess or requesting start of execution on a remote system.
In most cases, this method will also set subclass-specific member variables used in other methods such as
wait
and/orreturncode
.Parameters: - command (str) – Command string to execute.
- shell (str) – Shell to use when executing
command
. - env (dict) – Environment dict used to prep shell environment.
New in version 1.0.
-
stop
()¶ Perform final cleanup, if necessary.
This method is called within a
finally
clause inside the mainrun
method. Depending on the subclass, it may be a no-op, or it may do things such as close network connections or open files.Returns: None
New in version 1.0.
-
-
class
fabric.runners.
Result
(**kwargs)¶ An
invoke.runners.Result
exposing whichConnection
was run against.Exposes all attributes from its superclass, then adds a
.connection
, which is simply a reference to theConnection
whose method yielded this result.New in version 2.0.
-
__init__
(**kwargs)¶ Initialize self. See help(type(self)) for accurate signature.
-