ConfigSection Class

class AdvConfigMgr.ConfigSection(manager, name, verbose_name=None, description=None, storage_write_to=None, storage_read_from_only=None, store_default=False, locked=False, allow_create_on_load=True, allow_create_on_set=True, option_defaults=None, cli_section_title=None, cli_section_desc=None, version=None, version_option_name=None, version_migrations=None, options=None)

A single section of a config

Parameters:

• manager (ConfigManager) – A pointer to the config manager
• name (str) – The name of the section
• verbose_name (str) – The verbose name of the section
• description (str) – A long description of the section
• storage_write_to (str) – The tag of the storage location to save to, if None, the section will be saved to the default location, if ‘-‘ it will not be saved in save_all operations, if “*”, section will be saved to all configured storage locations. Sections can be saved manually to any storage if needed.
• storage_read_from_only (str or list) – options from storage with tags in this list will be read. If None (default) then options in storage will be always be used. This allows restricting options to specific storage locations. CLI options, if configured, will always overwrite data from storage.
• store_default (bool) – store defaults in storage medium
• locked (bool) – if True, do not allow any changes to the section
• allow_create_on_load (bool) – if True, options will be created if they are in the stored data, if false, they must be configured first.
• allow_create_on_set (bool) – if True, options can be created using a dictionary set proces, if False, they need to be configured first.
• cli_section_title (str) – the name of the section in the CLI (if sectioned), Defaults to verbose_name
• cli_section_desc (str) – the description for the section in the CLI (if sectioned), Defaults to description
• version (str) – the version number of the section, if None, this will take the version number of the ConfigManager object.
• version_option_name (str) – allows for overriding the ConfigManager’s version_option_name setting.

add(*args, **kwargs)

Adds new option definition to the system

args, kwargs: config options can also be passed in args/kwargs, in a number of formats.

Examples:

This does not set any default values:

add('option1', 'option2', 'option3')

Seperate dictionaries:

add(full_option_dict, full_option_dict)

A list of dictionaries:

add([full_option_dict, full_option_dict])

A list of sets with option_name and default value.:

add([('option1',default_value),('option2',default_value)]

If default value is a dict, this will not work, if a dict is passed, it is assumed to be a full_option_dict:

add(option1=default_value1, option2=default_value2, option3=default_value3)

add(option1={full_option_dict}, option2={full_option_dict))

These can be mixed, so the following would be valid:

add('option1', full_option_dict, [full_option_dict, full_option_dict], [('option2',default_value)])

full_option_dict Example (with defaults):

‘name’: ‘<name of option>’, ‘default_value’: _UNSET, ‘datatype’: None, ‘verbose_name’: None, ‘description’: None, ‘cli_option’: None, ‘validations’: None, ‘do_not_change’: False, ‘do_not_delete’: False, ‘required_after_load’: False,

Note

• If a default value is a dictionary, it must be passed within a full option dict.

• See ConfigOption for option_dict parameters.

• If a full option dict is passed as an arg (not kwarg) it must contain a ‘name’ key.

• Args and kwargs can be mixed if needed... for example this is also a valid approach:

  add(option1, <full_option_dict>, option3=default_value, option4={full_option_dict}
  

• If options are repeated in the same commane, kwargs will take precdence over args, and new options will overwrite old ones.

• if there are existing options in the section with the same name, an error will be raised.

clear(options, forgiving=False)

Will set the option to the default value or to unset as long as long as the section is not locked.

Parameters:

• options (str or list) – option name or list of option names
• forgiving (bool) – True will return False if the option is not found, False, will raise NoOptionError.

Returns:

True if all deletes passed, False if not. if False, a list of the failed options is stored in self.last_failure_list

Return type:

bool

Raises:

NoOptionError – If the option does not exist. and forgiving is False.

delete(options, force=False, forgiving=False)

Will delete a list of options.

Parameters:

• options – Option name or list of option names.
• force (bool) – True will delete the object even if it has a default_value without checking for value or lock.
• forgiving (bool) – True will return False if the option is not found, False, will raise NoOptionError.

Type:

str or list

Returns:

True if all deletes passed, False if not. if False, a list of the failed options is stored in ConfigSection.last_failure_list

Return type:

bool

from_read(option, value, raw=False, validate=True)

adds data from a storage module to the system, this ignores the ‘do_not_add’ flag. :param str option: option name :param value: the value to add :param bool raw: True if the interpolation needs to be bypassed. :param bool validate: True if validation should happen. :return:

get(option, fallback=Empty Value, raw=False)

gets the value of an option

Parameters:

• option – the name of the option
• fallback – a value to return if the option is empty
• raw – a flag to skip interpolation

Returns:

items(raw=False)

Return a list of (name, value) tuples for each option in a section.

All interpolations are expanded in the return values, based on the defaults passed into the constructor, unless the optional argument ‘raw’ is true.

Parameters:raw (bool) – True if data should not be interpolated.

load(option, value, *args, **kwargs)

Loads value into system, can create new options if “allow_create_on_load” is set.

Parameters:

• name – Option Name
• value – Option Value
• args – as per ConfigOption class (passed through)
• kwargs – as per ConfigOption class (passed through)

section_ok_after_load

validates that all options that are required “after_load” have either a set or default value :return: :rtype boolean:

set(option, value, raw=False, validate=True, force=False)

Sets an option value.

Parameters:

• option – the name of the option to set
• value – the value to set
• raw – if set to True will bypass the interpolater
• validate – if False will bypass the validation steps
• force – if True will bypass the lock checks, used for loading data.

Returns:

the interpolated value or default value.

to_write(option, raw=False, as_string=False)

gets data from the system to save to a storage module :param bool raw: :param bool as_string: :return: