Base Classes¶

Factories base classes

class saltfactories.bases.Factory(*, display_name=None, cwd=None, environ=None)[source]¶

Bases: object

Base factory class

Parameters

display_name (str) – Human readable name for the factory
environ (dict) – A dictionary of key, value pairs to add to the environment.
cwd (str) – The path to the current working directory

Return type

None

get_display_name()[source]¶: Returns a human readable name for the factory

class saltfactories.bases.SubprocessImpl(*, factory)[source]¶

Bases: object

Subprocess interaction implementation

Parameters: factory (Factory) – The factory instance, either Factory or a sub-class of it.
Return type: None

cmdline(*args)[source]¶

Construct a list of arguments to use when starting the subprocess

Parameters: args (str) – Additional arguments to use when starting the subprocess

By default, this method will just call it’s factory’s cmdline() method, but can be overridden, as is the case of saltfactories.base.SystemdSaltDaemonImpl.

init_terminal(cmdline, env=None)[source]¶

Instantiate a terminal with the passed command line(cmdline) and return it.

Additionally, it sets a reference to it in self._terminal and also collects an initial listing of child processes which will be used when terminating the terminal

Parameters

cmdline (list,tuple) – List of strings to pass as args to Popen
environ (dict) – A dictionary of key, value pairs to add to the py:attr:saltfactories.base.Factory.environ.

is_running()[source]¶

Returns: Returns true if the sub-process is alive
Return type: bool

terminate()[source]¶

Terminate the started daemon

Return type: ProcessResult

property pid¶: The pid of the running process. None if not running.

run(*args, **kwargs)[source]¶: Run the given command synchronously

class saltfactories.bases.Subprocess(*, display_name=None, cwd=None, environ=None, script_name, base_script_args=NOTHING, slow_stop=True)[source]¶

Bases: saltfactories.bases.Factory

Base CLI script/binary class

Parameters

script_name (str) – This is the string containing the name of the binary to call on the subprocess, either the full path to it, or the basename. In case of the basename, the directory containing the basename must be in your $PATH variable.
base_script_args (list,tuple) – An list or tuple iterable of the base arguments to use when building the command line to launch the process
slow_stop (bool) – Whether to terminate the processes by sending a SIGTERM signal or by calling terminate() on the sub-process. When code coverage is enabled, one will want slow_stop set to True so that coverage data can be written down to disk.

Return type

None

Please look at Factory for the additional supported keyword arguments documentation.

get_display_name()[source]¶: Returns a human readable name for the factory

get_script_path()[source]¶: Returns the path to the script to run

get_base_script_args()[source]¶: Returns any additional arguments to pass to the CLI script

get_script_args()[source]¶: Returns any additional arguments to pass to the CLI script

cmdline(*args)[source]¶

Construct a list of arguments to use when starting the subprocess

Parameters: args (str) – Additional arguments to use when starting the subprocess
Return type: list

is_running()[source]¶: Returns true if the sub-process is alive

terminate()[source]¶: Terminate the started daemon

property pid¶: The pid of the running process. None if not running.

class saltfactories.bases.Process(*, display_name=None, cwd=None, environ=None, script_name, base_script_args=NOTHING, slow_stop=True, timeout=NOTHING)[source]¶

Bases: saltfactories.bases.Subprocess

Base process factory

Parameters: timeout (int) – The default maximum amount of seconds that a script should run. This value can be overridden when calling run() through the _timeout keyword argument, and, in that case, the timeout value applied would be that of _timeout instead of self.timeout.
Return type: None

Please look at Subprocess for the additional supported keyword arguments documentation.

run(*args, _timeout=None, **kwargs)[source]¶

Run the given command synchronously

Parameters

args (list,tuple) – The list of arguments to pass to cmdline() to construct the command to run
_timeout (int) – The timeout value for this particular run() call. If this value is not None, it will be used instead of timeout, the default timeout.

process_output(stdout, stderr, cmdline=None)[source]¶

Process the output. When possible JSON is loaded from the output.

Returns: Returns a tuple in the form of (stdout, stderr, loaded_json)
Return type: tuple

cmdline(*args)¶

Construct a list of arguments to use when starting the subprocess

Parameters: args (str) – Additional arguments to use when starting the subprocess
Return type: list

get_base_script_args()¶: Returns any additional arguments to pass to the CLI script

get_display_name()¶: Returns a human readable name for the factory

get_script_args()¶: Returns any additional arguments to pass to the CLI script

get_script_path()¶: Returns the path to the script to run

is_running()¶: Returns true if the sub-process is alive

property pid¶: The pid of the running process. None if not running.

terminate()¶: Terminate the started daemon

class saltfactories.bases.StartDaemonCallArguments(*, args, kwargs)[source]¶

Bases: object

This class holds the arguments and keyword arguments used to start a daemon.

It’s used when restarting the daemon so that the same call is used.

Parameters

args (list,tuple) – List of arguments
kwargs (dict) – Dictionary of keyword arguments

Return type

None

class saltfactories.bases.DaemonImpl(*, factory, before_start_callbacks=NOTHING, after_start_callbacks=NOTHING, before_terminate_callbacks=NOTHING, after_terminate_callbacks=NOTHING)[source]¶

Bases: saltfactories.bases.SubprocessImpl

Daemon subprocess interaction implementation

Please look at SubprocessImpl for the additional supported keyword arguments documentation.

Return type: None

before_start(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

after_start(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

before_terminate(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

after_terminate(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

start(*extra_cli_arguments, max_start_attempts=None, start_timeout=None)[source]¶

Start the daemon

Parameters

extra_cli_arguments (tuple,) – Extra arguments to pass to the CLI that starts the daemon
max_start_attempts (int) – Maximum number of attempts to try and start the daemon in case of failures
start_timeout (int) – The maximum number of seconds to wait before considering that the daemon did not start

terminate()[source]¶: Terminate the daemon

get_start_arguments()[source]¶

Return the arguments and keyword arguments used when starting the daemon:

Return type: StartDaemonCallArguments

cmdline(*args)¶

Construct a list of arguments to use when starting the subprocess

Parameters: args (str) – Additional arguments to use when starting the subprocess

By default, this method will just call it’s factory’s cmdline() method, but can be overridden, as is the case of saltfactories.base.SystemdSaltDaemonImpl.

init_terminal(cmdline, env=None)¶

Instantiate a terminal with the passed command line(cmdline) and return it.

Additionally, it sets a reference to it in self._terminal and also collects an initial listing of child processes which will be used when terminating the terminal

Parameters

cmdline (list,tuple) – List of strings to pass as args to Popen
environ (dict) – A dictionary of key, value pairs to add to the py:attr:saltfactories.base.Factory.environ.

is_running()¶

Returns: Returns true if the sub-process is alive
Return type: bool

property pid¶: The pid of the running process. None if not running.

run(*args, **kwargs)¶: Run the given command synchronously

class saltfactories.bases.Daemon(*, display_name=None, cwd=None, environ=None, script_name, base_script_args=NOTHING, slow_stop=True, check_ports=None, factories_manager=None, start_timeout, max_start_attempts=3, extra_cli_arguments_after_first_start_failure=NOTHING)[source]¶

Bases: saltfactories.bases.Subprocess

Base daemon factory

Parameters

check_ports (list) – List of ports to try and connect to while confirming that the daemon is up and running
extra_cli_arguments_after_first_start_failure (tuple,) – Extra arguments to pass to the CLI that starts the daemon after the first failure
max_start_attempts (int) – Maximum number of attempts to try and start the daemon in case of failures
start_timeout (int) – The maximum number of seconds to wait before considering that the daemon did not start

Return type

None

Please look at Subprocess for the additional supported keyword arguments documentation.

before_start(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

after_start(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

before_terminate(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

after_terminate(callback, *args, **kwargs)[source]¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

get_check_ports()[source]¶: Return a list of ports to check against to ensure the daemon is running

start(*extra_cli_arguments, max_start_attempts=None, start_timeout=None)[source]¶: Start the daemon

started(*extra_cli_arguments, max_start_attempts=None, start_timeout=None)[source]¶: Start the daemon and return it’s instance so it can be used as a context manager

stopped(before_stop_callback=None, after_stop_callback=None, before_start_callback=None, after_start_callback=None)[source]¶

Parameters

before_stop_callback (Callable) – A callable to run before stopping the daemon. The callback must accept one argument, the daemon instance.
after_stop_callback (Callable) – A callable to run after stopping the daemon. The callback must accept one argument, the daemon instance.
before_start_callback (Callable) – A callable to run before starting the daemon. The callback must accept one argument, the daemon instance.
after_start_callback (Callable) – A callable to run after starting the daemon. The callback must accept one argument, the daemon instance.

This context manager will stop the factory while the context is in place, it re-starts it once out of context.

For example:

assert factory.is_running() is True

with factory.stopped():
    assert factory.is_running() is False

assert factory.is_running() is True

run_start_checks(started_at, timeout_at)[source]¶: Run checks to confirm that the daemon has started

cmdline(*args)¶

Construct a list of arguments to use when starting the subprocess

Parameters: args (str) – Additional arguments to use when starting the subprocess
Return type: list

get_base_script_args()¶: Returns any additional arguments to pass to the CLI script

get_display_name()¶: Returns a human readable name for the factory

get_script_args()¶: Returns any additional arguments to pass to the CLI script

get_script_path()¶: Returns the path to the script to run

is_running()¶: Returns true if the sub-process is alive

property pid¶: The pid of the running process. None if not running.

terminate()¶: Terminate the started daemon

class saltfactories.bases.Salt(*, config, python_executable=None, system_install=False)[source]¶

Bases: object

Base factory for salt cli’s and daemon’s

Parameters

config (dict) – The Salt config dictionary
python_executable (str) – The path to the python executable to use
system_install (bool) – If true, the daemons and CLI’s are run against a system installed salt setup, ie, the default salt system paths apply.

Return type

None

get_display_name()[source]¶: Returns a human readable name for the factory

class saltfactories.bases.SaltCliImpl(*, factory)[source]¶

Bases: saltfactories.bases.SubprocessImpl

Salt CLI’s subprocess interaction implementation

Please look at SubprocessImpl for the additional supported keyword arguments documentation.

Return type: None

cmdline(*args, minion_tgt=None, **kwargs)[source]¶

Construct a list of arguments to use when starting the subprocess

Parameters

args (str) – Additional arguments to use when starting the subprocess
minion_tgt (str) – The minion ID to target
kwargs – Additional keyword arguments will be converted into key=value pairs to be consumed by the salt CLI’s

init_terminal(cmdline, env=None)¶

Instantiate a terminal with the passed command line(cmdline) and return it.

Additionally, it sets a reference to it in self._terminal and also collects an initial listing of child processes which will be used when terminating the terminal

Parameters

cmdline (list,tuple) – List of strings to pass as args to Popen
environ (dict) – A dictionary of key, value pairs to add to the py:attr:saltfactories.base.Factory.environ.

is_running()¶

Returns: Returns true if the sub-process is alive
Return type: bool

property pid¶: The pid of the running process. None if not running.

run(*args, **kwargs)¶: Run the given command synchronously

terminate()¶

Terminate the started daemon

Return type: ProcessResult

class saltfactories.bases.SaltCli(*, config, python_executable=None, system_install=False, cwd=None, environ=None, script_name, base_script_args=NOTHING, slow_stop=True, timeout=NOTHING, hard_crash=False, merge_json_output=True)[source]¶

Bases: saltfactories.bases.Salt, saltfactories.bases.Process

Base factory for salt cli’s

Parameters: hard_crash (bool) – Pass --hard-crash to Salt’s CLI’s
Return type: None

Please look at Salt and Process for the additional supported keyword arguments documentation.

get_script_args()[source]¶: Returns any additional arguments to pass to the CLI script

cmdline(*args, minion_tgt=None, merge_json_output=None, **kwargs)[source]¶

Construct a list of arguments to use when starting the subprocess

Parameters

args (str) – Additional arguments to use when starting the subprocess
minion_tgt (str) – The minion ID to target
merge_json_output (bool) – The default behavior of salt outputters is to print one line per minion return, which makes parsing the whole output as JSON impossible when targeting multiple minions. If this value is True, an attempt is made to merge each JSON line into a single dictionary.
kwargs – Additional keyword arguments will be converted into key=value pairs to be consumed by the salt CLI’s

process_output(stdout, stderr, cmdline=None)[source]¶

Process the output. When possible JSON is loaded from the output.

Returns: Returns a tuple in the form of (stdout, stderr, loaded_json)
Return type: tuple

get_base_script_args()¶: Returns any additional arguments to pass to the CLI script

get_display_name()¶: Returns a human readable name for the factory

get_script_path()¶: Returns the path to the script to run

is_running()¶: Returns true if the sub-process is alive

property pid¶: The pid of the running process. None if not running.

run(*args, _timeout=None, **kwargs)¶

Run the given command synchronously

Parameters

args (list,tuple) – The list of arguments to pass to cmdline() to construct the command to run
_timeout (int) – The timeout value for this particular run() call. If this value is not None, it will be used instead of timeout, the default timeout.

terminate()¶: Terminate the started daemon

class saltfactories.bases.SystemdSaltDaemonImpl(*, factory, before_start_callbacks=NOTHING, after_start_callbacks=NOTHING, before_terminate_callbacks=NOTHING, after_terminate_callbacks=NOTHING)[source]¶

Bases: saltfactories.bases.DaemonImpl

Daemon systemd interaction implementation

Please look at DaemonImpl for the additional supported keyword arguments documentation.

Return type: None

cmdline(*args)[source]¶

Construct a list of arguments to use when starting the subprocess

Parameters: args (str) – Additional arguments to use when starting the subprocess

get_service_name()[source]¶: Return the systemd service name

is_running()[source]¶: Returns true if the sub-process is alive

internal_run(*args, **kwargs)[source]¶: Run the given command synchronously

start(*extra_cli_arguments, max_start_attempts=None, start_timeout=None)[source]¶

Start the daemon

Parameters

extra_cli_arguments (tuple,) – Extra arguments to pass to the CLI that starts the daemon
max_start_attempts (int) – Maximum number of attempts to try and start the daemon in case of failures
start_timeout (int) – The maximum number of seconds to wait before considering that the daemon did not start

property pid¶: The pid of the running process. None if not running.

after_start(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

after_terminate(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

before_start(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

before_terminate(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

get_start_arguments()¶

Return the arguments and keyword arguments used when starting the daemon:

Return type: StartDaemonCallArguments

init_terminal(cmdline, env=None)¶

Instantiate a terminal with the passed command line(cmdline) and return it.

Additionally, it sets a reference to it in self._terminal and also collects an initial listing of child processes which will be used when terminating the terminal

Parameters

cmdline (list,tuple) – List of strings to pass as args to Popen
environ (dict) – A dictionary of key, value pairs to add to the py:attr:saltfactories.base.Factory.environ.

run(*args, **kwargs)¶: Run the given command synchronously

terminate()¶: Terminate the daemon

class saltfactories.bases.SaltDaemon(*, config, python_executable=None, system_install=False, cwd=None, environ=None, script_name, base_script_args=NOTHING, slow_stop=True, check_ports=None, factories_manager=None, start_timeout, max_start_attempts=3, extra_cli_arguments_after_first_start_failure=NOTHING, event_listener=None, started_at=None)[source]¶

Bases: saltfactories.bases.Salt, saltfactories.bases.Daemon

Base factory for salt daemon’s

Please look at Salt and Daemon for the additional supported keyword arguments documentation.

Return type: None

classmethod configure(factories_manager, daemon_id, root_dir=None, defaults=None, overrides=None, **configure_kwargs)[source]¶: Configure the salt daemon

classmethod write_config(config)[source]¶: Write the configuration to file

classmethod load_config(config_file, config)[source]¶: Should return the configuration as the daemon would have loaded after parsing the CLI

get_check_events()[source]¶: Return a list of tuples in the form of (master_id, event_tag) check against to ensure the daemon is running

cmdline(*args)[source]¶

Construct a list of arguments to use when starting the subprocess

Parameters: args (str) – Additional arguments to use when starting the subprocess

run_start_checks(started_at, timeout_at)[source]¶: Run checks to confirm that the daemon has started

after_start(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

after_terminate(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

before_start(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

before_terminate(callback, *args, **kwargs)¶

Parameters

callback (Callable) – The function to call back
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback

get_base_script_args()¶: Returns any additional arguments to pass to the CLI script

get_check_ports()¶: Return a list of ports to check against to ensure the daemon is running

get_display_name()¶: Returns a human readable name for the factory

get_script_args()¶: Returns any additional arguments to pass to the CLI script

get_script_path()¶: Returns the path to the script to run

is_running()¶: Returns true if the sub-process is alive

property pid¶: The pid of the running process. None if not running.

start(*extra_cli_arguments, max_start_attempts=None, start_timeout=None)¶: Start the daemon

started(*extra_cli_arguments, max_start_attempts=None, start_timeout=None)¶: Start the daemon and return it’s instance so it can be used as a context manager

stopped(before_stop_callback=None, after_stop_callback=None, before_start_callback=None, after_start_callback=None)¶

Parameters

before_stop_callback (Callable) – A callable to run before stopping the daemon. The callback must accept one argument, the daemon instance.
after_stop_callback (Callable) – A callable to run after stopping the daemon. The callback must accept one argument, the daemon instance.
before_start_callback (Callable) – A callable to run before starting the daemon. The callback must accept one argument, the daemon instance.
after_start_callback (Callable) – A callable to run after starting the daemon. The callback must accept one argument, the daemon instance.

This context manager will stop the factory while the context is in place, it re-starts it once out of context.

For example:

assert factory.is_running() is True

with factory.stopped():
    assert factory.is_running() is False

assert factory.is_running() is True

terminate()¶: Terminate the started daemon