config.basic.component ====================== .. py:module:: config.basic.component .. autoapi-nested-parse:: 组件配置数据实现 .. versionadded:: 0.2.0 Classes ------- .. autoapisummary:: config.basic.component.ComponentConfigData config.basic.component.ComponentMember config.basic.component.ComponentMeta config.basic.component.ComponentOrders Module Contents --------------- .. py:class:: ComponentConfigData(meta: M | None = None, members: collections.abc.Mapping[str, D] | None = None) Bases: :py:obj:`config.basic.core.BasicConfigData`\ [\ :py:obj:`ComponentConfigData.D`\ ], :py:obj:`config.abc.ABCIndexedConfigData`\ [\ :py:obj:`ComponentConfigData.D`\ ] 组件配置数据 .. versionadded:: 0.2.0 :param meta: 组件元数据 :type meta: M | None :param members: 组件成员 :type members: Mapping[str, D] | None .. py:method:: __contains__(key: Any) -> bool .. py:method:: __deepcopy__(memo: dict[str, Any]) -> Self .. py:method:: __delitem__(index: Any) -> None .. danger:: 使用此操作可能会导致与元数据不同步且不经过校验！ .. py:method:: __eq__(other: Any) -> bool .. py:method:: __format__(format_spec: str) -> str .. py:method:: __getitem__(index: Any) -> D .. py:method:: __iter__() -> collections.abc.Iterator[str] .. py:method:: __len__() -> int .. py:method:: __repr__() -> str .. py:method:: __setitem__(index: Any, value: D) -> None .. danger:: 使用此操作可能会导致与元数据不同步且不经过校验！ .. py:method:: __str__() -> str .. py:method:: _member(member: str) -> D 通过成员文件名以及其别名获取成员配置数据 :param member: 成员名 :type member: str :return: 成员数据 :rtype: D .. py:method:: _resolve_members(path: ComponentConfigData._resolve_members.P, order: list[str], processor: collections.abc.Callable[[ComponentConfigData._resolve_members.P, D], ComponentConfigData._resolve_members.R], exception: Exception) -> ComponentConfigData._resolve_members.R 逐个尝试解析成员配置数据 :param path: 路径 :type path: P :param order: 成员处理顺序 :type order: list[str] :param processor: 成员处理函数 :type processor: Callable[[P, D], R] :param exception: 顺序为空抛出的错误 :type exception: Exception :return: 处理结果 :rtype: R .. important:: 针对 :py:exc:`RequiredPathNotFoundError` ， :py:exc:`ConfigDataTypeError` 做了特殊处理， 多个成员都抛出其一时最终仅抛出其中 :py:attr:`KeyInfo.index` 最大的 .. py:method:: delete(path: config.abc.PathLike, *args: Any, **kwargs: Any) -> Self 删除路径 :param path: 路径 :type path: PathLike :return: 返回当前实例便于链式调用 :rtype: Self :raise ConfigDataReadOnlyError: 配置数据为只读 :raise ConfigDataTypeError: 配置数据类型错误 :raise RequiredPathNotFoundError: 需求的键不存在 .. py:method:: exists(path: config.abc.PathLike, *args: Any, **kwargs: Any) -> 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: ComponentConfigData.get.V | None = None, *args: Any, return_raw_value: bool = False, **kwargs: Any) -> ComponentConfigData.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:: modify(path: config.abc.PathLike, *args: Any, **kwargs: Any) -> 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` 一样的类型新建路径 .. versionchanged:: 0.3.0 现在正确的先尝试使用 :py:attr:`~ComponentOrders.update` 对现有数据进行更新再尝试通过 :py:attr:`~ComponentOrders.create` 创建新数据 .. py:method:: retrieve(path: config.abc.PathLike, *args: Any, **kwargs: Any) -> 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: ComponentConfigData.setdefault.V | None = None, *args: Any, return_raw_value: bool = False, **kwargs: Any) -> ComponentConfigData.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, *args: Any, **kwargs: Any) -> Self 确保路径不存在 (删除路径，但是找不到路径时不会报错) :param path: 路径 :type path: PathLike :return: 返回当前实例便于链式调用 :rtype: Self :raise ConfigDataReadOnlyError: 配置数据为只读 :raise ConfigDataTypeError: 配置数据类型错误 .. versionadded:: 0.1.2 .. py:attribute:: __hash__ :value: None .. py:attribute:: __slots__ :value: () .. py:attribute:: _alias2filename :type: dict[str, str] .. py:attribute:: _filename2meta :type: dict[str, ComponentMember] .. py:attribute:: _members :type: collections.abc.Mapping[str, D] :value: None .. py:attribute:: _meta :type: M :value: None .. py:attribute:: _read_only :type: bool | None :value: False .. py:property:: alias2filename :type: collections.abc.Mapping[str, str] 别名到文件名的映射 .. py:property:: data_read_only :type: bool | None 组件数据是否为只读 .. py:property:: filename2meta :type: collections.abc.Mapping[str, ComponentMember] 文件名到成员元信息的映射 .. py:property:: members :type: collections.abc.Mapping[str, D] 组件成员 .. caution:: 未默认做深拷贝，可能导致非预期行为 .. py:property:: meta :type: M 组件元信息 .. caution:: 未默认做深拷贝，可能导致非预期行为 除非你知道你在做什么，不要轻易修改！ 由于 :py:class:`ComponentMeta` 仅提供一个通用的接口， 直接修改其中元数据而不修改 ``config`` 字段 `*可能*` 会导致SL与元数据的不同步， 这取决于 :py:class:`ComponentSL` 所取用的元数据解析器的行为 .. py:property:: read_only :type: bool | None 配置数据是否为 ``只读模式`` :return: 配置数据是否为 ``只读模式`` :rtype: bool | None .. py:class:: ComponentMember 组件成员 .. versionadded:: 0.2.0 .. py:attribute:: alias :type: str | None :value: None .. py:attribute:: config_format :type: str | None :value: None .. py:attribute:: filename :type: str .. py:class:: ComponentMeta 组件元数据 .. versionadded:: 0.2.0 .. py:attribute:: config :type: ComponentMeta.D .. py:attribute:: members :type: list[ComponentMember] :value: [] .. py:attribute:: orders :type: ComponentOrders .. py:attribute:: parser :type: config.abc.ABCMetaParser[Any, Any] | None :value: None .. py:class:: ComponentOrders 组件顺序 .. versionadded:: 0.2.0 .. py:attribute:: create :type: list[str] :value: [] .. py:attribute:: delete :type: list[str] :value: [] .. py:attribute:: read :type: list[str] :value: [] .. py:attribute:: update :type: list[str] :value: []