config.basic.environment ======================== .. py:module:: config.basic.environment .. autoapi-nested-parse:: 环境变量配置数据实现 .. versionadded:: 0.2.0 Classes ------- .. autoapisummary:: config.basic.environment.Difference config.basic.environment.EnvironmentConfigData Module Contents --------------- .. py:class:: Difference 与初始化数据的差异 .. py:method:: __bool__() -> bool .. py:method:: __iadd__(other: Any) -> Self .. py:method:: __isub__(other: Any) -> Self .. py:method:: clear() -> None 清空差异 .. py:attribute:: removed :type: set[str] 删除的键 .. py:attribute:: updated :type: set[str] 修改/新增的键 .. note:: 实现的不是很完美，如果一个键更改为了另一个值再改回来仍然会被认为是被修改过的键 .. py:class:: EnvironmentConfigData(data: collections.abc.MutableMapping[str, str] | None = None) Bases: :py:obj:`config.basic.mapping.MappingConfigData`\ [\ :py:obj:`collections.abc.MutableMapping`\ [\ :py:obj:`str`\ , :py:obj:`str`\ ]\ ] 环境变量配置数据 内部维护了与初始化参数的键差异 .. note:: :py:class:`~config.processor.OSEnv.OSEnvSL` 在保存时会重置差异数据 .. warning:: 当前实现 `不会验证值的类型` ，当值不是字符串类型时，在实际写入 :py:data:`os.environ` 时会抛出错误， 请确保传入的值是字符串类型 :param data: 环境变量数据 :type data: MutableMapping[str, str] | None .. py:method:: __bool__() -> bool .. py:method:: __contains__(key: Any) -> bool .. py:method:: __deepcopy__(memo: dict[str, Any]) -> Self .. py:method:: __delitem__(index: str) -> None .. py:method:: __eq__(other: Any) -> bool .. py:method:: __format__(format_spec: str) -> str .. py:method:: __getattr__(item: Any) -> Self | Any .. py:method:: __getitem__(index: Any) -> Any .. py:method:: __ior__(other: collections.abc.MutableMapping[str, str]) -> Self .. py:method:: __iter__() -> collections.abc.Iterator[D] .. py:method:: __len__() -> int .. py:method:: __or__(other: Any) -> Self .. py:method:: __repr__() -> str .. py:method:: __ror__(other: Any) -> Self .. py:method:: __setitem__(index: str, value: str) -> None .. py:method:: __str__() -> str .. py:method:: __subclasshook__(C) :classmethod: .. py:method:: _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 处理键路径的通用函数 :param path: 键路径 :type path: ABCPath :param path_checker: 检查并处理每个路径段，返回值非None时结束操作并返回值 :type path_checker: Callable[(current_data: Any, current_key: ABCKey, last_path: ABCPath, path_index: int), X] :param process_return: 处理最终结果，该函数返回值会被直接返回 :type process_return: Callable[(current_data: Any), Y] :return: 处理结果 :rtype: X | Y .. versionchanged:: 0.2.0 重命名参数 ``process_check`` 为 ``path_checker`` .. py:method:: clear() -> None D.clear() -> None. Remove all items from D. .. py:method:: delete(path: config.abc.PathLike) -> Self 删除路径 :param path: 路径 :type path: PathLike :return: 返回当前实例便于链式调用 :rtype: Self :raise ConfigDataReadOnlyError: 配置数据为只读 :raise ConfigDataTypeError: 配置数据类型错误 :raise RequiredPathNotFoundError: 需求的键不存在 .. py:method:: exists(path: config.abc.PathLike, *, ignore_wrong_type: bool = False) -> bool 判断路径是否存在 :param path: 路径 :type path: PathLike :param ignore_wrong_type: 忽略配置数据类型错误 :type ignore_wrong_type: bool :return: 路径是否存在 :rtype: bool :raise ConfigDataTypeError: 配置数据类型错误 .. py:method:: freeze(freeze: bool | None = None) -> Self 冻结配置数据 (切换只读模式) :param freeze: 是否冻结配置数据, 为 :py:const:`None` 时进行切换 :type freeze: bool | None :return: 返回当前实例便于链式调用 :rtype: Self .. versionadded:: 0.1.5 .. py:method:: from_data(*args: Any, **kwargs: Any) -> Self :classmethod: 提供创建同类型配置数据的快捷方式 :return: 新的配置数据 :rtype: Self .. note:: 套壳 ``__init__`` 主要是为了方便内部快速创建与传入的ABCConfigData同类型的对象 例如： .. code-block:: python type(instance)(data) 可以简写为 .. code-block:: python instance.from_data(data) .. versionchanged:: 0.2.0 现在会自适应初始化参数 .. py:method:: get(path: config.abc.PathLike, default: BasicIndexedConfigData.get.V | None = None, *, return_raw_value: bool = False) -> BasicIndexedConfigData.get.V | Any 获取路径的值的*快照*，路径不存在时填充默认值 :param path: 路径 :type path: PathLike :param default: 默认值 :type default: V :param return_raw_value: 是否获取原始值 :type return_raw_value: bool :return: 路径的值 :rtype: V | Any :raise 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' .. versionchanged:: 0.2.0 重命名参数 ``get_raw`` 为 ``return_raw_value`` .. py:method:: items(*, return_raw_value: bool = False) -> collections.abc.ItemsView[str, Any] 获取所有键值对 :param return_raw_value: 是否获取原始数据 :type return_raw_value: bool :return: 所有键值对 :rtype: ItemsView[str, Any] .. versionchanged:: 0.2.0 重命名参数 ``get_raw`` 为 ``return_raw_value`` .. py:method:: keys(*, recursive: bool = False, strict: bool = True, end_point_only: bool = False) -> collections.abc.KeysView[Any] 获取所有键 不为 :py:class:`~collections.abc.Mapping` 默认行为时键必须为 :py:class:`str` 且返回值会被转换为 :ref:`配置数据路径字符串 ` :param recursive: 是否递归获取 :type recursive: bool :param strict: 是否严格检查循环引用数据，为真时提前抛出错误，否则静默忽略 :type strict: bool :param end_point_only: 是否只获取叶子节点 :type end_point_only: bool :return: 所有键 :rtype: KeysView[str] :raise TypeError: 递归获取时键不为str时抛出 :raise 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']) .. versionchanged:: 0.2.0 添加参数 ``strict`` .. py:method:: modify(path: config.abc.PathLike, value: str, *, allow_create: bool = True) -> Self 修改路径的值 :param path: 路径 :type path: PathLike :param value: 值 :type value: Any :param allow_create: 是否允许创建不存在的路径，默认为True :type allow_create: bool :return: 返回当前实例便于链式调用 :rtype: Self :raise ConfigDataReadOnlyError: 配置数据为只读 :raise ConfigDataTypeError: 配置数据类型错误 :raise RequiredPathNotFoundError: 需求的键不存在 .. caution:: ``value`` 参数未默认做深拷贝，可能导致非预期行为 .. attention:: ``allow_create`` 时，使用与 `self.data` 一样的类型新建路径 .. py:method:: 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. .. py:method:: popitem() -> Any D.popitem() -> (k, v), remove and return some (key, value) pair as a 2-tuple; but raise KeyError if D is empty. .. py:method:: retrieve(path: config.abc.PathLike, *, return_raw_value: bool = False) -> Any 获取路径的值的*快照* :param path: 路径 :type path: PathLike :param return_raw_value: 是否获取原始值，为 :py:const:`False` 时，会将Mapping | Sequence转换为对应类 :type return_raw_value: bool :return: 路径的值 :rtype: Any :raise ConfigDataTypeError: 配置数据类型错误 :raise RequiredPathNotFoundError: 需求的键不存在 .. versionchanged:: 0.2.0 重命名参数 ``get_raw`` 为 ``return_raw_value`` .. py:method:: setdefault(path: config.abc.PathLike, default: EnvironmentConfigData.setdefault.V | None = None, *, return_raw_value: bool = False) -> EnvironmentConfigData.setdefault.V | Any 如果路径不在配置数据中则填充默认值到配置数据并返回 :param path: 路径 :type path: PathLike :param default: 默认值 :type default: V :param return_raw_value: 是否获取原始值 :type return_raw_value: bool :return: 路径的值 :rtype: V | Any :raise ConfigDataReadOnlyError: 配置数据为只读 :raise 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'}) .. versionchanged:: 0.2.0 重命名参数 ``get_raw`` 为 ``return_raw_value`` 重命名 ``set_default`` 为 ``setdefault`` .. py:method:: unset(path: config.abc.PathLike) -> Self 确保路径不存在 (删除路径，但是找不到路径时不会报错) :param path: 路径 :type path: PathLike :return: 返回当前实例便于链式调用 :rtype: Self :raise ConfigDataReadOnlyError: 配置数据为只读 :raise ConfigDataTypeError: 配置数据类型错误 .. versionadded:: 0.1.2 .. py:method:: 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 .. py:method:: values(return_raw_value: bool = False) -> collections.abc.ValuesView[Any] 获取所有值 :param return_raw_value: 是否获取原始数据 :type return_raw_value: bool :return: 所有键值对 :rtype: ValuesView[Any] .. versionchanged:: 0.2.0 重命名参数 ``get_raw`` 为 ``return_raw_value`` .. py:attribute:: __abc_tpflags__ :value: 64 .. py:attribute:: __class_getitem__ .. py:attribute:: __hash__ :value: None .. py:attribute:: __marker .. py:attribute:: __reversed__ :value: None .. py:attribute:: __slots__ :value: () .. py:attribute:: _data :type: MappingConfigData.D .. py:attribute:: _read_only :type: bool | None :value: False .. py:attribute:: data :type: MappingConfigData.D 配置的原始数据*快照* .. py:property:: data_read_only :type: bool 配置数据是否为只读 :return: 配置数据是否为只读 :rtype: bool | None .. versionadded:: 0.1.3 .. versionchanged:: 0.1.5 改为抽象属性 .. py:attribute:: difference .. py:property:: read_only :type: bool | None 配置数据是否为 ``只读模式`` :return: 配置数据是否为 ``只读模式`` :rtype: bool | None