simple_automation.context.Context

class simple_automation.context.Context(manager, host)

Bases: object

A context is a wrapper object around a host and an ssh connection to that host. It is used to execute commands on the remote machine, and tracks state over the connection lifetime.

Methods

defaults

Creates a resource object, which sets the given defaults when it is entered, and resets them when it is exited.

exec_ssh_raw

Execute ssh to execute the given command on the remote host, directly via ssh.

init_ssh

Initialize environment on the remote host (temporary directory, remote exec script), so we can more easily execute commands on the remote.

remote_exec

Execute ssh to execute the given command on the remote host, via our built-in remote dispatch script.

run_task

Runs the registered instance (see Manager) for the given task class.

transaction

Begins a new transaction.

Attributes

debug

Forwards the corresponding variable from the associated manager.

pretend

Forwards the corresponding variable from the associated manager.

vars

Returns a Vars object containing the current active set of variables, which was merged from parent objects (global variables, group variables) on construction.

vars_dict

Returns a dictionary containing the current active set of variables, which was merged from parent objects (global variables, group variables) on construction.

verbose

Forwards the corresponding variable from the associated manager.

class ContextDefaults(context, user: str, umask: int, dir_mode: int, file_mode: int, owner: str, group: str)

Bases: object

Creates a resource object, which sets the given defaults when it is entered, and resets them when it is exited. Always use in a with statement. Statements may be nested.

property debug

Forwards the corresponding variable from the associated manager.

defaults(user: Optional[str] = None, umask: Optional[int] = None, dir_mode: Optional[int] = None, file_mode: Optional[int] = None, owner: Optional[str] = None, group: Optional[str] = None)

Creates a resource object, which sets the given defaults when it is entered, and resets them when it is exited. Always use in a with statement. Statements may be nested.

Example

def run(self, context):
    # Default context permissions apply here
    with context.defaults(owner="www", group="www"):
        # The directory owner and group will both be "www"
        directory(context, path="/var/www/test")
Parameters
  • user (str, optional) – The user to execute commands as on the remote.

  • umask (int, optional) – The umask to execute commands with on the remote.

  • dir_mode (int, optional) – The directory mode for newly created directories on the remote.

  • file_mode (int, optional) – The directory mode for newly created directories on the remote.

  • owner (str, optional) – The owner of newly created files or directories on the remote.

  • group (str, optional) – The group of newly created files or directories on the remote.

exec_ssh_raw(command)

Execute ssh to execute the given command on the remote host, directly via ssh.

Parameters

command (list[str]) – The command to execute on the remote.

Returns

The completed subprocess

Return type

subprocess.CompletedProcess

init_ssh()

Initialize environment on the remote host (temporary directory, remote exec script), so we can more easily execute commands on the remote.

property pretend

Forwards the corresponding variable from the associated manager.

remote_exec(command, checked=False, input=None, error_verbosity=None, user=None, umask=None, verbosity=None)

Execute ssh to execute the given command on the remote host, via our built-in remote dispatch script. If checked is True, it will throw an exception if the remote command returns an unsuccessful exit status. checked=True also implies a default error_verbosity=0 and verbosity=2.

If both verbosity and error_verbosity trigger, the output will only be printed once.

Parameters
  • command (list[str]) – The command to execute on the remote.

  • checked (bool, optional) – If true, an exception will be raised if the command fails. Defaults to false.

  • input (bytes, optional) – If not None, this will be passed to the command as stdin.

  • user (str, optional) – A specific user to execute the command as. Defaults to the user set in the context.

  • umask (int, optional) – A specific umask to execute the command with. Defaults to the umask set in the context.

  • verbosity (int, optional) – If verbosity is not None and self.verbose >= verbosity, the command output will be printed. Read: verbosity is the number of -v flags needed so that the command’s output will be shown. If verbosity is not given, the output will never be shown.

  • error_verbosity (int, optional) – Same as verbosity, but only triggers when the command fails. E.g. calling with error_verbosity=1 causes both stdout and stderr to be printed, if the command fails and at least -v was given.

Returns

The completed remote command

Return type

CompletedRemoteCommand

run_task(registered_task_class)

Runs the registered instance (see Manager) for the given task class.

Parameters

registered_task_class (class(Task)) – The task class that should be executed. The registered instance is found first, and then called.

transaction(title: str, name: str)

Begins a new transaction. Intended to be used in a ‘with’ statement. Each transaction will be shown to the user as a distinct unit.

A transaction must record an initial state and a final state, and may return success or failure (+reason).

A transaction should not actually alter the state of the remote, if context.pretend is set to True. In this case it should only examine and record what would be done.

A transaction may give additional variables to success() and failure(), which will be stored for later use.

Parameters
  • title (str) – The title for the new transaction.

  • name (str) – The name for the new transaction.

property vars

Returns a Vars object containing the current active set of variables, which was merged from parent objects (global variables, group variables) on construction.

property vars_dict

Returns a dictionary containing the current active set of variables, which was merged from parent objects (global variables, group variables) on construction.

property verbose

Forwards the corresponding variable from the associated manager.