config.basic.mapping¶

映射类型配置数据实现

在 0.2.0 版本加入.

Classes¶

MappingConfigData

映射配置数据

Module Contents¶

class MappingConfigData(data: D | None = None)¶

Bases: config.basic.core.BasicIndexedConfigData[MappingConfigData.D], collections.abc.MutableMapping[Any, Any]

映射配置数据

在 0.1.5 版本加入.

参数:: data (D | None) -- 映射数据

__bool__() → bool¶

__contains__(key: Any) → bool¶

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

__delitem__(index: Any) → None¶

__eq__(other: Any) → bool¶

__format__(format_spec: str) → str¶

__getattr__(item: Any) → Self | Any¶

__getitem__(index: Any) → Any¶

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

__len__() → int¶

__or__(other: Any) → Self¶

__repr__() → str¶

__ror__(other: Any) → Self¶

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

__str__() → str¶

classmethod __subclasshook__(C)¶

_process_path(path: config.abc.ABCPath[Any], path_checker: collections.abc.Callable[[Any, config.abc.AnyKey, config.abc.ABCPath[Any], int], BasicIndexedConfigData._process_path.X], process_return: collections.abc.Callable[[Any], BasicIndexedConfigData._process_path.Y]) → BasicIndexedConfigData._process_path.X | BasicIndexedConfigData._process_path.Y¶

处理键路径的通用函数

参数:

path (ABCPath) -- 键路径
path_checker (Callable[(current_data: Any, current_key: ABCKey, last_path: ABCPath, path_index: int), X]) -- 检查并处理每个路径段，返回值非None时结束操作并返回值
process_return (Callable[(current_data: Any), Y]) -- 处理最终结果，该函数返回值会被直接返回

返回:

处理结果

返回类型:

X | Y

在 0.2.0 版本发生变更: 重命名参数 process_check 为 path_checker

clear() → None¶: D.clear() -> None. Remove all items from D.

delete(path: config.abc.PathLike) → Self¶

删除路径

参数:

path (PathLike) -- 路径

返回:

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

返回类型:

Self

抛出:

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

exists(path: config.abc.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 版本发生变更: 现在会自适应初始化参数

get(path: config.abc.PathLike, default: BasicIndexedConfigData.get.V | None = None, *, return_raw_value: bool = False) → BasicIndexedConfigData.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

items(*, return_raw_value: bool = False) → collections.abc.ItemsView[str, Any]¶

获取所有键值对

参数:: return_raw_value (bool) -- 是否获取原始数据
返回:: 所有键值对
返回类型:: ItemsView[str, Any]

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

keys(*, recursive: bool = False, strict: bool = True, end_point_only: bool = False) → collections.abc.KeysView[Any]¶

获取所有键

不为 Mapping 默认行为时键必须为 str 且返回值会被转换为配置数据路径字符串

参数:

recursive (bool) -- 是否递归获取
strict (bool) -- 是否严格检查循环引用数据，为真时提前抛出错误，否则静默忽略
end_point_only (bool) -- 是否只获取叶子节点

返回:

所有键

返回类型:

KeysView[str]

抛出:

TypeError -- 递归获取时键不为str时抛出
CyclicReferenceError -- 严格检查循环引用数据时发现循环引用抛出

例子¶

>>> from c41811.config import MappingConfigData
>>> data = MappingConfigData({"foo": {"bar": {"baz": "value"}, "bar1": "value1"}, "foo1": "value2"})

不带参数行为与普通字典一样

>>> data.keys()
dict_keys(['foo', 'foo1'])

参数 end_point_only 会滤掉非 叶子节点 的键

>>> data.keys(end_point_only=True)  # 内部计算为保留顺序采用了OrderedDict所以返回值是odict_keys
odict_keys(['foo1'])

参数 recursive 用于获取所有的 路径

>>> data.keys(recursive=True)
odict_keys(['foo\\.bar\\.baz', 'foo\\.bar', 'foo\\.bar1', 'foo', 'foo1'])

同时提供 recursive 和 end_point_only 会产出所有 叶子节点 的路径

>>> data.keys(recursive=True, end_point_only=True)
odict_keys(['foo\\.bar\\.baz', 'foo\\.bar1', 'foo1'])

为严格模式时会检查循环引用并提前引发错误

>>> cyclic: dict[str, Any] = {"cyclic": None, "key": "value"}
>>> cyclic["cyclic"] = cyclic
>>> cyclic: MappingConfigData[dict[str, Any]] = MappingConfigData(cyclic)

>>> cyclic.keys(recursive=True)  # 默认为严格模式
Traceback (most recent call last):
    ...
c41811.config.errors.CyclicReferenceError: Cyclic reference detected at \.cyclic -> \.cyclic (1/1)

否则静默跳过循环引用

>>> cyclic.keys(recursive=True, strict=False)
odict_keys(['cyclic', 'key'])

>>> cyclic.keys(recursive=True, strict=False, end_point_only=True)
odict_keys(['key'])

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

modify(path: config.abc.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 一样的类型新建路径

pop(path: config.abc.PathLike, /, default: Any = Unset) → Any¶: D.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → Any¶: D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty.

retrieve(path: config.abc.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

setdefault(path: config.abc.PathLike, default: BasicIndexedConfigData.setdefault.V | None = None, *, return_raw_value: bool = False) → BasicIndexedConfigData.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

unset(path: config.abc.PathLike) → Self¶

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

参数:

path (PathLike) -- 路径

返回:

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

返回类型:

Self

抛出:

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

在 0.1.2 版本加入.

update(m: Any = None, /, **kwargs: Any) → None¶: D.update([E, ]**F) -> None. Update D from mapping/iterable E and F. If E present and has a .keys() method, does: for k in E.keys(): D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values(return_raw_value: bool = False) → collections.abc.ValuesView[Any]¶

获取所有值

参数:: return_raw_value (bool) -- 是否获取原始数据
返回:: 所有键值对
返回类型:: ValuesView[Any]

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

__abc_tpflags__ = 64¶

__class_getitem__¶

__hash__ = None¶

__marker¶

__reversed__ = None¶

__slots__ = ()¶

_data: MappingConfigData.D¶

_read_only: bool | None = False¶

data: MappingConfigData.D¶: 配置的原始数据*快照*

property data_read_only: bool¶

配置数据是否为只读

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

在 0.1.3 版本加入.

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

property read_only: bool | None¶

配置数据是否为 只读模式

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