`configuration`#

一个通用的应用程序配置实用程序。

功能包括

惰性求值
合并配置文件
参数类型验证，带有自定义验证
参数别名

易于扩展到其他源格式，例如 json 和 ini

类#

`ParameterFlag`	通用枚举。
`RawParameter`
`EnvRawParameter`
`ArgParseRawParameter`
`YamlRawParameter`
`DefaultValueRawParameter`	将默认值包装为 RawParameter，以便在 ParameterLoader 中使用。
`LoadedParameter`	表示已加载配置值的参数。
`PrimitiveLoadedParameter`	LoadedParameter 类型，保存单个 python 原始值。
`MapLoadedParameter`	LoadedParameter 类型，保存 LoadedParameters 的映射（即 dict）。
`SequenceLoadedParameter`	LoadedParameter 类型，保存 LoadedParameters 的序列（即 list）。
`ObjectLoadedParameter`	LoadedParameter 类型，保存 LoadedParameters 的映射（即对象）。
`ConfigurationObject`	虚拟类，用于标记 Python 对象是否包含配置参数。
`Parameter`	Parameter 类表示未加载的配置参数，包含类型、默认值
`PrimitiveParameter`	Configuration 类的 Parameter 类型，保存单个 python 原始值。
`MapParameter`	Configuration 类的 Parameter 类型，保存 Parameters 的映射（即 dict）。
`SequenceParameter`	Configuration 类的 Parameter 类型，保存 Parameters 的序列（即 list）。
`ObjectParameter`	Configuration 类的 Parameter 类型，保存包含 Parameter 字段的对象。
`ParameterLoader`	ParameterLoader 类包含从开始到结束加载参数所需的顶层逻辑
`ConfigurationType`	Configuration 的元类
`配置`

函数#

`pretty_list`(iterable[, padding])
`pretty_map`(dictionary[, padding])
`expand_environment_variables`(unexpanded)
`raise_errors`(errors)
`custom_expandvars`(→ str)	展开字符串中的变量。
`unique_sequence_map`(*, unique_key)	用于验证在 `Configuration` 子类上定义的属性

属性#

`EMPTY_MAP`
`CONDARC_FILENAMES`
`YAML_EXTENSIONS`
`_RE_CUSTOM_EXPANDVARS`

EMPTY_MAP#

pretty_list(iterable, padding=' ')#

pretty_map(dictionary, padding=' ')#

expand_environment_variables(unexpanded)#

exception ConfigurationError(message, caused_by=None, **kwargs)#

基类： conda.CondaError

所有非退出异常的通用基类。

初始化 self。有关准确的签名，请参阅 help(type(self))。

exception ConfigurationLoadError(path, message_addition='', **kwargs)#

基类： ConfigurationError

所有非退出异常的通用基类。

初始化 self。有关准确的签名，请参阅 help(type(self))。

exception ValidationError(parameter_name, parameter_value, source, msg=None, **kwargs)#

基类： ConfigurationError

所有非退出异常的通用基类。

初始化 self。有关准确的签名，请参阅 help(type(self))。

exception MultipleKeysError(source, keys, preferred_key)#

基类： ValidationError

所有非退出异常的通用基类。

初始化 self。有关准确的签名，请参阅 help(type(self))。

exception InvalidTypeError(parameter_name, parameter_value, source, wrong_type, valid_types, msg=None)#

基类： ValidationError

所有非退出异常的通用基类。

初始化 self。有关准确的签名，请参阅 help(type(self))。

exception CustomValidationError(parameter_name, parameter_value, source, custom_message)#

基类： ValidationError

所有非退出异常的通用基类。

初始化 self。有关准确的签名，请参阅 help(type(self))。

exception MultiValidationError(errors, *args, **kwargs)#

基类： conda.CondaMultiError, ConfigurationError

所有非退出异常的通用基类。

初始化 self。有关准确的签名，请参阅 help(type(self))。

raise_errors(errors)#

class ParameterFlag#

基类： enum.Enum

通用枚举。

从此类派生以定义新的枚举。

final = 'final'#

top = 'top'#

bottom = 'bottom'#

__str__()#: 返回 str(self)。

classmethod from_name(name)#

classmethod from_value(value)#

classmethod from_string(string)#

class RawParameter(source, key, raw_value)#

__repr__()#: 返回 repr(self)。

abstract value(parameter_obj)#

abstract keyflag()#

abstract valueflags(parameter_obj)#

classmethod make_raw_parameters(source, from_map)#

class EnvRawParameter(source, key, raw_value)#

基类： RawParameter

property __important_split_value#

source = 'envvars'#

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

classmethod make_raw_parameters(appname)#

class ArgParseRawParameter(source, key, raw_value)#

基类： RawParameter

source = 'cmd_line'#

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

classmethod make_raw_parameters(args_from_argparse)#

class YamlRawParameter(source, key, raw_value, key_comment)#

基类： RawParameter

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

static _get_yaml_key_comment(commented_dict, key)#

classmethod _get_yaml_list_comments(value)#

static _get_yaml_list_comment_item(item)#

static _get_yaml_map_comments(value)#

classmethod make_raw_parameters(source, from_map)#

classmethod make_raw_parameters_from_file(filepath)#

class DefaultValueRawParameter(source, key, raw_value)#

基类： RawParameter

将默认值包装为 RawParameter，以便在 ParameterLoader 中使用。

value(parameter_obj)#

keyflag()#

valueflags(parameter_obj)#

class LoadedParameter(name, value, key_flag, value_flags, validation=None)#

表示已加载配置值的参数。

参数：

name (str) -- 已加载参数的名称
value (LoadedParameter 或 primitive) -- 已加载参数的值
key_flag (ParameterFlag 或 None) -- 参数自身的优先级标志
value_flags (Any 或 None) -- 参数值的优先级标志
validation (callable) -- 给定一个参数值作为输入，返回一个布尔值指示有效性，或者返回一个描述无效值的字符串。

_type#

_element_type#

__eq__(other)#: 返回 self==value。

__hash__()#: 返回 hash(self)。

collect_errors(instance, typed_value, source='<<merged>>')#

验证 LoadedParameter 类型化的值。

参数：

instance (Configuration) -- 用于创建 LoadedParameter 的实例对象。
typed_value (Any) -- 要验证的类型化的值。
source (str) -- 类型化值的来源的字符串描述。

expand()#

递归地展开 Loaded Parameter 中的任何环境变量值。

返回: LoadedParameter

abstract merge(matches)#

递归地将匹配项合并为一个 LoadedParameter。

参数：: matches (List<LoadedParameter>) -- 此参数的匹配项列表。

返回: LoadedParameter

typify(source)#

递归地类型化 LoadedParameter。

参数：: source (str) -- 描述 LoadedParameter 来源的字符串。

返回: 表示类型化值的原始类型、序列或映射。

static _typify_data_structure(value, source, type_hint=None)#

static _match_key_is_important(loaded_parameter)#

static _first_important_matches(matches)#

class PrimitiveLoadedParameter(name, element_type, value, key_flag, value_flags, validation=None)#

基类: LoadedParameter

LoadedParameter 类型，保存单个 python 原始值。

Python 原始类型包括 str、int、float、complex、bool 和 NoneType。此外，Python 2 还有 long 和 unicode 类型。

参数：

element_type (type 或 tuple[type]) -- 参数值的类型验证。
value (primitive value) -- 原始 Python 值。

__eq__(other)#: 返回 self==value。

__hash__()#: 返回 hash(self)。

merge(matches)#

递归地将匹配项合并为一个 LoadedParameter。

参数：: matches (List<LoadedParameter>) -- 此参数的匹配项列表。

返回: LoadedParameter

class MapLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None)#

基类: LoadedParameter

LoadedParameter 类型，保存 LoadedParameters 的映射（即 dict）。

参数：

value (Mapping) -- 字符串键到 LoadedParameter 值的映射。
element_type (Parameter) -- 值中包含的 Parameter 类型。
value_flags (Mapping) -- 优先级值标志的映射。

_type#

collect_errors(instance, typed_value, source='<<merged>>')#

验证 LoadedParameter 类型化的值。

参数：

instance (Configuration) -- 用于创建 LoadedParameter 的实例对象。
typed_value (Any) -- 要验证的类型化的值。
source (str) -- 类型化值的来源的字符串描述。

merge(parameters: collections.abc.Sequence[MapLoadedParameter]) → MapLoadedParameter#

递归地将匹配项合并为一个 LoadedParameter。

参数：: matches (List<LoadedParameter>) -- 此参数的匹配项列表。

返回: LoadedParameter

class SequenceLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None)#

基类: LoadedParameter

LoadedParameter 类型，保存 LoadedParameters 的序列（即 list）。

参数：

value (Sequence) -- LoadedParameter 值的序列。
element_type (Parameter) -- 序列中包含的 Parameter 类型。
value_flags (Sequence) -- 优先级值标志的序列。

_type#

collect_errors(instance, typed_value, source='<<merged>>')#

验证 LoadedParameter 类型化的值。

参数：

instance (Configuration) -- 用于创建 LoadedParameter 的实例对象。
typed_value (Any) -- 要验证的类型化的值。
source (str) -- 类型化值的来源的字符串描述。

merge(matches)#

递归地将匹配项合并为一个 LoadedParameter。

参数：: matches (List<LoadedParameter>) -- 此参数的匹配项列表。

返回: LoadedParameter

class ObjectLoadedParameter(name, value, element_type, key_flag, value_flags, validation=None)#

基类: LoadedParameter

LoadedParameter 类型，保存 LoadedParameters 的映射（即对象）。

参数：

value (Sequence) -- 具有 LoadedParameter 字段的对象。
element_type (object) -- 序列中包含的 Parameter 类型。
value_flags (Sequence) -- 优先级值标志的序列。

_type#

collect_errors(instance, typed_value, source='<<merged>>')#

验证 LoadedParameter 类型化的值。

参数：

instance (Configuration) -- 用于创建 LoadedParameter 的实例对象。
typed_value (Any) -- 要验证的类型化的值。
source (str) -- 类型化值的来源的字符串描述。

merge(parameters: collections.abc.Sequence[ObjectLoadedParameter]) → ObjectLoadedParameter#

递归地将匹配项合并为一个 LoadedParameter。

参数：: matches (List<LoadedParameter>) -- 此参数的匹配项列表。

返回: LoadedParameter

class ConfigurationObject#

虚拟类，用于标记 Python 对象是否包含配置参数。

to_json()#: 返回一个填充了默认值的可序列化对象

class Parameter(default, validation=None)#

Parameter 类表示一个未加载的配置参数，在参数加载配置之前，保存类型、默认值和验证信息。

参数：

default (Any) -- 如果在 Configuration 中未找到 Parameter，则给定的类型化的 Python 表示默认值。
validation (callable) -- 给定一个参数值作为输入，返回一个布尔值指示有效性，或者返回一个描述无效值的字符串。

property default#: 返回一个包装实际默认值的 DefaultValueRawParameter。

_type#

_element_type#

get_all_matches(name, names, instance)#

在 Configuration 实例中查找 Parameter 的所有匹配项

参数：

name (str) -- 要搜索的参数的规范名称
names (tuple(str)) -- 参数的备用别名
instance (Configuration) -- 要在其中搜索的配置实例

返回 (List(RawParameter)): 在配置中找到的参数的匹配项。

abstract load(name, match)#

使用 RawParameter 中的值加载 Parameter。

参数：

name (str) -- 要传递的参数的名称
match (RawParameter) -- RawParameter 匹配项的值

返回 LoadedParameter

typify(name, source, value)#

class PrimitiveParameter(default, element_type=None, validation=None)#

基类: Parameter

Configuration 类的 Parameter 类型，保存单个 python 原始值。

Python 原始类型包括 str、int、float、complex、bool 和 NoneType。此外，Python 2 还有 long 和 unicode 类型。

参数：

default (primitive value) -- 如果未找到 Parameter，则为默认值。
element_type (type 或 tuple[type]) -- 参数值的类型验证。如果为 None，则使用 type(default)。

load(name, match)#

使用 RawParameter 中的值加载 Parameter。

参数：

name (str) -- 要传递的参数的名称
match (RawParameter) -- RawParameter 匹配项的值

返回 LoadedParameter

class MapParameter(element_type, default=frozendict(), validation=None)#

基类: Parameter

Configuration 类的 Parameter 类型，保存 Parameters 的映射（即 dict）。

参数：

element_type (Parameter) -- MapParameter 中包含的 Parameter 类型。
default (Mapping) -- 参数的默认值。如果为 None，则将为空字典。

_type#

get_all_matches(name, names, instance)#

在 Configuration 实例中查找 Parameter 的所有匹配项

参数：

name (str) -- 要搜索的参数的规范名称
names (tuple(str)) -- 参数的备用别名
instance (Configuration) -- 要在其中搜索的配置实例

返回 (List(RawParameter)): 在配置中找到的参数的匹配项。

load(name, match)#

使用 RawParameter 中的值加载 Parameter。

参数：

name (str) -- 要传递的参数的名称
match (RawParameter) -- RawParameter 匹配项的值

返回 LoadedParameter

class SequenceParameter(element_type, default=(), validation=None, string_delimiter=',')#

基类: Parameter

Configuration 类的 Parameter 类型，保存 Parameters 的序列（即 list）。

参数：

element_type (Parameter) -- 序列中包含的 Parameter 类型。
default (Sequence) -- 默认值，如果未给定，则为空元组。
string_delimiter (str) -- 用于将字符串解析为序列的分隔字符串。

_type#

get_all_matches(name, names, instance)#

在 Configuration 实例中查找 Parameter 的所有匹配项

参数：

name (str) -- 要搜索的参数的规范名称
names (tuple(str)) -- 参数的备用别名
instance (Configuration) -- 要在其中搜索的配置实例

返回 (List(RawParameter)): 在配置中找到的参数的匹配项。

load(name, match)#

使用 RawParameter 中的值加载 Parameter。

参数：

name (str) -- 要传递的参数的名称
match (RawParameter) -- RawParameter 匹配项的值

返回 LoadedParameter

class ObjectParameter(element_type, default=ConfigurationObject(), validation=None)#

基类: Parameter

Configuration 类的 Parameter 类型，保存包含 Parameter 字段的对象。

参数：

element_type (object) -- 具有 ObjectParameter 中包含的参数字段的对象类型。
default (Sequence) -- 默认值，如果未给定，则为空元组。

_type#

get_all_matches(name, names, instance)#

在 Configuration 实例中查找 Parameter 的所有匹配项

参数：

name (str) -- 要搜索的参数的规范名称
names (tuple(str)) -- 参数的备用别名
instance (Configuration) -- 要在其中搜索的配置实例

返回 (List(RawParameter)): 在配置中找到的参数的匹配项。

load(name, match)#

使用 RawParameter 中的值加载 Parameter。

参数：

name (str) -- 要传递的参数的名称
match (RawParameter) -- RawParameter 匹配项的值

返回 LoadedParameter

class ParameterLoader(parameter_type, aliases=(), expandvars=False)#

ParameterLoader 类包含从开始到结束加载参数所需的顶层逻辑。

参数：

parameter_type (Parameter) -- 存储在加载器中的 Parameter 类型。
aliases (tuple(str)) -- Parameter 的备用别名
expandvars (bool) -- 是否递归展开环境变量。

property name#

property names#

_set_name(name)#

__get__(instance, instance_type)#

_raw_parameters_from_single_source(raw_parameters)#

static raw_parameters_from_single_source(name, names, raw_parameters)#

class ConfigurationType(name, bases, attr)#

基类: type

Configuration 的元类

CONDARC_FILENAMES = ('.condarc', 'condarc')#

YAML_EXTENSIONS = ('.yml', '.yaml')#

_RE_CUSTOM_EXPANDVARS#

custom_expandvars(template: str, mapping: collections.abc.Mapping[str, Any] = {}, /, **kwargs) → str#

展开字符串中的变量。

灵感来源于 string.Template 并修改为镜像 os.path.expandvars 功能，允许自定义变量而不改变 os.environ。

按如下方式展开 POSIX 和 Windows CMD 环境变量

$VARIABLE → VARIABLE 的值
${VARIABLE} → VARIABLE 的值
%VARIABLE% → VARIABLE 的值

无效的替换保持原样

$MISSING → $MISSING
${MISSING} → ${MISSING}
%MISSING% → %MISSING%
$$ → $$
%% → %%
$ → $
% → %

class Configuration(search_path=(), app_name=None, argparse_args=None, **kwargs)#

static _expand_search_path(search_path: collections.abc.Iterable[pathlib.Path | str], **kwargs) → collections.abc.Iterable[pathlib.Path]#

classmethod _load_search_path(search_path: collections.abc.Iterable[pathlib.Path]) → collections.abc.Iterable[tuple[pathlib.Path, dict]]#

_set_search_path(search_path: collections.abc.Iterable[pathlib.Path | str], **kwargs)#

_set_env_vars(app_name=None)#

_set_argparse_args(argparse_args)#

_set_raw_data(raw_data: collections.abc.Mapping[collections.abc.Hashable, dict])#

_reset_cache()#

register_reset_callaback(callback)#

check_source(source)#

validate_all()#

static _collect_validation_error(func, *args, **kwargs)#

validate_configuration()#

post_build_validation()#

collect_all()#

describe_parameter(parameter_name)#

list_parameters()#

typify_parameter(parameter_name, value, source)#

abstract get_descriptions()#

unique_sequence_map(*, unique_key: str)#: 用于验证在 Configuration 子类上定义的属性，这些子类定义为 SequenceParameter(MapParameter())，其中 map 包含一个应被视为唯一的键。此装饰器将处理删除重复项并合并为单个序列。