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

Parameters:	name – the option’s name min – minimum value the float can take max – maximum value the float can take **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 min – minimum value the port can take max – maximum value the port can take choices – Optional sequence of valid values. **kwargs – arbitrary keyword arguments passed to Opt

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

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

New in version 3.8.

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

Option for either an IP or a hostname.

Accepts valid hostnames and valid IP addresses.

Option with type oslo_config.types.HostAddress

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

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

Opt with URI type

Option with type oslo_config.types.URI

Parameters:	name – the option’s name 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’ **kwargs – arbitrary keyword arguments passed to Opt

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, dynamic_group_owner='', driver_option='')¶

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 (str) – the group name title (str) – the group title for –help help (str) – the group description for –help dynamic_group_owner (str) – The name of the option that controls repeated instances of this group. driver_option (str) – The name of the option within the group that controls which driver will register options.