config.basic.environment¶

环境变量配置数据实现

在 0.2.0 版本加入.

Classes¶

`Difference`	与初始化数据的差异
`EnvironmentConfigData`	环境变量配置数据

Module Contents¶

class Difference¶

与初始化数据的差异

__bool__() → bool¶

__iadd__(other: Any) → Self¶

__isub__(other: Any) → Self¶

clear() → None¶: 清空差异

removed: set[str]¶: 删除的键

updated: set[str]¶: 修改/新增的键

备注

实现的不是很完美，如果一个键更改为了另一个值再改回来仍然会被认为是被修改过的键

class EnvironmentConfigData(data: collections.abc.MutableMapping[str, str] | None = None)¶

Bases: config.basic.mapping.MappingConfigData[collections.abc.MutableMapping[str, str]]

环境变量配置数据

内部维护了与初始化参数的键差异

备注

OSEnvSL 在保存时会重置差异数据

警告

当前实现不会验证值的类型，当值不是字符串类型时，在实际写入 os.environ 时会抛出错误，请确保传入的值是字符串类型

参数:: data (MutableMapping[str, str] | None) -- 环境变量数据

__bool__() → bool¶

__contains__(key: Any) → bool¶

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

__delitem__(index: str) → None¶

__eq__(other: Any) → bool¶

__format__(format_spec: str) → str¶

__getattr__(item: Any) → Self | Any¶

__getitem__(index: Any) → Any¶

__ior__(other: collections.abc.MutableMapping[str, str]) → Self¶

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

__len__() → int¶

__or__(other: Any) → Self¶

__repr__() → str¶

__ror__(other: Any) → Self¶

__setitem__(index: str, value: str) → 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: str, *, 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: EnvironmentConfigData.setdefault.V | None = None, *, return_raw_value: bool = False) → EnvironmentConfigData.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 = None, /, **kwargs: str) → 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 版本发生变更: 改为抽象属性

difference¶

property read_only: bool | None¶

配置数据是否为 只读模式

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