Shell interface

The envprobe.shell package implements the logic that allows Envprobe to interface with system shells.

class CapabilityError

Indicates that the requested operation cannot be done in the current Shell.

get_current_shell(environment_dict)

Create a Shell based on the configured environment variables.

Returns

The Shell is instantiated with the environment settings.

Return type

Shell

Raises

• KeyError – Raised if the environment_dict did not contain the necessary variables configured.

• ModuleNotFoundError – Raised if the shell to be used was identified, but the implementation was unable to load.

class Shell(pid, configuration_dir, control_filename)

Base class for keeping configuration related to a running shell.

Parameters

• pid (int) – The process ID (pid) of the shell.

• configuration_dir (str) – The directory where the control and persistent data of the shell process will be stored.

• control_filename (str) – The name of the file which is used by the hook to execute commands in the shell’s context.

property configuration_directory

The configuration_dir the shell was constructed with.

This is the directory where the data of the shell hook is written to on storage.

Note

In almost all cases, this is a temporary directory!

property control_file

The full path to the control file the shell was constructed with.

The contents of this file are directives written in the target shell’s syntax, and is used to apply the changes commandeered by Envprobe in the shell’s context itself.

abstract get_shell_hook(envprobe_callback_location)

Create the shell code that drives Envprobe’s control evaluation.

This code should be evaluated inside the context of an existing shell process to faciliate execution of the control_file’s contents.

abstract get_shell_unhook()

Create the shell code that detaches/unhooks Envprobe.

This code should be evaluated inside the context of an existing shell process as an inverse operation of get_shell_hook().

abstract property is_envprobe_capable

Whether the current shell is capable of loading and meaningfully running Envprobe.

abstract property manages_environment_variables

Whether the current shell is capable of managing the environment variables through Envprobe.

set_environment_variable(env_var)

Write the code setting env_var’s value to the control_file.

Raises

CapabilityError – If the shell is not capable of managing environment variables.

Note

The implementation for the actual code writing should be provided in the overriden method _set_environment_variable() instead.

property shell_pid

The pid the shell was constructed with.

property shell_type

The identifier of the shell’s type as registered in Envprobe.

property state_file

The full path of the file persisted in storage that is used to store the “saved” state and knowledge about the shell.

unset_environment_variable(env_var)

Write the code that undefines env_var to the control_file.

Raises

CapabilityError – If the shell is not capable of managing environment variables.

Note

The implementation for the actual code writing should be provided in the overriden method _unset_environment_variable() instead.

Dynamic loading

The Shell library is designed to be dynamically loading the individual shell implementations. This is accomplished by the following functions, used extensively in clients of the library.

get_class(kind)

Retrieves the implementation class for the given name from the dynamic registry.

Parameters

kind (str) – The name of the shell, as registered.

Returns

The class implementation.

Return type

class

Raises

KeyError – Raised if the given kind is not registered.

get_kind(clazz)

Retrieves the name for the given implementation class from the dynamic registry.

Parameters

clazz (class) – The implementation class object.

Returns

The registered name for the implementation.

Return type

str

Raises

KeyError – Raised if the given clazz is not registered.

get_known_kinds()

Get the list of dynamically registered and loaded Shell implementations.

Returns

The names.

Return type

list(str)

load(kind)

Attempt to load a Shell implementation.

The function loads the module kind from envprobe.shell an expects it to register the Shell named kind.

Parameters

kind (str) – The name of the shell to load. The loading will be done from the similarly named Python module under envprobe.shell.

Returns

clazz – If the loading succeeded or the given kind is already loaded, the class implementation is returned.

Return type

class

Raises

• ModuleNotFoundError – Raised if the module to load is not found.

• NotImplementedError – Raised if the module successfully loaded, but there were no shell with the name kind registered by it.

load_all()

Loads all Shell implementations to the interpreter found under envprobe.shell in the install.

This method does not throw if a module does not actually register anything.

Registering implementations

register_type(kind, clazz)

Register the Shell implementation to the dynamic lookup mechanism.

Parameters

• kind (str) – The name of the shell implementation.

• clazz (class) – The Python class that implements the functions.

Raises

TypeError – clazz must be a type that is a subclass of Shell, otherwise an exception is raised.

Example

The implementing modules of Shell subclasses should be named similarly as the shell they are implementing, and after defining the class, in the global code of the module itself, a call to register_type should be present:

Registering a hypothetical implementation of the PytShell in envprobe.shell.pyt

from envprobe.shell.core import Shell, register_type

class Pyt(Shell):
    # ... the implementation of the class ...

register_type('pyt', Pyt)