Option Definitions

class oslo_config.cfg.Opt(name, type=None, dest=None, short=None, default=None, positional=False, metavar=None, help=None, secret=False, required=False, deprecated_name=None, deprecated_group=None, deprecated_opts=None, sample_default=None, deprecated_for_removal=False)

Base class for all configuration options.

The only required parameter is the option’s name. However, it is common to also supply a default and help string for all options.

Parameters:
  • name – the option’s name
  • type – the option’s type. Must be a callable object that takes string and returns converted and validated value
  • dest – the name of the corresponding ConfigOpts property
  • short – a single character CLI option name
  • default – the default value of the option
  • positional – True if the option is a positional CLI argument
  • metavar – the option argument to show in –help
  • help – an explanation of how the option is used
  • secret – true iff the value should be obfuscated in log output
  • required – true iff a value must be supplied for this option
  • deprecated_name – deprecated name option. Acts like an alias
  • deprecated_group – the group containing a deprecated alias
  • deprecated_opts – array of DeprecatedOpt(s)
  • sample_default – a default string for sample config files
  • deprecated_for_removal – indicates whether this opt is planned for removal in a future release

An Opt object has no public methods, but has a number of public properties:

name:
the name of the option, which may include hyphens
type:
a callable object that takes string and returns converted and validated value. Default types are available from oslo_config.types
dest:
the (hyphen-less) ConfigOpts property which contains the option value
short:
a single character CLI option name
default:
the default value of the option
sample_default:
a sample default value string to include in sample config files
positional:
True if the option is a positional CLI argument
metavar:
the name shown as the argument to a CLI option in –help output
help:
a string explaining how the option’s value is used
class oslo_config.cfg.StrOpt(name, choices=None, **kwargs)

Option with String type

Option with type oslo_config.types.String

Kept for backward-compatibility with options not using Opt directly.

Parameters:choices – Optional sequence of valid values.
class oslo_config.cfg.BoolOpt(name, **kwargs)

Boolean options.

Bool opts are set to True or False on the command line using –optname or –noopttname respectively.

In config files, boolean values are cast with Boolean type.

class oslo_config.cfg.IntOpt(name, **kwargs)

Option with Integer type

Option with type oslo_config.types.Integer

Kept for backward-compatibility with options not using Opt directly.

class oslo_config.cfg.FloatOpt(name, **kwargs)

Option with Float type

Option with type oslo_config.types.Float

Kept for backward-communicability with options not using Opt directly.

class oslo_config.cfg.ListOpt(name, **kwargs)

Option with List(String) type

Option with type oslo_config.types.List

Kept for backward-compatibility with options not using Opt directly.

class oslo_config.cfg.DictOpt(name, **kwargs)

Option with Dict(String) type

Option with type oslo_config.types.Dict

Kept for backward-compatibility with options not using Opt directly.

class oslo_config.cfg.MultiOpt(name, item_type, **kwargs)

Multi-value option.

Multi opt values are typed opts which may be specified multiple times. The opt value is a list containing all the values specified.

Parameters:
  • name – Name of the config option
  • item_type – Type of items (see oslo_config.types)

For example:

cfg.MultiOpt('foo',
             item_type=types.Integer(),
             default=None,
             help="Multiple foo option")

The command line --foo=1 --foo=2 would result in cfg.CONF.foo containing [1,2]

class oslo_config.cfg.MultiStrOpt(name, **kwargs)

MultiOpt with a MultiString item_type.

MultiOpt with a default oslo_config.types.MultiString item type.

Kept for backwards-compatibility for options that do not use MultiOpt directly.

class oslo_config.cfg.IPOpt(name, version=None, **kwargs)

Opt with IPAddress type

Option with type oslo_config.types.IPAddress

Parameters:version – one of either 4, 6, or None to specify either version.
class oslo_config.cfg.DeprecatedOpt(name, group=None)

Represents a Deprecated option.

Here’s how you can use it:

oldopts = [cfg.DeprecatedOpt('oldopt1', group='group1'),
           cfg.DeprecatedOpt('oldopt2', group='group2')]
cfg.CONF.register_group(cfg.OptGroup('group1'))
cfg.CONF.register_opt(cfg.StrOpt('newopt', deprecated_opts=oldopts),
                      group='group1')

For options which have a single value (like in the example above), if the new option is present (“[group1]/newopt” above), it will override any deprecated options present (“[group1]/oldopt1” and “[group2]/oldopt2” above).

If no group is specified for a DeprecatedOpt option (i.e. the group is None), lookup will happen within the same group the new option is in. For example, if no group was specified for the second option ‘oldopt2’ in oldopts list:

oldopts = [cfg.DeprecatedOpt('oldopt1', group='group1'),
           cfg.DeprecatedOpt('oldopt2')]
cfg.CONF.register_group(cfg.OptGroup('group1'))
cfg.CONF.register_opt(cfg.StrOpt('newopt', deprecated_opts=oldopts),
                      group='group1')

then lookup for that option will happen in group ‘group1’.

If the new option is not present and multiple deprecated options are present, the option corresponding to the first element of deprecated_opts will be chosen.

Multi-value options will return all new and deprecated options. So if we have a multi-value option “[group1]/opt1” whose deprecated option is “[group2]/opt2”, and the conf file has both these options specified like so:

[group1]
opt1=val10,val11

[group2]
opt2=val21,val22

Then the value of “[group1]/opt1” will be [‘val11’, ‘val12’, ‘val21’, ‘val22’].

class oslo_config.cfg.SubCommandOpt(name, dest=None, handler=None, title=None, description=None, help=None)

Sub-command options.

Sub-command options allow argparse sub-parsers to be used to parse additional command line arguments.

The handler argument to the SubCommandOpt constructor is a callable which is supplied an argparse subparsers object. Use this handler callable to add sub-parsers.

The opt value is SubCommandAttr object with the name of the chosen sub-parser stored in the ‘name’ attribute and the values of other sub-parser arguments available as additional attributes.

class oslo_config.cfg.OptGroup(name, title=None, help=None)

Represents a group of opts.

CLI opts in the group are automatically prefixed with the group name.

Each group corresponds to a section in config files.

An OptGroup object has no public methods, but has a number of public string properties:

name:
the name of the group
title:
the group title as displayed in –help
help:
the group description as displayed in –help

Previous topic

The cfg Module

Next topic

Option Types and Validation

This Page