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, deprecated_reason=None, deprecated_since=None, mutable=False, advanced=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 if the value should be obfuscated in log output
  • required – true if 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 – list of DeprecatedOpt
  • sample_default – a default string for sample config files
  • deprecated_for_removal – indicates whether this opt is planned for removal in a future release
  • deprecated_reason – indicates why this opt is planned for removal in a future release. Silently ignored if deprecated_for_removal is False
  • deprecated_since – indicates which release this opt was deprecated in. Accepts any string, though valid version strings are encouraged. Silently ignored if deprecated_for_removal is False
  • mutable – True if this option may be reloaded
  • advanced – a bool True/False value if this option has advanced usage and is not normally used by the majority of users

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

advanced

in sample files, a bool value indicating the option is advanced

Changed in version 1.2: Added deprecated_opts parameter.

Changed in version 1.4: Added sample_default parameter.

Changed in version 1.9: Added deprecated_for_removal parameter.

Changed in version 2.7: An exception is now raised if the default value has the wrong type.

Changed in version 3.2: Added deprecated_reason parameter.

Changed in version 3.5: Added mutable parameter.

Changed in version 3.12: Added deprecated_since parameter.

Changed in version 3.15: Added advanced parameter and attribute.

class oslo_config.cfg.StrOpt(name, choices=None, quotes=None, regex=None, ignore_case=None, max_length=None, **kwargs)

Option with String type

Option with type oslo_config.types.String

Parameters:
  • name – the option’s name
  • choices – Optional sequence of valid values.
  • quotes – If True and string is enclosed with single or double quotes, will strip those quotes.
  • regex – Optional regular expression (string or compiled regex) that the value must match on an unanchored search.
  • ignore_case – If True case differences (uppercase vs. lowercase) between ‘choices’ or ‘regex’ will be ignored.
  • max_length – If positive integer, the value must be less than or equal to this parameter.
  • **kwargs – arbitrary keyword arguments passed to Opt

Changed in version 2.7: Added quotes parameter

Changed in version 2.7: Added regex parameter

Changed in version 2.7: Added ignore_case parameter

Changed in version 2.7: Added max_length parameter

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

Boolean options.

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

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

Parameters:
  • name – the option’s name
  • **kwargs – arbitrary keyword arguments passed to Opt
class oslo_config.cfg.IntOpt(name, min=None, max=None, **kwargs)

Option with Integer type

Option with type oslo_config.types.Integer

Parameters:
  • name – the option’s name
  • min – minimum value the integer can take
  • max – maximum value the integer can take
  • **kwargs – arbitrary keyword arguments passed to Opt

Changed in version 1.15: Added min and max parameters.

class oslo_config.cfg.FloatOpt(name, min=None, max=None, **kwargs)

Option with Float type

Option with type oslo_config.types.Float :param min: minimum value the float can take :param max: maximum value the float can take

Parameters:
  • name – the option’s name
  • **kwargs – arbitrary keyword arguments passed to Opt

Changed in version 3.14: Added min and max parameters.

class oslo_config.cfg.ListOpt(name, item_type=None, bounds=None, **kwargs)

Option with List(String) type

Option with type oslo_config.types.List

Parameters:
  • name – the option’s name
  • item_type – type of items (see oslo_config.types)
  • bounds – if True the value should be inside “[” and “]” pair
  • **kwargs – arbitrary keyword arguments passed to Opt

Changed in version 2.5: Added item_type and bounds parameters.

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

Option with Dict(String) type

Option with type oslo_config.types.Dict

Parameters:
  • name – the option’s name
  • **kwargs – arbitrary keyword arguments passed to Opt

New in version 1.2.

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 – the option’s name
  • item_type – Type of items (see oslo_config.types)
  • **kwargs – arbitrary keyword arguments passed to Opt

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]

New in version 1.3.

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

MultiOpt with a MultiString item_type.

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

Parameters:
  • name – the option’s name
  • **kwargs – arbitrary keyword arguments passed to MultiOpt
class oslo_config.cfg.IPOpt(name, version=None, **kwargs)

Opt with IPAddress type

Option with type oslo_config.types.IPAddress

Parameters:
  • name – the option’s name
  • version – one of either 4, 6, or None to specify either version.
  • **kwargs – arbitrary keyword arguments passed to Opt

New in version 1.4.

class oslo_config.cfg.PortOpt(name, min=None, max=None, choices=None, **kwargs)

Option for a TCP/IP port number. Ports can range from 0 to 65535.

Option with type oslo_config.types.Integer

Parameters:
  • name – the option’s name
  • choices – Optional sequence of valid values.
  • **kwargs – arbitrary keyword arguments passed to Opt
  • min – minimum value the port can take
  • max – maximum value the port can take

New in version 2.6.

Changed in version 3.2: Added choices parameter.

Changed in version 3.4: Allow port number with 0.

Changed in version 3.16: Added min and max parameters.

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

Option for a hostname. Only accepts valid hostnames.

Option with type oslo_config.types.Hostname

New in version 3.8.

class oslo_config.cfg.URIOpt(name, max_length=None, schemes=None, **kwargs)

Opt with URI type

Option with type oslo_config.types.URI

Parameters:
  • max_length – If positive integer, the value must be less than or equal to this parameter.
  • schemes – list of valid URI schemes, e.g. ‘https’, ‘ftp’, ‘git’

New in version 3.12.

Changed in version 3.14: Added max_length parameter

Changed in version 3.18: Added schemes parameter

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’].

New in version 1.2.

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.

Parameters:
  • name – the option’s name
  • dest – the name of the corresponding ConfigOpts property
  • handler – callable which is supplied subparsers object when invoked
  • title – title of the sub-commands group in help output
  • description – description of the group in help output
  • help – a help string giving an overview of available sub-commands
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

Parameters:
  • name – the group name
  • title – the group title for –help
  • help – the group description for –help