The ConfigOpts Class¶

class oslo_config.cfg.ConfigOpts¶

Config options which may be set on the command line or in config files.

ConfigOpts is a configuration option manager with APIs for registering option schemas, grouping options, parsing option values and retrieving the values of options.

It has built-in support for config_file and config_dir options.

class GroupAttr(conf, group)¶

Helper class.

Represents the option values of a group as a mapping and attributes.

class StrSubWrapper(conf, group=None, namespace=None)¶

Helper class.

Exposes opt values as a dict for string substitution.

class SubCommandAttr(conf, group, dest)¶

Helper class.

Represents the name and arguments of an argparse sub-parser.

clear(*args, **kwargs)¶

Reset the state of the object to before options were registered.

This method removes all registered options and discards the data from the command line and configuration files.

Any subparsers added using the add_cli_subparsers() will also be removed as a side-effect of this method.

clear_default(*args, **kwargs)¶

Clear an override an opt’s default value.

Clear a previously set override of the default value of given option.

Parameters:	name – the name/dest of the opt group – an option OptGroup object or group name
Raises:	NoSuchOptError, NoSuchGroupError

clear_override(*args, **kwargs)¶

Clear an override an opt value.

Clear a previously set override of the command line, config file and default values of a given option.

Parameters:	name – the name/dest of the opt group – an option OptGroup object or group name
Raises:	NoSuchOptError, NoSuchGroupError

find_file(name)¶

Locate a file located alongside the config files.

Search for a file with the supplied basename in the directories which we have already loaded config files from and other known configuration directories.

The directory, if any, supplied by the config_dir option is searched first. Then the config_file option is iterated over and each of the base directories of the config_files values are searched. Failing both of these, the standard directories searched by the module level find_config_files() function is used. The first matching file is returned.

Parameters:	name – the filename, for example ‘policy.json’
Returns:	the path to a matching file, or None

import_group(group, module_str)¶

Import an option group from a module.

Import a module and check that a given option group is registered.

This is intended for use with global configuration objects like cfg.CONF where modules commonly register options with CONF at module load time. If one module requires an option group defined by another module it can use this method to explicitly declare the dependency.

Parameters:	group – an option OptGroup object or group name module_str – the name of a module to import
Raises:	ImportError, NoSuchGroupError

import_opt(name, module_str, group=None)¶

Import an option definition from a module.

Import a module and check that a given option is registered.

This is intended for use with global configuration objects like cfg.CONF where modules commonly register options with CONF at module load time. If one module requires an option defined by another module it can use this method to explicitly declare the dependency.

Parameters:	name – the name/dest of the opt module_str – the name of a module to import group – an option OptGroup object or group name
Raises:	NoSuchOptError, NoSuchGroupError

list_all_sections()¶

List all sections from the configuration.

Returns a sorted list of all section names found in the configuration files, whether declared beforehand or not.

log_opt_values(logger, lvl)¶

Log the value of all registered opts.

It’s often useful for an app to log its configuration to a log file at startup for debugging. This method dumps to the entire config state to the supplied logger at a given log level.

Parameters:	logger – a logging.Logger object lvl – the log level (for example logging.DEBUG) arg to logger.log()

mutate_config_files()¶

Reload configure files and parse all options.

Only options marked as ‘mutable’ will appear to change.

Hooks are called in a NON-DETERMINISTIC ORDER. Do not expect hooks to be called in the same order as they were added.

Returns:	{(None or ‘group’, ‘optname’): (old_value, new_value), … }
Raises:	Error if reloading fails

print_help(file=None)¶

Print the help message for the current program.

This method is for use after all CLI options are known registered using __call__() method. If this method is called before the __call__() is invoked, it throws NotInitializedError

Parameters:	file – the File object (if None, output is on sys.stdout)
Raises:	NotInitializedError

print_usage(file=None)¶

Print the usage message for the current program.

This method is for use after all CLI options are known registered using __call__() method. If this method is called before the __call__() is invoked, it throws NotInitializedError

Parameters:	file – the File object (if None, output is on sys.stdout)
Raises:	NotInitializedError

register_cli_opt(*args, **kwargs)¶

Register a CLI option schema.

CLI option schemas must be registered before the command line and config files are parsed. This is to ensure that all CLI options are shown in –help and option validation works as expected.

Parameters:	opt – an instance of an Opt sub-class group – an optional OptGroup object or group name
Returns:	False if the opt was already registered, True otherwise
Raises:	DuplicateOptError, ArgsAlreadyParsedError

register_cli_opts(*args, **kwargs)¶

Register multiple CLI option schemas at once.

register_group(group)¶

Register an option group.

An option group must be registered before options can be registered with the group.

Parameters:	group – an OptGroup object

register_mutate_hook(hook)¶

Registers a hook to be called by mutate_config_files.

Parameters:	hook – a function accepting this ConfigOpts object and a dict of config mutations, as returned by mutate_config_files.
Returns:	None

register_opt(*args, **kwargs)¶

Register an option schema.

Registering an option schema makes any option value which is previously or subsequently parsed from the command line or config files available as an attribute of this object.

Parameters:	opt – an instance of an Opt sub-class group – an optional OptGroup object or group name cli – whether this is a CLI option
Returns:	False if the opt was already registered, True otherwise
Raises:	DuplicateOptError

register_opts(*args, **kwargs)¶

Register multiple option schemas at once.

reload_config_files(*args, **kwargs)¶

Reload configure files and parse all options

Returns:	False if reload configure files failed or else return True

reset()¶

Clear the object state and unset overrides and defaults.

set_default(*args, **kwargs)¶

Override an opt’s default value.

Override the default value of given option. A command line or config file value will still take precedence over this default.

Parameters:	name – the name/dest of the opt default – the default value group – an option OptGroup object or group name enforce_type – a boolean whether to convert the default value to the option’s type, None is not converted even if enforce_type is True.
Raises:	NoSuchOptError, NoSuchGroupError

set_override(*args, **kwargs)¶

Override an opt value.

Override the command line, config file and default values of a given option.

Parameters:	name – the name/dest of the opt override – the override value group – an option OptGroup object or group name enforce_type – a boolean whether to convert the override value to the option’s type, None is not converted even if enforce_type is True.
Raises:	NoSuchOptError, NoSuchGroupError

unregister_opt(*args, **kwargs)¶

Unregister an option.

Parameters:	opt – an Opt object group – an optional OptGroup object or group name
Raises:	ArgsAlreadyParsedError, NoSuchGroupError

unregister_opts(*args, **kwargs)¶

Unregister multiple CLI option schemas at once.