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 ConfigOpts.StrSubWrapper(conf, group=None, namespace=None)

Helper class.

Exposes opt values as a dict for string substitution.

class ConfigOpts.SubCommandAttr(conf, group, dest)

Helper class.

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

ConfigOpts.clear(*args, **kwargs)

Clear the state of the object to before it was called.

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

ConfigOpts.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
ConfigOpts.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
ConfigOpts.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
ConfigOpts.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
ConfigOpts.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
ConfigOpts.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.

ConfigOpts.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()
ConfigOpts.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.

Return {(None or ‘group’, ‘optname’):
 (old_value, new_value), ... }

:raises Error if reloading fails

ConfigOpts.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
ConfigOpts.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
ConfigOpts.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
ConfigOpts.register_cli_opts(*args, **kwargs)

Register multiple CLI option schemas at once.

ConfigOpts.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
ConfigOpts.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.

:return None

ConfigOpts.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
ConfigOpts.register_opts(*args, **kwargs)

Register multiple option schemas at once.

ConfigOpts.reload_config_files(*args, **kwargs)

Reload configure files and parse all options

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

ConfigOpts.reset()

Clear the object state and unset overrides and defaults.

ConfigOpts.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
ConfigOpts.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
ConfigOpts.unregister_opt(*args, **kwargs)

Unregister an option.

Parameters:
  • opt – an Opt object
  • group – an optional OptGroup object or group name
Raises:

ArgsAlreadyParsedError, NoSuchGroupError
ConfigOpts.unregister_opts(*args, **kwargs)

Unregister multiple CLI option schemas at once.