Environment variable types

The envprobe.vartypes package implements the logic that maps different environment variables allows Envprobe to interface with system shells.

class EnvVar(name, raw_value)

Base class for an environment variable type’s implementation.

Note

The implementations of this class are responsible for handling the type of an environment variable. The classes are instantiated with a given value, and are detached from actual environment afterwards, i.e. a change in the environment will NOT be reflected by what is available from the instances.

Parameters

name (str) – The name of the environment variable.
raw_value (str) – The stringified raw value of the environment variable, as present in the operating system.

apply_diff(diff)

Applies the given difference to the value of the instance.

Parameters: diff (list(char, str)) – A difference action list, as returned by EnvVar.diff().
Raises: ValueError – If the diff is invalid or non-applicable.

Note

In most cases, the - (remove) side of the diff is ignored when applying.

classmethod diff(old, new)

Generate an iterable difference “actions” between two variables.

Parameters

old (EnvVar or None) – The “left” or “baseline” side of the diff.
new (EnvVar or None) – The “right” or “new” side of the diff.

Returns

The differences between the two variables’ values.

The first element of the tuple, (char), is either +, - or = for new/added, old/removed, and unchanged, respectively. For each entry in the list, the second element (str) is the affected value itself. The description of the difference is always of type str.

If either the old or the new did not contain a value, the respective side will be missing from the list.

If the two variables are equal, an empty list is returned.

Return type

list(char, str)

Raises

TypeError – Only variables of the same type, and only subclasses of EnvVar may be differentiated.

Note

The implementation for the actual calculating of the difference should be provided in the overridden method _diff() in the subclasses.

property extended_attributes

Returns the object managing the extended attributes (user-facing knowledge) about the variable.

Returns: configuration
Return type: EnvVarExtendedInformation

classmethod merge_diff(diff_a, diff_b)

Creates a merged diff from two diffs that simulates the transitive application of the first and the second diff in order.

Parameters

diff_a (list(char, str)) – The difference actions to apply first, as returned by EnvVar.diff().
diff_b (list(char, str)) – The difference actions to apply second, in the same format.

Returns

The merged difference actions’ list. The format is kept.

Return type

list(char, str)

Raises

ValueError – If the diff is invalid or non-applicable.

property name: The name of the variable.

abstract raw(): Convert the value of the variable to a raw shell representation.

classmethod type_description(): The description of the environment variable type.

abstract property value

Retrieves the value of the environment variable.

Returns: The value. The (Python) type of the returned value is specific to the subclass.
Return type: unknown

The extended information for an environment variable is stored in objects of the following class.

class EnvVarExtendedInformation

Implements a storage for the extended user-facing knowledge about a variable.

apply(configuration)

Applies the persisted configuration on the current object.

Parameters: configuration (dict) – The configuration mapping too apply. See envprobe.settings.variable_information.VariableInformation.__getitem__() for the format generated.

property description: The human description about the usage of the variable.

property source: The annotated source repository where the variable’s information was obtained from.

property type: The type class identifier (kind) for the current variable.

Implemented types

The list of known variable types in Envprobe are documented in the pages accessible from the links below.

`string.String`	The standard type of environment variables.
`numeric.Numeric`	This type may only hold a numeric (`int` or `float`) value.
`array.Array`	An environment variable where elements are separated by a `separator`.
`colon_separated.ColonSeparatedArray`	A helper class that binds the array's `separator` to `:`.
`semi_separated.SemicolonSeparatedArray`	A helper class that binds the array's `separator` to `;`.
`path.Path`	A POSIX-compatible `PATH` environment variable.

Dynamic loading

The library is designed to be dynamically loading the individual environment variable type 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 environment variable type, 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 EnvVar implementations.

Returns: The names.
Return type: list(str)

load(kind)

Attempt to load an EnvVar implementation.

The function loads the module kind from envprobe.vartypes and expects it to register the EnvVar named kind.

Parameters

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

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 implementation with the name kind registered by it.

load_all()

Loads all EnvVar implementations to the interpreter found under envprobe.vartypes in the install.

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

Registering implementations

register_type(kind, clazz)

Register the EnvVar implementation to the dynamic lookup mechanism.

Parameters

kind (str) – The name of the environment variable type implementation.
clazz (class) – The Python class that implements the functions.

Raises

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

Example

The implementing modules of EnvVar 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 Circle in envprobe.vartypes.circle

from envprobe.vartypes.envvar import EnvVar, register_type

class Circle(EnvVar):
    # ... the implementation of the class ...

register_type('circle', Circle)