oslo_config 包

子包

子模块

oslo_config.cfg 模块

oslo_config 中的主模块。

exception oslo_config.cfg.ArgsAlreadyParsedError(msg=None)

基类: Error

如果在解析后注册 CLI 选项时引发。

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

基类: Opt

布尔选项。

使用 –optname 或 –nooptname 在命令行上将布尔选项设置为 True 或 False。

在配置文件中，布尔值将转换为 Boolean 类型。

参数：

  • name – 选项的名称

  • **kwargs – 传递给 Opt 的任意关键字参数

exception oslo_config.cfg.ConfigDirNotFoundError(config_dir)

基类: Error

如果找不到请求的 config-dir 时引发。

exception oslo_config.cfg.ConfigFileParseError(config_file, msg)

基类: Error

如果解析配置文件时发生错误，则引发。

exception oslo_config.cfg.ConfigFileValueError(msg=None)

基类: ConfigSourceValueError

如果配置文件值与其选项类型不匹配时引发。

exception oslo_config.cfg.ConfigFilesNotFoundError(config_files)

基类: Error

如果找不到一个或多个配置文件时引发。

exception oslo_config.cfg.ConfigFilesPermissionDeniedError(config_files)

基类: Error

如果一个或多个配置文件不可读时引发。

class oslo_config.cfg.ConfigOpts

基类: Mapping

可在命令行或配置文件中设置的配置选项。

ConfigOpts 是一个配置选项管理器，提供用于注册选项模式、分组选项、解析选项值和检索选项值的 API。

它内置支持 config_file 和 config_dir 选项。

版本 9.5.0 中更改: 添加了 shell-completion 选项以生成 shell 完成脚本。

class GroupAttr(conf, group)

基类: Mapping

辅助类。

将组的选项值表示为映射和属性。

class StrSubWrapper(conf, group=None, namespace=None)

基类: object

辅助类。

将选项值作为字典公开用于字符串替换。

class SubCommandAttr(conf, group, dest)

基类: object

辅助类。

表示 argparse 子解析器的名称和参数。

class Template(template)

基类: Template

idpattern = '[_a-z][\\._a-z0-9]*'
pattern = re.compile('\n            \\$(?:\n              (?P<escaped>\\$)  |   # Escape sequence of two delimiters\n              (?P<named>[_a-z][\\._a-z0-9]*)       |   # delimiter and a Python identifier\n            , re.IGNORECASE|re.VERBOSE)
clear()

重置对象的状态为在注册选项之前。

此方法删除所有已注册的选项并丢弃来自命令行和配置文件的所有数据。

使用 add_cli_subparsers() 添加的任何子解析器也会作为此方法的副作用被删除。

clear_default(name, group=None)

清除并覆盖选项的默认值。

清除先前设置的给定选项的默认值覆盖。

参数：

  • name – 选项的名称/目标

  • group – 一个 OptGroup 对象或组名

引发:

NoSuchOptError, NoSuchGroupError

clear_override(name, group=None)

清除并覆盖选项值。

清除先前设置的给定选项的命令行、配置文件和默认值的覆盖。

参数：

  • name – 选项的名称/目标

  • group – 一个 OptGroup 对象或组名

引发:

NoSuchOptError, NoSuchGroupError

property config_dirs
disallow_names = ('project', 'prog', 'version', 'usage', 'default_config_files', 'default_config_dirs')
find_file(name)

找到与配置文件位于同一位置的文件。

在已经加载配置文件的目录以及其他已知配置目录中搜索具有给定基本名称的文件。

首先搜索 config_dir 选项提供的目录。然后遍历 config_file 选项，并搜索 config_files 值的每个基本目录。如果都失败，则使用模块级别 find_config_files() 函数搜索的标准目录。返回第一个匹配的文件。

参数：

name – 文件名，例如 ‘policy.json’

返回值:

匹配文件的路径，或 None

get_location(name, group=None)

返回选项设置的位置。

参数：

  • name (str) – 选项的名称。

  • group (str) – 选项的组名。默认为 'DEFAULT'。

返回值:

LocationInfo

参见

选项设置位置

在版本 5.3.0 中添加。

import_group(group, module_str)

从模块导入选项组。

导入模块并检查是否已注册给定的选项组。

这适用于像 cfg.CONF 这样的全局配置对象，这些对象通常在模块加载时使用 CONF 注册选项。如果一个模块需要由另一个模块定义的选项组，可以使用此方法显式声明依赖关系。

参数：

  • group – 一个 OptGroup 对象或组名

  • module_str – 要导入的模块的名称

引发:

ImportError, NoSuchGroupError

import_opt(name, module_str, group=None)

从模块导入选项定义。

导入模块并检查是否已注册给定的选项。

这适用于像 cfg.CONF 这样的全局配置对象，这些对象通常在模块加载时使用 CONF 注册选项。如果一个模块需要由另一个模块定义的选项，可以使用此方法显式声明依赖关系。

参数：

  • name – 选项的名称/目标

  • module_str – 要导入的模块的名称

  • group – 一个 OptGroup 对象或组名

引发:

NoSuchOptError, NoSuchGroupError

list_all_sections()

列出配置中的所有部分。

返回在配置文件中找到的所有部分名称的排序列表，无论是否事先声明。

log_opt_values(logger, lvl)

记录所有已注册选项的值。

对于应用程序将其配置记录到启动时的日志文件以进行调试通常很有用。此方法将整个配置状态转储到提供的日志记录器处的给定日志级别。

参数：

  • logger – 一个 logging.Logger 对象

  • lvl – 日志级别（例如 logging.DEBUG）arg 到 logger.log()

mutate_config_files()

重新加载配置文件并解析所有选项。

只有标记为 ‘mutable’ 的选项才会显示更改。

钩子以非确定性顺序调用。不要期望钩子以它们被添加的相同顺序被调用。

返回值:

{(None 或 ‘group’, ‘optname’): (old_value, new_value), … }

引发:

如果重新加载失败则引发错误

print_help(file=None)

打印当前程序的帮助信息。

此方法用于在所有 CLI 选项使用 __call__() 方法注册后使用。如果在此方法被调用之前调用了 __call__()，则会抛出 NotInitializedError

参数：

file – 文件对象（如果为 None，则输出到 sys.stdout）

引发:

NotInitializedError

print_usage(file=None)

打印当前程序的用法信息。

此方法用于在所有 CLI 选项使用 __call__() 方法注册后使用。如果在此方法被调用之前调用了 __call__()，则会抛出 NotInitializedError

参数：

file – 文件对象（如果为 None，则输出到 sys.stdout）

引发:

NotInitializedError

register_cli_opt(opt, group=None)

注册 CLI 选项模式。

CLI 选项模式必须在命令行和配置文件被解析之前注册。这是为了确保所有 CLI 选项都显示在 –help 中，并且选项验证能够按预期工作。

参数：

  • opt – Opt 子类的实例

  • group – 可选的 OptGroup 对象或组名

返回值:

如果该选项已经注册，则为 False；否则为 True

引发:

DuplicateOptError, ArgsAlreadyParsedError

register_cli_opts(opts, group=None)

一次注册多个 CLI 选项模式。

register_group(group)

注册一个选项组。

必须先注册一个选项组，然后才能向该组注册选项。

参数：

group – OptGroup 对象

register_mutate_hook(hook)

注册一个钩子，该钩子将被 mutate_config_files 调用。

参数：

hook – 一个接受此 ConfigOpts 对象和 mutate_config_files 返回的配置修改字典的函数。

返回值:

无

register_opt(opt, group=None, cli=False)

注册一个选项模式。

注册一个选项模式，使任何先前或随后从命令行或配置文件中解析的选项值都作为此对象的属性可用。

参数：

  • opt – Opt 子类的实例

  • group – 可选的 OptGroup 对象或组名

  • cli – 是否为 CLI 选项

返回值:

如果该选项已经注册，则为 False；否则为 True

引发:

DuplicateOptError

register_opts(opts, group=None)

一次注册多个选项模式。

reload_config_files()

重新加载配置文件并解析所有选项

返回值:

如果重新加载配置文件失败，则返回 False；否则返回 True

reset()

清除对象状态并取消设置覆盖和默认值。

set_default(name, default, group=None)

覆盖选项的默认值。

覆盖给定选项的默认值。命令行或配置文件值仍将优先于此默认值。

参数：

  • name – 选项的名称/目标

  • default – 默认值

  • group – 一个 OptGroup 对象或组名

引发:

NoSuchOptError, NoSuchGroupError

set_override(name, override, group=None)

覆盖选项值。

覆盖给定选项的命令行、配置文件和默认值。

参数：

  • name – 选项的名称/目标

  • override – 覆盖值

  • group – 一个 OptGroup 对象或组名

引发:

NoSuchOptError, NoSuchGroupError

supported_shell_completion = ['bash', 'zsh']
unregister_opt(opt, group=None)

取消注册一个选项。

参数：

  • opt – Opt 对象

  • group – 可选的 OptGroup 对象或组名

引发:

ArgsAlreadyParsedError, NoSuchGroupError

unregister_opts(opts, group=None)

一次取消注册多个 CLI 选项模式。

class oslo_config.cfg.ConfigParser(filename, sections)

基类: BaseParser

解析单个配置文件，填充 ‘sections’ 以呈现

{'DEFAULT': {'key': [value, ...], ...},
 ...}

同时填充 self._normalized，其外观相同，但具有规范化的节名称。

assignment(key, value)

在解析了完整的赋值时调用。

error_no_section()
new_section(section)

在开始新节时调用。

parse()
parse_exc(msg, lineno, line=None)

所有非退出异常的公共基类。

exception oslo_config.cfg.ConfigSourceValueError(msg=None)

基类: Error, ValueError

如果配置源值与选项类型不匹配，则引发。

exception oslo_config.cfg.DefaultValueError(msg=None)

基类: Error, ValueError

如果默认配置类型与选项类型不匹配，则引发。

class oslo_config.cfg.DeprecatedOpt(name, group=None)

基类: object

表示已弃用的选项。

以下是如何使用它

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')

对于具有单个值的选项（如上例所示），如果存在新的选项（“ [group1] / newopt” 上面），它将覆盖任何存在的已弃用选项（“ [group1] / oldopt1” 和 “ [group2] / oldopt2” 上面）。

如果未为 DeprecatedOpt 选项指定组（即组为 None），则将在新选项所在的组中查找。例如，如果未为 deprecated_opts 列表中的第二个选项 ‘oldopt2’ 指定组

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')

那么将在组 ‘group1’ 中查找该选项。

如果不存在新的选项并且存在多个已弃用的选项，则将选择 deprecated_opts 的第一个元素的对应选项。

多值选项将返回所有新的和已弃用的选项。因此，如果有一个多值选项 “[group1] / opt1”，其已弃用的选项是 “[group2] / opt2”，并且配置文件中同时指定了这两个选项，如下所示

[group1]
opt1=val10,val11

[group2]
opt2=val21,val22

那么 “[group1] / opt1” 的值将是 [‘val10’，‘val11’，‘val21’，‘val22’]。

在版本 1.2 中添加。

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

基类: Opt

具有 Dict(String) 类型的选项

具有 type oslo_config.types.Dict 的选项

参数：

  • name – 选项的名称

  • **kwargs – 传递给 Opt 的任意关键字参数

在版本 1.2 中添加。

exception oslo_config.cfg.DuplicateOptError(opt_name)

基类: Error

如果注册了具有相同名称的多个选项，则引发。

exception oslo_config.cfg.Error(msg=None)

基础: Exception

cfg 异常的基类。

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

基类: Opt

具有 Float 类型的选项

具有 type oslo_config.types.Float 的选项

参数：

  • name – 选项的名称

  • min – 浮点数可以取的最小值

  • max – 浮点数可以取的最大值

  • **kwargs – 传递给 Opt 的任意关键字参数

在版本 3.14 中更改： 添加了 min 和 max 参数。

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

基类: Opt

IP 或主机名选项。

接受有效的主机名和有效的 IP 地址。

选项，其 type 为 oslo_config.types.HostAddress

参数：

  • name – 选项的名称

  • version – 要指定版本，可以是 4、6 或 None 中的一个。

  • **kwargs – 传递给 Opt 的任意关键字参数

在 3.22 版本中添加。

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

基类: Opt

IP 或主机名选项。

类似于 HostAddress，但支持下划线字符。

选项，其 type 为 oslo_config.types.HostDomain

参数：

  • name – 选项的名称

  • version – 要指定版本，可以是 4、6 或 None 中的一个。

  • **kwargs – 传递给 Opt 的任意关键字参数

在 8.6 版本中添加。

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

基类: Opt

主机名选项。仅接受有效的主机名。

选项，其 type 为 oslo_config.types.Hostname

参数：

  • name – 选项的名称

  • **kwargs – 传递给 Opt 的任意关键字参数

在版本 3.8 中添加。

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

基类: Opt

具有 IPAddress 类型的选项

选项，其 type 为 oslo_config.types.IPAddress

参数：

  • name – 选项的名称

  • version – 要指定版本，可以是 4、6 或 None 中的一个。

  • **kwargs – 传递给 Opt 的任意关键字参数

1.4 版本中添加。

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

基类: Opt

具有整数类型的选项

选项，其 type 为 oslo_config.types.Integer

参数：

  • name – 选项的名称

  • min – 整数可以取到的最小值

  • max – 整数可以取到的最大值

  • choices – 可选的有效值序列或带有描述的有效值元组。

  • **kwargs – 传递给 Opt 的任意关键字参数

在 1.15 版本中更改： 添加了 min 和 max 参数。

在 9.3.0 版本中更改： 添加了 choices 参数。

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

基类: Opt

具有 List(String) 类型的选项

选项，其 type 为 oslo_config.types.List

参数：

  • name – 选项的名称

  • item_type – 项目类型（请参阅 oslo_config.types）

  • bounds – 如果为 True，则该值应位于“[”和“]”对内

  • **kwargs – 传递给 Opt 的任意关键字参数

在 2.5 版本中更改： 添加了 item_type 和 bounds 参数。

class oslo_config.cfg.LocationInfo(location, detail)

基类: tuple

detail

字段编号 1 的别名

location

字段编号 0 的别名

class oslo_config.cfg.Locations(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

基础: Enum

command_line = (5, True)
environment = (6, True)
opt_default = (1, False)
set_default = (2, False)
set_override = (3, False)
user = (4, True)
class oslo_config.cfg.MultiOpt(name, item_type, **kwargs)

基类: Opt

多值选项。

多值选项是可多次指定的类型化选项。选项的值包含所有指定的值的列表。

参数：

  • name – 选项的名称

  • item_type – 项目类型（请参阅 oslo_config.types）

  • **kwargs – 传递给 Opt 的任意关键字参数

例如

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

命令行 --foo=1 --foo=2 将导致 cfg.CONF.foo 包含 [1,2]

1.3 版本中添加。

multi = True
class oslo_config.cfg.MultiStrOpt(name, **kwargs)

基类：MultiOpt

具有 MultiString item_type 的 MultiOpt。

具有默认 oslo_config.types.MultiString 项目类型的 MultiOpt。

参数：

  • name – 选项的名称

  • **kwargs – 传递给 MultiOpt 的任意关键字参数

exception oslo_config.cfg.NoSuchGroupError(group_name)

基类: Error

引用不存在的组时引发。

exception oslo_config.cfg.NoSuchOptError(opt_name, group=None)

基类：Error, AttributeError

引用不存在的选项时引发。

exception oslo_config.cfg.NotInitializedError(msg=None)

基类: Error

在尚未初始化解析器时引发。

class oslo_config.cfg.Opt(name, type=None, dest=None, short=None, default=None, positional=False, metavar=None, help=None, secret=False, required=None, 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)

基类: object

所有配置选项的基类。

唯一的必需参数是选项的名称。但是，为所有选项提供默认值和帮助字符串是很常见的。

参数：

  • name – 选项的名称

  • type – 选项的类型。必须是一个可调用对象，该对象接受字符串并返回转换和验证后的值

  • dest – 相应的 ConfigOpts 属性的名称

  • short – 单个字符的 CLI 选项名称

  • default – 选项的默认值

  • positional – 如果选项是位置 CLI 参数，则为 True

  • metavar – 在 –help 中显示的选项参数

  • help – 解释如何使用该选项

  • secret – 如果该值应在日志输出中混淆，则为 true

  • required – 如果必须为该选项提供值，则为 true

  • deprecated_name – 已弃用的选项名称。充当别名

  • deprecated_group – 包含已弃用别名的组

  • deprecated_opts – DeprecatedOpt 列表

  • sample_default – 示例配置文件中的默认字符串

  • deprecated_for_removal – 指示该选项是否计划在未来的版本中移除

  • deprecated_reason – 指示该选项计划在未来版本中移除的原因。如果 deprecated_for_removal 为 False，则会被静默忽略

  • deprecated_since – 指示该选项在哪个版本中被弃用。接受任何字符串，但鼓励使用有效的版本字符串。如果 deprecated_for_removal 为 False，则会被静默忽略

  • mutable – 如果该选项可以重新加载，则为 True

  • advanced – 一个布尔值 True/False，如果该选项具有高级用法且通常不被大多数用户使用

Opt 对象没有公共方法，但具有许多公共属性

name

该选项的名称，可以包含连字符

type

一个可调用对象，它接收字符串并返回转换和验证后的值。默认类型可从 oslo_config.types 获取

dest

（不带连字符的）ConfigOpts 属性，其中包含选项值

short

一个单字符 CLI 选项名称

default

该选项的默认值

sample_default

一个示例默认值字符串，用于包含在示例配置文件中

positional

如果该选项是位置 CLI 参数，则为 True

metavar

在 –help 输出中作为 CLI 选项参数显示的名称

help

一个字符串，解释了选项的值是如何使用的

advanced

在示例文件中，一个布尔值，指示该选项是高级选项

版本 1.2 中更改： 添加了 deprecated_opts 参数。

版本 1.4 中更改： 添加了 sample_default 参数。

版本 1.9 中更改： 添加了 deprecated_for_removal 参数。

版本 2.7 中更改： 如果默认值类型错误，现在会引发异常。

版本 3.2 中更改： 添加了 deprecated_reason 参数。

版本 3.5 中更改： 添加了 mutable 参数。

版本 3.12 中更改： 添加了 deprecated_since 参数。

版本 3.15 中更改： 添加了 advanced 参数和属性。

multi = False
class oslo_config.cfg.OptGroup(name, title=None, help=None, dynamic_group_owner='', driver_option='')

基类: object

表示一组选项。

组中的 CLI 选项会自动以组名称为前缀。

每个组对应于配置文件中的一个部分。

OptGroup 对象没有公共方法，但具有许多公共字符串属性

name

该组的名称

title

在 –help 中显示的组标题

help

在 –help 中显示的组描述

参数：

  • name (str) – 组名称

  • title (str) – –help 的组标题

  • help (str) – –help 的组描述

  • dynamic_group_owner (str) – 控制此组重复实例的选项的名称。

  • driver_option (str) – 控制将注册选项的驱动程序的组内的选项名称。

exception oslo_config.cfg.ParseError(msg, lineno, line, filename)

基于 ParseError

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

基类: Opt

TCP/IP 端口号的选项。端口范围为 0 到 65535。

选项，其 type 为 oslo_config.types.Integer

参数：

  • name – 选项的名称

  • min – 端口可以取的最小值

  • max – 端口可以取得的最大值

  • choices – 可选的有效值序列或带有描述的有效值元组。

  • **kwargs – 传递给 Opt 的任意关键字参数

版本 2.6 中添加。

版本 3.2 中更改： 添加了 choices 参数。

版本 3.4 中更改： 允许端口号为 0。

版本 3.16 中更改： 添加了 min 和 max 参数。

版本 5.2 中更改： choices 参数现在将接受一个元组序列，其中每个元组的格式为 (choice, description)

exception oslo_config.cfg.RequiredOptError(opt_name, group=None)

基类: Error

如果需要一个选项但用户没有提供值，则引发。

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

基类: Opt

字符串类型的选项

具有 type oslo_config.types.String 的选项

参数：

  • name – 选项的名称

  • choices – 可选的有效值序列或带有描述的有效值元组。

  • quotes – 如果为 True 并且字符串用单引号或双引号括起来，则会删除这些引号。

  • regex – 可选的正则表达式（字符串或编译后的正则表达式），该值必须与之匹配（不锚定搜索）。

  • ignore_case – 如果为 True，则 ‘choices’ 或 ‘regex’ 之间的区分大小写（大写与小写）将被忽略。

  • max_length – 如果为正整数，则该值必须小于或等于此参数。

  • **kwargs – 传递给 Opt 的任意关键字参数

版本 2.7 中更改： 添加了 quotes 参数

版本 2.7 中更改： 添加了 regex 参数

版本 2.7 中更改： 添加了 ignore_case 参数

版本 2.7 中更改： 添加了 max_length 参数

版本 5.2 中更改： choices 参数现在将接受一个元组序列，其中每个元组的格式为 (choice, description)

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

基类: Opt

子命令选项。

子命令选项允许使用 argparse 子解析器来解析额外的命令行参数。

SubCommandOpt 构造函数的 handler 参数是一个可调用对象，该对象将提供一个 argparse 子解析器对象。使用此 handler 可调用对象来添加子解析器。

该选项值是 SubCommandAttr 对象，其中所选子解析器的名称存储在 ‘name’ 属性中，其他子解析器参数的值作为附加属性可用。

参数：

  • name – 选项的名称

  • dest – 相应的 ConfigOpts 属性的名称

  • handler – 调用时提供子解析器对象的调用对象

  • title – 帮助输出中子命令组的标题

  • description – 帮助输出中组的描述

  • help – 提供可用子命令概述的帮助字符串

exception oslo_config.cfg.TemplateSubstitutionError(msg=None)

基类: Error

如果在选项值中替换变量时发生错误，则引发。

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

基类: Opt

URI 类型的选项

具有 type oslo_config.types.URI 的选项

参数：

  • name – 选项的名称

  • max_length – 如果为正整数，则该值必须小于或等于此参数。

  • schemes – 有效的 URI 方案列表，例如 ‘https’、‘ftp’、‘git’

  • **kwargs – 传递给 Opt 的任意关键字参数

版本 3.12 中添加。

版本 3.14 中更改： 添加了 max_length 参数

版本 3.18 中更改： 添加了 schemes 参数

oslo_config.cfg.find_config_dirs(project=None, prog=None, extension='.conf.d')

返回默认配置目录列表。

参数：

  • project – 可选的项目名称

  • prog – 程序名称，默认为 sys.argv[0] 的基本名称，不带 .py 扩展名

  • extension – 配置目录的类型。默认为 ‘.conf.d’

我们默认使用两个配置目录：[${project}.conf.d/, ${prog}.conf.d/] 。如果未提供项目名称，我们仅查找 ${prog.conf.d/} 。

并且我们在以下目录中查找这些配置目录

~/.${project}/
~/
/etc/${project}/
/etc/
${SNAP_COMMON}/etc/${project}
${SNAP}/etc/${project}

我们返回每个两个配置目录的绝对路径，在找到它们的地方（如果找到它们）。

例如，如果 project=foo，prog=bar 并且 /etc/foo/foo.conf.d/、/etc/bar.conf.d/ 和 ~/.foo/bar.conf.d/ 都存在，那么我们返回 [‘/etc/foo/foo.conf.d/’、‘~/.foo/bar.conf.d/’]

oslo_config.cfg.find_config_files(project=None, prog=None, extension='.conf')

返回默认配置文件列表。

参数：

  • project – 可选的项目名称

  • prog – 程序名称，默认为 sys.argv[0] 的基本名称，不带 .py 扩展名

  • extension – 配置文件的类型

我们默认使用两个配置文件：[${project}.conf, ${prog}.conf]

并且我们在以下目录中查找这些配置文件

~/.${project}/
~/
/etc/${project}/
/etc/
${SNAP_COMMON}/etc/${project}
${SNAP}/etc/${project}

我们返回 (最多) 每个默认配置文件的绝对路径，对于找到它的最顶层目录。

例如，如果 project=foo，prog=bar 并且 /etc/foo/foo.conf、/etc/bar.conf 和 ~/.foo/bar.conf 都存在，那么我们返回 [‘/etc/foo/foo.conf’、‘~/.foo/bar.conf’]

如果未提供项目名称，我们仅查找 ${prog}.conf。

oslo_config.cfg.set_defaults(opts, **kwargs)

oslo_config.fixture 模块

class oslo_config.fixture.Config(conf=<oslo_config.cfg.ConfigOpts object>)

基础: Fixture

允许覆盖测试的配置设置。

conf 在清理时将被重置。

config(**kw)

覆盖配置值。

关键字参数是需要覆盖的配置选项的名称及其值。

如果提供了 group 参数，则将覆盖应用于指定的配置选项组，否则覆盖将应用于 default 组。

load_raw_values(group=None, **kwargs)

将原始值加载到配置中，而不注册它们。

此方法将一系列参数添加到当前配置实例中，就像它们由 ConfigParser 加载一样。此方法不需要先注册配置选项，但是加载的值在注册之前将不可访问。

register_cli_opt(opt, group=None)

为测试运行注册单个 CLI 选项。

以这种方式注册的选项将在清理期间自动注销。

如果提供了 group 参数，它将把新选项注册到该组，否则该选项将注册到 default 组。

必须在解析命令行和配置文件之前注册 CLI 选项。这是为了确保所有 CLI 选项都显示在 –help 中，并且选项验证能够按预期工作。

register_cli_opts(opts, group=None)

为测试运行注册多个 CLI 选项。

此方法与 register_opt() 的工作方式相同，但将选项列表作为第一个参数。如果提供了 group 参数，则所有参数都将注册到同一组，否则所有选项都将注册到 default 组。

必须在解析命令行和配置文件之前注册 CLI 选项。这是为了确保所有 CLI 选项都显示在 –help 中，并且选项验证能够按预期工作。

register_opt(opt, group=None)

为测试运行注册单个选项。

以这种方式注册的选项将在清理期间自动注销。

如果提供了 group 参数，它将把新选项注册到该组，否则该选项将注册到 default 组。

register_opts(opts, group=None)

为测试运行注册多个选项。

此方法与 register_opt() 的工作方式相同，但将选项列表作为第一个参数。如果提供了 group 参数，则所有参数都将注册到同一组，否则所有选项都将注册到 default 组。

setUp()

准备 Fixture 以供使用。

不应覆盖此方法。具体的 fixture 应该实现 _setUp。仍然支持覆盖 setUp，但不推荐。

在 setUp 完成后，fixture 将具有一个或多个属性，这些属性可用于（具体取决于具体的子类）。

引发:

如果 _setUp 失败，则引发 MultipleExceptions。MultipleExceptions 中捕获的最后一个异常将是一个 SetupError 异常。

返回值:

None。

更改于 1.3:

覆盖 setUp 的建议已反转 - 在 1.3 之前，应该覆盖 setUp()，现在不应该覆盖。

更改于 1.3.1:

现在捕获 BaseException，并且只有 Exception 的子类才会被包装在 MultipleExceptions 中。

set_config_dirs(config_dirs)

指定要读取的配置目录列表。

此方法允许您预定义 oslo_config 加载的配置目录列表。它将确保您的测试不会尝试自动检测，并意外地从本地安装的服务中获取配置文件。

set_config_files(config_files)

指定要读取的配置文件列表。

此方法允许您预定义 oslo_config 加载的配置文件列表。它将确保您的测试不会尝试自动检测，并意外地从本地安装的服务中获取配置文件。

set_default(name, default, group=None)

设置选项的默认值。

此方法不一定意味着要直接调用。它存在于此，以允许 Oslo 库中的 set_defaults() 函数使用 Config fixture 而不是 ConfigOpts 实例。

使用方法如下：

class MyTest(testtools.TestCase):

    def setUp(self):
        super(MyTest, self).setUp()
        self.conf = self.useFixture(fixture.Config())

    def test_something(self):
        some_library.set_defaults(self.conf, name='value')
        some_library.do_something_exciting()

oslo_config.generator 模块

示例配置生成器

用于生成示例配置文件的工具。有关详细信息，请参阅 ../doc/source/cli/generator.rst。

1.4 版本中添加。

oslo_config.generator.generate(conf, output_file=None)

生成示例配置文件。

列出通过给定配置中指定的命名空间可用的所有选项，并将它们的描述写入指定的输出文件。

参数：

conf – 包含生成器的配置的 ConfigOpts 实例

oslo_config.generator.i18n_representer(dumper, data)

oslo_i18n yaml 表示器

返回翻译成默认语言环境的字符串，用于 yaml.safe_dump

参数：

  • dumper – yaml.safe_dump 传递的 SafeDumper 实例

  • data – oslo_i18n._message.Message 实例

oslo_config.generator.main(args=None)

oslo-config-generator 的主函数。

oslo_config.generator.on_load_failure_callback(*args, **kwargs)
oslo_config.generator.register_cli_opts(conf)

将格式化程序的 CLI 选项与 ConfigOpts 实例注册。

注意，必须在调用 ConfigOpts 实例来解析配置之前执行此操作。

参数：

conf – ConfigOpts 实例

引发:

DuplicateOptError, ArgsAlreadyParsedError

oslo_config.iniparser 模块

class oslo_config.iniparser.BaseParser

基类: object

assignment(key, value)

在解析了完整的赋值时调用。

comment(comment)

在解析到注释时调用。

error_empty_key(line)
error_invalid_assignment(line)
error_no_section_end_bracket(line)
error_no_section_name(line)
error_unexpected_continuation(line)
lineno = 0
new_section(section)

在开始新节时调用。

parse(lineiter)
parse_exc

别名 ParseError

exception oslo_config.iniparser.ParseError(message, lineno, line)

基础: Exception

oslo_config.sphinxconfiggen 模块

oslo_config.sphinxconfiggen.generate_sample(app)
oslo_config.sphinxconfiggen.setup(app)

oslo_config.sphinxext 模块

class oslo_config.sphinxext.ConfigDomain(env: BuildEnvironment)

继承自 Domain

oslo.config 域。

directives: dict[str, type[Directive]] = {'group': <class 'oslo_config.sphinxext.ConfigGroup'>, 'option': <class 'oslo_config.sphinxext.ConfigOption'>}

指令名称 -> 指令类

initial_data: dict = {'groups': {}, 'options': {}}

用于全新环境的数据值

label = 'oslo.config'

领域标签：更长、更具描述性（用于消息中）

merge_domaindata(docnames, otherdata)

合并来自不同 domaindata 存储（来自并行构建中的子进程）的关于 docnames 的数据。

name = 'oslo.config'

领域名称：应简短但唯一

object_types: dict[str, ObjType] = {'configoption': <sphinx.domains.ObjType object>}

类型（通常是指令）名称 -> ObjType 实例

resolve_xref(env, fromdocname, builder, typ, target, node, contnode)

解析交叉引用

roles: dict[str, RoleFunction | XRefRole] = {'group': <oslo_config.sphinxext.ConfigGroupXRefRole object>, 'option': <oslo_config.sphinxext.ConfigOptXRefRole object>}

角色名称 -> 角色可调用对象

class oslo_config.sphinxext.ConfigGroup(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

基类: Directive

has_content = True

指令是否可以包含内容？

option_spec = {'namespace': <function unchanged>}

选项名称到验证器函数的映射。

optional_arguments = 0

必需参数后的可选参数数量。

required_arguments = 1

必需指令参数的数量。

run()
class oslo_config.sphinxext.ConfigGroupXRefRole

基类: XRefRole

处理指向配置组的 :oslo.config:group: 角色。

在解析标题和目标文本以及创建引用节点（在 refnode 中给出）后调用。此方法可以更改引用节点，并且必须返回新的（或相同的）(title, target) 元组。

class oslo_config.sphinxext.ConfigOptXRefRole

基类: XRefRole

处理指向配置选项的 :oslo.config:option: 角色。

在解析标题和目标文本以及创建引用节点（在 refnode 中给出）后调用。此方法可以更改引用节点，并且必须返回新的（或相同的）(title, target) 元组。

class oslo_config.sphinxext.ConfigOption(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

基类: ObjectDescription

配置选项的描述（.. option）。

add_target_and_index(firstname, sig, signode)

添加交叉引用 ID 并将条目添加到 self.indexnode（如果适用）。

name 是 handle_signature() 返回的任何内容。

handle_signature(sig, signode)

将选项描述转换为 RST 节点。

class oslo_config.sphinxext.ShowOptionsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

基类: Directive

has_content = True

指令是否可以包含内容？

option_spec = {'config-file': <function unchanged>, 'split-namespaces': <function flag>}

选项名称到验证器函数的映射。

run()
oslo_config.sphinxext.setup(app)

oslo_config.types 模块

配置选项的类型转换和验证类。

将这些类用作 oslo_config.cfg.Opt 及其子类的 type 参数的值。

1.3 版本中添加。

class oslo_config.types.Boolean(type_name='布尔值')

基类: ConfigType

布尔类型。

值不区分大小写，可以使用 1/0、yes/no、true/false 或 on/off 设置。

参数：

type_name – 要在示例配置文件中使用的类型名称。

版本 2.7 中更改: 添加了 type_name 参数。

FALSE_VALUES = ['false', '0', 'off', 'no']
TRUE_VALUES = ['true', '1', 'on', 'yes']
class oslo_config.types.ConfigType(type_name='未知类型')

基类: object

NONE_DEFAULT = '<None>'
format_defaults(default, sample_default=None)

返回格式化的默认值列表。

quote_trailing_and_leading_space(str_val)
class oslo_config.types.Dict(value_type=None, bounds=False, type_name='字典值', key_value_separator=':')

基类: ConfigType

字典类型。

字典类型的值是键值对，用逗号分隔。结果值是这些键/值对的字典。字典键的类型始终是字符串，但字典值的类型可以自定义。

参数：

  • value_type – 字典中值的类型

  • bounds – 如果为 True，值应位于“{”和“}”对内

  • type_name – 要在示例配置文件中使用的类型名称。

版本 2.7 中更改: 添加了 type_name 参数。

版本 9.5 中更改： 添加了 key_value_separator 参数。

class oslo_config.types.Float(min=None, max=None, type_name='浮点数值')

基类: Number

浮点数类型。

参数：

  • min – 可选检查，确保值大于或等于 min。

  • max – 可选检查，确保值小于或等于 max。

  • type_name – 要在示例配置文件中使用的类型名称。

版本 2.7 中更改: 添加了 type_name 参数。

版本 3.14 中更改： 添加了 min 和 max 参数。如果同时提供了 choices，则它们必须在范围内。

class oslo_config.types.HostAddress(version=None, type_name='主机地址值')

基类: ConfigType

主机地址类型。

表示有效的 IPv4 或 IPv6 地址，以及有效的主机域名，包括完全限定域名。对 IPv4 地址和有效主机名进行严格检查，根据 RFC1912 将选项值与各自的类型进行匹配。

参数：

  • version – 定义在 IP 地址的情况下应显式检查的版本 (4 或 6)

  • type_name – 要在示例配置文件中使用的类型名称。

class oslo_config.types.HostDomain(version=None, type_name='主机域名值')

基类: HostAddress

主机域名类型。

类似于 HostAddress，但支持下划线字符。

参数：

  • version – 定义在 IP 地址的情况下应显式检查的版本 (4 或 6)

  • type_name – 要在示例配置文件中使用的类型名称。

DOMAIN_REGEX = '(?!-)[A-Z0-9-_]{1,63}(?<!-)$'
class oslo_config.types.Hostname(type_name='主机名值')

基类: ConfigType

主机域名类型。

主机名是指有效的 DNS 或主机名。它不得超过 253 个字符，段长度不得超过 63 个字符，也不能以连字符开头或结尾。

参数：

type_name – 要在示例配置文件中使用的类型名称。

HOSTNAME_REGEX = '(?!-)[A-Z0-9-]{1,63}(?<!-)$'
class oslo_config.types.IPAddress(version=None, type_name='IP 地址值')

基类: ConfigType

IP 地址类型

表示 IPv4 或 IPv6。如果未指定版本参数，则将检查这两个版本

参数：

  • version – 定义应显式检查的版本 (4 或 6)

  • type_name – 要在示例配置文件中使用的类型名称。

版本 2.7 中更改: 添加了 type_name 参数。

class oslo_config.types.Integer(min=None, max=None, type_name='整数值', choices=None)

基类: Number

整数类型。

将值转换为整数，并可选地进行范围检查。如果值为空白或空字符串，将返回 None。

参数：

  • min – 可选检查，确保值大于或等于 min。

  • max – 可选检查，确保值小于或等于 max。

  • type_name – 要在示例配置文件中使用的类型名称。

  • choices – 可选的有效值序列或带有描述的有效值元组。

版本 2.4 中更改： 该类现在尊重 0 作为 min 和 max 参数。

版本 2.7 中更改: 添加了 type_name 参数。

版本 3.2 中更改： 添加了 choices 参数。

版本 3.16 中更改： choices 不再与 min/max 互斥。如果提供了这些参数，则所有选项都将被验证是否在范围内。

版本 5.2 中更改： choices 参数现在将接受一个元组序列，其中每个元组的格式为 (choice, description)

class oslo_config.types.List(item_type=None, bounds=False, type_name='列表值')

基类: ConfigType

列表类型。

表示其他 (项目) 类型的列表值，用逗号分隔。结果值包含这些值的列表。

列表不知道项目类型是否也可以包含逗号。为了解决这个问题，它会尝试以下操作：如果下一部分验证失败，它会附加逗号和下一个项目，直到验证成功或没有剩余部分。在后一种情况下，它将发出验证错误。

参数：

  • item_type – 列表项目的类型。应该是 ConfigType 的实例。

  • bounds – 如果为 True，值应位于“[”和“]”对内

  • type_name – 要在示例配置文件中使用的类型名称。

版本 2.7 中更改: 添加了 type_name 参数。

class oslo_config.types.MultiString(type_name='多值')

基类: String

多值字符串。

NONE_DEFAULT = ['']
format_defaults(default, sample_default=None)

返回格式化的默认值列表。

class oslo_config.types.Number(num_type, type_name, min=None, max=None, choices=None)

基类: ConfigType

数字类，Integer 和 Float 的基类。

参数：

  • num_type – 用于转换的数字类型 (例如 int、float)

  • type_name – 要在示例配置文件中使用的类型名称。

  • min – 可选检查，确保值大于或等于 min。

  • max – 可选检查，确保值小于或等于 max。

  • choices – 可选的有效值序列或带有描述的有效值元组。

版本 3.14 中添加。

版本 5.2 中更改： choices 参数现在将接受一个元组序列，其中每个元组的格式为 (choice, description)

class oslo_config.types.Port(min=None, max=None, type_name='端口', choices=None)

基类: Integer

端口类型

表示 L4 端口。

参数：

  • min – 可选检查，确保值大于或等于 min。

  • max – 可选检查，确保值小于或等于 max。

  • type_name – 要在示例配置文件中使用的类型名称。

  • choices – 可选的有效值序列或带有描述的有效值元组。

版本 3.16 中添加。

版本 5.2 中更改： choices 参数现在将接受一个元组序列，其中每个元组的格式为 (choice, description)

PORT_MAX = 65535
PORT_MIN = 0
class oslo_config.types.Range(min=None, max=None, inclusive=True, type_name='范围值')

基类: ConfigType

范围类型。

表示一个整数范围。范围由一个整数标识，整数位于“-”字符的两侧。允许负数。单个数字也是一个有效的范围。

参数：

  • min – 可选检查，确保下限大于或等于 min。

  • max – 可选检查，确保上限小于或等于 max。

  • inclusive – 如果为 True，则右边界应包含在范围内。

  • type_name – 要在示例配置文件中使用的类型名称。

版本 3.18 中添加。

class oslo_config.types.String(choices=None, quotes=False, regex=None, ignore_case=False, max_length=None, type_name='字符串值')

基类: ConfigType

字符串类型。

字符串值不会被转换，并作为 str 对象返回。

参数：

  • choices – 可选的序列，可以是有效值或带有描述的有效值元组。与“regex”互斥。

  • quotes – 如果为 True 并且字符串用单引号或双引号括起来，则将删除这些引号。如果字符串在开头有引号但结尾没有引号，则会发出错误。默认情况下关闭。如果与容器类型（如 List）一起使用，则很有用。

  • regex – 可选的正则表达式（字符串或编译后的正则表达式），该值必须与之匹配（不锚定搜索）。与“choices”互斥。

  • ignore_case – 如果为 True，则“choices”或“regex”之间的区分大小写（大写与小写）将被忽略；默认为 False。

  • max_length – 可选整数。如果指定了正值，则选项值的最大长度必须小于或等于此参数。否则，将不会进行长度检查。

  • type_name – 要在示例配置文件中使用的类型名称。

版本 2.1 中更改： 添加了 regex 参数。

版本 2.5 中更改： 添加了 ignore_case 参数。

版本 2.7 中更改： 添加了 max_length 参数。添加了 type_name 参数。

版本 5.2 中更改： choices 参数现在将接受一个元组序列，其中每个元组的格式为 (choice, description)

class oslo_config.types.URI(max_length=None, schemes=None, type_name='uri 值')

基类: ConfigType

URI 类型

表示 URI。值将根据 RFC 3986 进行验证。

参数：

  • max_length – 可选整数。如果指定了正值，则选项值的最大长度必须小于或等于此参数。否则，将不会进行长度检查。

  • schemes – 有效方案的列表。

  • type_name – 要在示例配置文件中使用的类型名称。

3.14 版本更改：添加了 max_length 参数。

3.18 版本更改：添加了 schemes 参数。

oslo_config.validator 模块

配置验证器

使用示例配置文件生成器的配置文件来检索项目中所有可用选项的列表，然后将其与提供的文件中配置的内容进行比较。如果设置了项目中未定义的任何选项，则返回这些错误。

oslo_config.validator.load_opt_data(conf)
oslo_config.validator.main()

oslo-config-validator 的主函数。

oslo_config.version 模块

模块内容