Launchers¶

A launcher is a fancy python function, but implemented using OOP.

You can break it in 4 components:

some user configurable options.
a execution block that will use the user provided options.
how it can be serialized in the yaml syntax.
an unique identifier to refers to it

Kloch comes with a bunch of built-in launchers:

.base : An abstract launcher whose only purpose is to be merged with other launchers.
.system : A simple launcher executing the given command in the default system console.
.python : A launcher that execute the given python file with kloch’s own interpreter.

But you can implement as much as you want using the Launcher Plugins system.

The .base launch is particular because all launchers inherit from it. Which mean all launcher, even custom will at least have the options of the .base launcher. But it’s also handled differently when specified in a profile file because its option values will be used as base to merge all the other launchers values over it (example in .base inheritance).

builtin launchers¶

The following describe how to configure the builtin launchers in the Profile File.

.base¶

An abstract launcher whose only purpose is to be merged with other launchers.

This launcher is never launched and is simply merged with other launchers defined in the profile.

➡parent	:launchers:.base
⬇key
`environ`	required	no
	type	Dict[str, Union[str, List[str]]]
	description	mapping of environment variable to set before starting the environment. The value can either be a regular string or a list of string. The list of string has each item joined using the system path separator [2]. All values have environment variables expanded with `os.expandvars` [1]. You can escape the expansion by doubling the `$` like `$$` All values are turned absolute and normalized [4] if they are existing paths.
`merge_system_environ`	required	no
	type	<class ‘bool’>
	description	True to implicitly merge the system environment (from the machine reading the profile) with the potentially specified `environ` field. The system environ is merged as “base” so any key specified in the `environ` will override it.
`command`	required	no
	type	List[str]
	description	Arbitrary list of command line arguments to call at the end of the launcher execution.
`cwd`	required	no
	type	<class ‘str’>
	description	Filesystem path to an existing directory to use as “current working directory”. The path will have environment variables expanded with `os.expandvars` [1]. You can escape the expansion by doubling the `$` like `$$`. You can also use variables defined in the `environ` key. The path is turned absolute and normalized [4].
`priority`	required	no
	type	<class ‘int’>
	description	How much you should privilege this launcher to be used over other launchers.Higher number means higher priority.

.system¶

A simple launcher executing the given command in the default system console.

The launcher will just set the given environment variables for the session,execute the command, then exit. Which make it useless without a command specified.

The launcher use subprocess.run to execute the command.

➡parent	:launchers:.system
⬇key
`environ`	required	no
	type	Dict[str, Union[str, List[str]]]
	description	mapping of environment variable to set before starting the environment. The value can either be a regular string or a list of string. The list of string has each item joined using the system path separator [2]. All values have environment variables expanded with `os.expandvars` [1]. You can escape the expansion by doubling the `$` like `$$` All values are turned absolute and normalized [4] if they are existing paths.
`merge_system_environ`	required	no
	type	<class ‘bool’>
	description	True to implicitly merge the system environment (from the machine reading the profile) with the potentially specified `environ` field. The system environ is merged as “base” so any key specified in the `environ` will override it.
`command`	required	no
	type	List[str]
	description	Arbitrary list of command line arguments to call at the end of the launcher execution.
`cwd`	required	no
	type	<class ‘str’>
	description	Filesystem path to an existing directory to use as “current working directory”. The path will have environment variables expanded with `os.expandvars` [1]. You can escape the expansion by doubling the `$` like `$$`. You can also use variables defined in the `environ` key. The path is turned absolute and normalized [4].
`priority`	required	no
	type	<class ‘int’>
	description	How much you should privilege this launcher to be used over other launchers.Higher number means higher priority.
`command_as_str`	required	no
	type	<class ‘bool’>
	description	If True a str is passed to `subprocess.run`, else a list is passed. This can be useful in the context of setting `shell=True` or not on UNIX platforms.
`subprocess_kwargs`	required	no
	type	<class ‘dict’>
	description	Mapping of kwargs to pass to the internal `subprocess.run` call.
`expand_first_arg`	required	no
	type	<class ‘bool’>
	description	If True the first argument of the passed command will be expanded using `shutil.which` to find its executable file on disk. Will raise if no path is found. Useful for avoiding using `shell=True` in `subprocess_kwargs`.

.python¶

A launcher that execute the given python file with kloch’s own interpreter.

Execute the given python file with the python interpreter used to run kloch.

Any command will be basse as command line arguments to the script.

➡parent	:launchers:.python
⬇key
`environ`	required	no
	type	Dict[str, Union[str, List[str]]]
	description	mapping of environment variable to set before starting the environment. The value can either be a regular string or a list of string. The list of string has each item joined using the system path separator [2]. All values have environment variables expanded with `os.expandvars` [1]. You can escape the expansion by doubling the `$` like `$$` All values are turned absolute and normalized [4] if they are existing paths.
`merge_system_environ`	required	no
	type	<class ‘bool’>
	description	True to implicitly merge the system environment (from the machine reading the profile) with the potentially specified `environ` field. The system environ is merged as “base” so any key specified in the `environ` will override it.
`command`	required	no
	type	List[str]
	description	Arbitrary list of command line arguments passed to the python file.
`cwd`	required	no
	type	<class ‘str’>
	description	Filesystem path to an existing directory to use as “current working directory”. The path will have environment variables expanded with `os.expandvars` [1]. You can escape the expansion by doubling the `$` like `$$`. You can also use variables defined in the `environ` key. The path is turned absolute and normalized [4].
`priority`	required	no
	type	<class ‘int’>
	description	How much you should privilege this launcher to be used over other launchers.Higher number means higher priority.
`python_file`	required	yes
	type	<class ‘str’>
	description	Filesystem path to an existing python file. The path will have environment variables expanded with `os.expandvars` [1]. The path is turned absolute and normalized. [4]

References