config.abc¶

配置抽象基类

Attributes¶

`AnyKey`
`PathLike`
`SLArgumentType`

Classes¶

`ABCConfigData`	配置数据抽象基类
`ABCConfigFile`	配置文件类
`ABCConfigPool`	配置池抽象类
`ABCConfigSL`	配置SaveLoad处理器抽象类
`ABCIndexedConfigData`	支持 `索引` 操作的配置数据
`ABCKey`	用于获取配置的键
`ABCMetaParser`	元信息解析器抽象类
`ABCPath`	用于获取数据的路径
`ABCProcessorHelper`	辅助SL处理器
`ABCSLProcessorPool`	SL处理器池

Module Contents¶

class ABCConfigData¶

Bases: abc.ABC

配置数据抽象基类

在 0.1.5 版本发生变更: 现在配置数据不再局限于Mapping

__format__(format_spec: str) → str¶

freeze(freeze: bool | None = None) → Self¶

冻结配置数据 (切换只读模式)

参数:: freeze (bool | None) -- 是否冻结配置数据, 为 None 时进行切换
返回:: 返回当前实例便于链式调用
返回类型:: Self

在 0.1.5 版本加入.

classmethod from_data(*args: Any, **kwargs: Any) → Self¶

提供创建同类型配置数据的快捷方式

返回:: 新的配置数据
返回类型:: Self

备注

套壳 __init__ 主要是为了方便内部快速创建与传入的ABCConfigData同类型的对象

例如：

type(instance)(data)

可以简写为

instance.from_data(data)

在 0.2.0 版本发生变更: 现在会自适应初始化参数

__slots__ = ()¶

property data_read_only: bool | None¶

Abstractmethod:

配置数据是否为只读

返回:: 配置数据是否为只读
返回类型:: bool | None

在 0.1.3 版本加入.

在 0.1.5 版本发生变更: 改为抽象属性

property read_only: bool | None¶

Abstractmethod:

配置数据是否为 只读模式

返回:: 配置数据是否为 只读模式
返回类型:: bool | None

class ABCConfigFile(initial_config: D, *, config_format: str | None = None)¶

Bases: abc.ABC

配置文件类

参数:

initial_config (D) -- 配置数据
config_format (str | None) -- 配置文件的格式

小心

initial_config 参数未默认做深拷贝，可能导致非预期行为

在 0.2.0 版本发生变更: 重命名参数 config_data 为 initial_config

__bool__() → bool¶

__eq__(other: Any) → bool¶

__repr__() → str¶

classmethod initialize(processor_pool: ABCSLProcessorPool, namespace: str, file_name: str, config_format: str, *processor_args: Any, **processor_kwargs: Any) → Self¶

Abstractmethod:

初始化一个受SL处理器支持的配置文件

参数:

processor_pool (ABCSLProcessorPool) -- 配置池
namespace (str) -- 文件命名空间
file_name (str) -- 文件名
config_format (str) -- 配置文件的格式

返回:

配置对象

返回类型:

Self

抛出:

UnsupportedConfigFormatError -- 不支持的配置格式

在 0.2.0 版本加入.

classmethod load(processor_pool: ABCSLProcessorPool, namespace: str, file_name: str, config_format: str, *processor_args: Any, **processor_kwargs: Any) → Self¶

Abstractmethod:

从SL处理器加载配置

参数:

processor_pool (ABCSLProcessorPool) -- 配置池
namespace (str) -- 文件命名空间
file_name (str) -- 文件名
config_format (str) -- 配置文件的格式

返回:

配置对象

返回类型:

Self

抛出:

UnsupportedConfigFormatError -- 不支持的配置格式

在 0.2.0 版本发生变更: 重命名 config_pool 为 processor_pool

abstractmethod save(processor_pool: ABCSLProcessorPool, namespace: str, file_name: str, config_format: str | None = None, *processor_args: Any, **processor_kwargs: Any) → None¶

使用SL处理保存配置

参数:

processor_pool (ABCSLProcessorPool) -- 配置池
namespace (str) -- 文件命名空间
file_name (str) -- 文件名
config_format (str | None) -- 配置文件的格式

抛出:

UnsupportedConfigFormatError -- 不支持的配置格式

在 0.2.0 版本发生变更: 重命名 config_pool 为 processor_pool

__hash__ = None¶

__slots__ = ()¶

_config: D¶

_config_format: str | None = None¶

property config: D¶

返回:: 配置数据

小心

未默认做深拷贝，可能导致非预期行为

在 0.2.0 版本发生变更: 重命名属性 data 为 config

property config_format: str | None¶: 配置文件的格式

class ABCConfigPool(root_path: str = './.config')¶

Bases: ABCSLProcessorPool

配置池抽象类

参数:: root_path (str) -- 保存的根目录

abstractmethod discard(namespace: str, file_name: str | None = None) → Self¶

确保配置文件不存在于配置池

参数:

namespace (str) -- 命名空间
file_name (str | None) -- 文件名

返回:

返回当前实例便于链式调用

返回类型:

Self

在 0.2.0 版本加入.

get(namespace: str) → dict[str, ABCConfigFile[Any]] | None¶

get(namespace: str, file_name: str) → ABCConfigFile[Any] | None

get(namespace: str, file_name: str | None = None) → dict[str, ABCConfigFile[Any]] | ABCConfigFile[Any] | None

获取配置

如果配置不存在则返回None

参数:

namespace (str) -- 命名空间
file_name (Optional[str]) -- 文件名

返回:

配置

返回类型:

dict[str, ABCConfigFile] | ABCConfigFile | None

abstractmethod initialize(namespace: str, file_name: str, *args: Any, config_formats: str | collections.abc.Iterable[str] | None = None, **kwargs: Any) → ABCConfigFile[Any]¶

初始化配置文件到指定命名空间并返回

参数:

namespace (str) -- 命名空间
file_name (str) -- 文件名
config_formats (str | Iterable[str] | None) -- 配置格式

返回:

配置对象

返回类型:

ABCConfigFile

在 0.2.0 版本加入.

abstractmethod load(namespace: str, file_name: str, *args: Any, config_formats: str | collections.abc.Iterable[str] | None = None, allow_initialize: bool = False, **kwargs: Any) → ABCConfigFile[Any]¶

加载配置到指定命名空间并返回

参数:

namespace (str) -- 命名空间
file_name (str) -- 文件名
config_formats (str | Iterable[str] | None) -- 配置格式
allow_initialize (bool) -- 是否允许初始化配置文件

返回:

配置对象

返回类型:

ABCConfigFile

在 0.2.0 版本发生变更: 现在会像 save() 一样接收并传递额外参数

删除参数 config_file_cls

重命名参数 allow_create 为 allow_initialize

abstractmethod remove(namespace: str, file_name: str | None = None) → Self¶

从配置池移除配置文件

参数:

namespace (str) -- 命名空间
file_name (str | None) -- 文件名

返回:

返回当前实例便于链式调用

返回类型:

Self

在 0.2.0 版本发生变更: 返回当前实例便于链式调用

重命名 delete 为 remove

abstractmethod save(namespace: str, file_name: str, config_formats: str | collections.abc.Iterable[str] | None = None, config: ABCConfigFile[Any] | None = None, *args: Any, **kwargs: Any) → Self¶

保存配置

参数:

namespace (str) -- 命名空间
file_name (str) -- 文件名
config_formats (str | Iterable[str] | None) -- 配置格式
config (ABCConfigFile | None) -- 配置文件，可选，提供此参数相当于自动调用了一遍pool.set

返回:

返回当前实例便于链式调用

返回类型:

Self

在 0.1.2 版本发生变更: 添加参数 config_formats 添加参数 config

在 0.2.0 版本发生变更: 返回当前实例便于链式调用

abstractmethod save_all(*, ignore_err: bool = False) → dict[str, dict[str, tuple[ABCConfigFile[Any], Exception]]] | None¶

保存所有配置

参数:: ignore_err (bool) -- 是否忽略保存导致的错误
返回:: ignore_err为True时返回{Namespace: {FileName: (ConfigObj, Exception)}}，否则返回None
返回类型:: dict[str, dict[str, tuple[ABCConfigFile, Exception]]] | None

在 0.3.0 版本发生变更: 更改参数 ignore_err 为仅关键字参数

abstractmethod set(namespace: str, file_name: str, config: ABCConfigFile[Any]) → Self¶

设置配置

参数:

namespace (str) -- 命名空间
file_name (str) -- 文件名
config (ABCConfigFile) -- 配置

返回:

返回当前实例便于链式调用

返回类型:

Self

在 0.2.0 版本发生变更: 返回当前实例便于链式调用

FileNameProcessors: collections.OrderedDict[str | re.Pattern[str], list[str]]¶

文件名处理器注册表

小心

此字典是顺序敏感的，越靠前越优先被检查

数据结构: {文件名匹配: [处理器注册名]}

文件名匹配:

为字符串时会使用 endswith 进行匹配
为 re.Pattern 时会使用 Pattern.fullmatch 进行匹配

在 0.2.0 版本发生变更: 重命名 FileExtProcessor 为 FileNameProcessors

现在是顺序敏感的

SLProcessors: dict[str, ABCConfigSL]¶

处理器注册表

数据结构: {处理器注册名: 处理器实例}}

在 0.2.0 版本发生变更: 重命名 SLProcessor 为 SLProcessors

__slots__ = ()¶

_root_path = './.config'¶

property helper: ABCProcessorHelper¶

Abstractmethod:

处理器助手

property root_path: str¶: 配置文件根目录

class ABCConfigSL(*, reg_alias: str | None = None)¶

Bases: abc.ABC

配置SaveLoad处理器抽象类

在 0.2.0 版本发生变更: 移动 保存加载器参数 相关至 BasicLocalFileConfigSL

参数:: reg_alias (Optional[str]) -- sl处理器注册别名

__eq__(other: Any) → bool¶

__hash__() → int¶

abstractmethod initialize(processor_pool: ABCSLProcessorPool, root_path: str, namespace: str, file_name: str, *args: Any, **kwargs: Any) → ABCConfigFile[Any]¶

初始化一个受SL处理器支持的配置文件

参数:

processor_pool (ABCSLProcessorPool) -- 配置池
root_path (str) -- 保存的根目录
namespace (str) -- 配置的命名空间
file_name (str) -- 配置文件名

返回:

配置对象

返回类型:

ABCConfigFile

在 0.2.0 版本加入.

abstractmethod load(processor_pool: ABCSLProcessorPool, root_path: str, namespace: str, file_name: str, *args: Any, **kwargs: Any) → ABCConfigFile[Any]¶

加载处理器

参数:

processor_pool (ABCSLProcessorPool) -- 配置池
root_path (str) -- 保存的根目录
namespace (str) -- 配置的命名空间
file_name (str) -- 配置文件名

返回:

配置对象

返回类型:

ABCConfigFile

抛出:

FailedProcessConfigFileError -- 处理配置文件失败

在 0.2.0 版本发生变更: 删除参数 config_file_cls

添加参数 processor_pool

register_to(config_pool: ABCSLProcessorPool) → Self¶

注册到配置池中

参数:: config_pool (ABCSLProcessorPool) -- 配置池
返回:: 返回当前实例便于链式调用
返回类型:: Self

在 0.3.0 版本发生变更: 返回当前实例便于链式调用

abstractmethod save(processor_pool: ABCSLProcessorPool, config_file: ABCConfigFile[Any], root_path: str, namespace: str, file_name: str, *args: Any, **kwargs: Any) → None¶

保存处理器

参数:

processor_pool (ABCSLProcessorPool) -- 配置池
config_file (ABCConfigFile) -- 待保存配置
root_path (str) -- 保存的根目录
namespace (str) -- 配置的命名空间
file_name (str) -- 配置文件名

抛出:

FailedProcessConfigFileError -- 处理配置文件失败

在 0.2.0 版本发生变更: 添加参数 processor_pool

__slots__ = ()¶

_reg_alias: str | None = None¶

property processor_reg_name: str¶

Abstractmethod:

SL处理器的默认注册名

property reg_alias: str | None¶: 处理器的别名

property reg_name: str¶: 处理器的注册名

property supported_file_classes: list[type[ABCConfigFile[Any]]]¶

Abstractmethod:
返回:: 支持的配置文件类

在 0.2.0 版本加入.

property supported_file_patterns: tuple[str | re.Pattern[Any], Ellipsis]¶

Abstractmethod:
返回:: 支持的文件名匹配

在 0.2.0 版本发生变更: 重命名 file_ext 为 supported_file_patterns

class ABCIndexedConfigData¶

Bases: ABCConfigData, config._protocols.MutableIndexed[Any, Any], abc.ABC

支持 索引 操作的配置数据

在 0.1.5 版本加入.

在 0.2.0 版本发生变更: 重命名 ABCSupportsIndexConfigData 为 ABCIndexedConfigData

abstractmethod __contains__(key: Any) → bool¶

abstractmethod __delitem__(index: Any) → None¶

__format__(format_spec: str) → str¶

abstractmethod __getitem__(index: Any) → Any¶

abstractmethod __iter__() → collections.abc.Iterator[Any]¶

abstractmethod __len__() → int¶

abstractmethod __setitem__(index: Any, value: Any) → None¶

abstractmethod delete(path: PathLike) → Self¶

删除路径

参数:

path (PathLike) -- 路径

返回:

返回当前实例便于链式调用

返回类型:

Self

抛出:

ConfigDataReadOnlyError -- 配置数据为只读
ConfigDataTypeError -- 配置数据类型错误
RequiredPathNotFoundError -- 需求的键不存在

abstractmethod exists(path: PathLike, *, ignore_wrong_type: bool = False) → bool¶

判断路径是否存在

参数:

path (PathLike) -- 路径
ignore_wrong_type (bool) -- 忽略配置数据类型错误

返回:

路径是否存在

返回类型:

bool

抛出:

ConfigDataTypeError -- 配置数据类型错误

freeze(freeze: bool | None = None) → Self¶

冻结配置数据 (切换只读模式)

参数:: freeze (bool | None) -- 是否冻结配置数据, 为 None 时进行切换
返回:: 返回当前实例便于链式调用
返回类型:: Self

在 0.1.5 版本加入.

classmethod from_data(*args: Any, **kwargs: Any) → Self¶

提供创建同类型配置数据的快捷方式

返回:: 新的配置数据
返回类型:: Self

备注

套壳 __init__ 主要是为了方便内部快速创建与传入的ABCConfigData同类型的对象

例如：

type(instance)(data)

可以简写为

instance.from_data(data)

在 0.2.0 版本发生变更: 现在会自适应初始化参数

abstractmethod get(path: PathLike, default: ABCIndexedConfigData.get.V | None = None, *, return_raw_value: bool = False) → ABCIndexedConfigData.get.V | Any¶

获取路径的值的*快照*，路径不存在时填充默认值

参数:

path (PathLike) -- 路径
default (V) -- 默认值
return_raw_value (bool) -- 是否获取原始值

返回:

路径的值

返回类型:

V | Any

抛出:

ConfigDataTypeError -- 配置数据类型错误

例子¶

>>> from c41811.config import MappingConfigData
>>> data = MappingConfigData({"key": "value"})

路径存在时返回值

>>> data.get("key")
'value'

路径不存在时返回默认值None

>>> print(data.get("not exists"))
None

自定义默认值

>>> data.get("with default", default="default value")
'default value'

在 0.2.0 版本发生变更: 重命名参数 get_raw 为 return_raw_value

abstractmethod modify(path: PathLike, value: Any, *, allow_create: bool = True) → Self¶

修改路径的值

参数:

path (PathLike) -- 路径
value (Any) -- 值
allow_create (bool) -- 是否允许创建不存在的路径，默认为True

返回:

返回当前实例便于链式调用

返回类型:

Self

抛出:

ConfigDataReadOnlyError -- 配置数据为只读
ConfigDataTypeError -- 配置数据类型错误
RequiredPathNotFoundError -- 需求的键不存在

小心

value 参数未默认做深拷贝，可能导致非预期行为

注意

allow_create 时，使用与 self.data 一样的类型新建路径

abstractmethod retrieve(path: PathLike, *, return_raw_value: bool = False) → Any¶

获取路径的值的*快照*

参数:

path (PathLike) -- 路径
return_raw_value (bool) -- 是否获取原始值，为 False 时，会将Mapping | Sequence转换为对应类

返回:

路径的值

返回类型:

Any

抛出:

ConfigDataTypeError -- 配置数据类型错误
RequiredPathNotFoundError -- 需求的键不存在

在 0.2.0 版本发生变更: 重命名参数 get_raw 为 return_raw_value

abstractmethod setdefault(path: PathLike, default: ABCIndexedConfigData.setdefault.V | None = None, *, return_raw_value: bool = False) → ABCIndexedConfigData.setdefault.V | Any¶

如果路径不在配置数据中则填充默认值到配置数据并返回

参数:

path (PathLike) -- 路径
default (V) -- 默认值
return_raw_value (bool) -- 是否获取原始值

返回:

路径的值

返回类型:

V | Any

抛出:

ConfigDataReadOnlyError -- 配置数据为只读
ConfigDataTypeError -- 配置数据类型错误

例子¶

>>> from c41811.config import MappingConfigData
>>> data = MappingConfigData({"key": "value"})

路径存在时返回值

>>> data.setdefault("key")
'value'

路径不存在时返回默认值None并填充到原始数据

>>> print(data.setdefault("not exists"))
None
>>> data
MappingConfigData({'key': 'value', 'not exists': None})

自定义默认值

>>> data.setdefault("with default", default="default value")
'default value'
>>> data
MappingConfigData({'key': 'value', 'not exists': None, 'with default': 'default value'})

在 0.2.0 版本发生变更: 重命名参数 get_raw 为 return_raw_value

重命名 set_default 为 setdefault

abstractmethod unset(path: PathLike) → Self¶

确保路径不存在 (删除路径，但是找不到路径时不会报错)

参数:

path (PathLike) -- 路径

返回:

返回当前实例便于链式调用

返回类型:

Self

抛出:

ConfigDataReadOnlyError -- 配置数据为只读
ConfigDataTypeError -- 配置数据类型错误

在 0.1.2 版本加入.

__slots__ = ()¶

property data_read_only: bool | None¶

Abstractmethod:

配置数据是否为只读

返回:: 配置数据是否为只读
返回类型:: bool | None

在 0.1.3 版本加入.

在 0.1.5 版本发生变更: 改为抽象属性

property read_only: bool | None¶

Abstractmethod:

配置数据是否为 只读模式

返回:: 配置数据是否为 只读模式
返回类型:: bool | None

class ABCKey(key: K, meta: str | None = None)¶

Bases: abc.ABC

用于获取配置的键

参数:

key (K) -- 键名
meta (str | None) -- 元信息

abstractmethod __contains_inner_element__(data: D) → bool¶

是否包含内层元素

参数:: data (D) -- 配置数据
返回:: 是否包含内层配置数据
返回类型:: bool

在 0.1.4 版本加入.

__deepcopy__(memo: dict[Any, Any]) → Self¶

abstractmethod __delete_inner_element__(data: D) → None¶

删除内层元素

参数:: data (D) -- 配置数据

在 0.1.4 版本加入.

__eq__(other: Any) → bool¶

abstractmethod __get_inner_element__(data: D) → D¶

获取内层元素

参数:: data (D) -- 配置数据
返回:: 内层配置数据
返回类型:: D

在 0.1.4 版本加入.

__hash__() → int¶

__repr__() → str¶

abstractmethod __set_inner_element__(data: D, value: Any) → None¶

设置内层元素

参数:

data (D) -- 配置数据
value (Any) -- 值

在 0.1.4 版本加入.

__str__() → str¶

abstractmethod __supports__(data: Any) → tuple[Any, Ellipsis]¶

检查此键是否支持该配置数据

返回缺失的协议

参数:: data (Any) -- 配置数据
返回:: 此键缺失支持的数据类型
返回类型:: tuple

在 0.1.4 版本加入.

abstractmethod __supports_modify__(data: Any) → tuple[Any, Ellipsis]¶

检查此键是否支持修改该配置数据

返回缺失的协议

参数:: data (Any) -- 配置数据
返回:: 此键缺失支持的数据类型
返回类型:: tuple

在 0.1.4 版本加入.

abstractmethod unparse() → str¶: 还原为可被解析的字符串

在 0.1.1 版本加入.

__slots__ = ()¶

_key¶

_meta: str | None = None¶

property key: K¶: 键

property meta: str | None¶: 元信息

在 0.2.0 版本加入.

class ABCMetaParser¶

Bases: abc.ABC

元信息解析器抽象类

在 0.2.0 版本加入.

abstractmethod convert_config2meta(meta_config: D) → M¶

解析元配置

参数:: meta_config (D) -- 元配置
返回:: 元数据
返回类型:: M

abstractmethod convert_meta2config(meta: M) → D¶

解析元数据

参数:: meta (M) -- 元数据
返回:: 元配置
返回类型:: D

abstractmethod validator(meta: M, *args: Any) → M¶: 元数据验证器

__slots__ = ()¶

class ABCPath(keys: collections.abc.Iterable[K])¶

Bases: abc.ABC, collections.abc.Iterable[ABCPath.K]

用于获取数据的路径

参数:: keys (Iterable[K]) -- 路径的键

__bool__() → bool¶

__contains__(item: Any) → bool¶

__deepcopy__(memo: dict[Any, Any]) → Self¶

__eq__(other: Any) → bool¶

__getitem__(item: slice) → Self¶
__getitem__(item: int) → K

__hash__() → int¶

__iter__() → collections.abc.Iterator[K]¶

__len__() → int¶

__repr__() → str¶

classmethod __subclasshook__(C)¶

abstractmethod unparse() → str¶: 还原为可被解析的字符串

在 0.1.1 版本加入.

__class_getitem__¶

__slots__ = ()¶

_keys¶

property keys: tuple[K, Ellipsis]¶: 键列表

备注

返回的是深拷贝副本，修改不会影响路径

在 0.2.0 版本加入.

class ABCProcessorHelper¶

Bases: abc.ABC

辅助SL处理器

在 0.2.0 版本加入.

static calc_path(root_path: str, namespace: str, file_name: str | None = None) → str¶

处理配置文件对应的文件路径

file_name为None时，返回文件所在的目录

参数:

root_path (str) -- 保存的根目录
namespace (str) -- 配置的命名空间
file_name (str | None) -- 配置文件名

返回:

配置文件路径

返回类型:

str

__slots__ = ()¶

class ABCSLProcessorPool(root_path: str = './.config')¶

Bases: abc.ABC

SL处理器池

参数:: root_path (str) -- 保存的根目录

FileNameProcessors: collections.OrderedDict[str | re.Pattern[str], list[str]]¶

文件名处理器注册表

小心

此字典是顺序敏感的，越靠前越优先被检查

数据结构: {文件名匹配: [处理器注册名]}

文件名匹配:

为字符串时会使用 endswith 进行匹配
为 re.Pattern 时会使用 Pattern.fullmatch 进行匹配

在 0.2.0 版本发生变更: 重命名 FileExtProcessor 为 FileNameProcessors

现在是顺序敏感的

SLProcessors: dict[str, ABCConfigSL]¶

处理器注册表

数据结构: {处理器注册名: 处理器实例}}

在 0.2.0 版本发生变更: 重命名 SLProcessor 为 SLProcessors

__slots__ = ()¶

_root_path = './.config'¶

property helper: ABCProcessorHelper¶

Abstractmethod:

处理器助手

property root_path: str¶: 配置文件根目录

type AnyKey = ABCKey[Any, Any]¶: 在 0.2.0 版本加入.

type PathLike = str | ABCPath[AnyKey]¶: 在 0.2.0 版本加入.

type SLArgumentType = Sequence[Any] | Mapping[str, Any] | tuple[Sequence[Any], Mapping[str, Any]] | None¶: 在 0.3.0 版本发生变更: 重命名 SLArgument 为 SLArgumentType