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.

class Template(template)
clear()

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(name, group=None)

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(name, group=None)

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

get_location(name, group=None)

Return the location where the option is being set.

Parameters

  • name (str) – The name of the option.

  • group (str) – The name of the group of the option. Defaults to 'DEFAULT'.

Returns

LocationInfo

See also

Option Setting Locations

New in version 5.3.0.

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(opt, group=None)

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(opts, group=None)

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(opt, group=None, cli=False)

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(opts, group=None)

Register multiple option schemas at once.

reload_config_files()

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(name, default, group=None)

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

Raises

NoSuchOptError, NoSuchGroupError

set_override(name, override, group=None)

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

Raises

NoSuchOptError, NoSuchGroupError

unregister_opt(opt, group=None)

Unregister an option.

Parameters

  • opt – an Opt object

  • group – an optional OptGroup object or group name

Raises

ArgsAlreadyParsedError, NoSuchGroupError

unregister_opts(opts, group=None)

Unregister multiple CLI option schemas at once.