CLI config utilities

Overview

Path	PyPoE/cli/config.py
Version	1.0.0a0
Revision	$Id: 2455f8f32d14f2910c3f21d015465883de77e524 $
Author	Omega_K2

Description

Utilities to setup the config on the CLI interface.

Documentation

Classes

class PyPoE.cli.config.ConfigHelper(*args, **kwargs)

Bases: configobj.ConfigObj

Extended regular config obj that can perform special tasks and extended handling.

Generally the new options should be used over the direct usage of inherited functions.

__init__(*args, **kwargs)

Raises:ValueError – if the infile configobj.ConfigObj parameter is not specified

add_option(key, specification)

Adds (registers) a new config option with the specified key and specification. The key must be unique.

Parameters:

• key (str) – key to use for storage
• specification (str) – config specification string for validating values for this key

Raises:

KeyError – if the key is a duplicate

add_setup_listener(config_key, function)

Adds a listener for the specified config key that triggers when the config value was changed.

Function should take 3 arguments: * key: The key that was changed * value: the new value * old_value: the old value

Parameters:

• config_key (str) – config key to register the listener for
• function (callable) – callable to add as listener

Raises:

TypeError – if function is not callable

add_setup_variable(setup_key, variable_key, specification)

Adds a setup variable, i.e. a variable related to a specific setup

For example this is useful to store additional information required to check whether a new run of setup is needed.

Parameters:

• setup_key (str) – the setup key to register the variable for
• variable_key (str) – the key of the variable itself (must be unique)
• specification (str) – the config specification to use for the variable

Raises:

• KeyError – if the setup key does not exist
• KeyError – if the variable key is a duplicate

get_option(key, safe=True)

Returns the handled value for the specified key from the config.

If the safe option is specified the function will check if any setups for the specified key need to be formed and raises an Error if the setup is pending. If False this behaviour is disabled

Warning

if the specified key is missing this method will shutdown the CLI with an error message to configure the key

Parameters:

• key (str) – key to retrieve the value for
• safe (bool) – whether to check setup is needed

Returns:

handled value

Return type:

object

Raises:

SetupError – if the setup for the key was not performed

get_setup_variable(setup_key, variable_key)

Returns the stored variable for the specified setup key

Parameters:

• setup_key (str) – the setup key to retrieve the variable for
• variable_key (str) – the config key of the variable to retrieve

Returns:

the value of the variable

Return type:

object

is_setup(variable)

Returns whether the specified config key has it’s setup performed

Parameters:key (str) – the setup key to check Returns:True if setup is performed Return type:bool

needs_setup(key)

Returns whether the specified config key requires setup or not.

Warning

This does not return whether the setup is performed, only whether this is a config key that requires setup.

If you want to know whether setup was performed use is_setup.

Parameters:key (str) – the setup key to check Returns:True if setup needs to be performed Return type:bool

option

Returns config option section from the config handler.

Returns: Return type:configobj.Section

optionspec

Returns config option specification section from the config handler.

Returns: Return type:configobj.Section

register_setup(key, funcs)

Registers one or multiple functions that will be called to perform the setup for the specified config key.

This will also create the according setup keys if non existent

Note

Setup variables should be registered using this function before using any other ‘setup’ related functions.

Parameters:

• key (str) – config key to register the setup for
• funcs (callable or Iterable[callable]) – a function or iterable of functions to be called when the setup for the specified key is performed

Raises:

TypeError – if funcs is not callable

set_option(key, value)

Sets the key to the specified value.

The function will also take care of the following: - invalidate setups registered for this key, if any - validate the value - execute listeners

Parameters:

• key (str) – the option key to set
• value (object) – the value to set the key to

Raises:

validate.ValidationError – if the validation of the value failed

set_setup_variable(setup_key, variable_key, value)

Sets the value for the specified setup key and variable

Parameters:

• setup_key (str) – the setup key to set the variable for
• variable_key (str) – the config key of the variable to set
• value (object) – the value to set the variable to

Raises:

validate.ValidationError – if the validation of the value failed

setup

Returns config setup section from the config handler.

Returns: Return type:configobj.Section

setup_or_raise(variable)

Returns True if setup is performed for the specified config variable and raises an error if it isn’t.

Parameters:variable (str) – config variable to check against Returns:if setup is performed Return type:True Raises:SetupError – if setup is not performed

setupspec

Returns config setup specification section from the config handler.

Returns: Return type:configobj.Section

Exceptions

class PyPoE.cli.config.ConfigError

Bases: ValueError

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class PyPoE.cli.config.SetupError

Bases: ValueError

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Agreement

See PyPoE/LICENSE