config.basic.core¶

主要中间层

在 0.2.0 版本加入.

Classes¶

`BasicConfigData`	配置数据基类
`BasicConfigPool`	基础配置池类
`BasicIndexedConfigData`	支持 `索引` 操作的配置数据基类
`BasicSingleConfigData`	单文件配置数据基类
`ConfigFile`	配置文件类
`PHelper`	处理器助手类

Module Contents¶

class BasicConfigData¶

Bases: config.abc.ABCConfigData, abc.ABC

配置数据基类

在 0.1.5 版本加入.

在 0.2.0 版本发生变更: 重命名 BaseConfigData 为 BasicConfigData

__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__ = ()¶

_read_only: bool | None = False¶

property data_read_only: bool | None¶

配置数据是否为只读

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

在 0.1.3 版本加入.

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

property read_only: bool | None¶

配置数据是否为 只读模式

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

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

Bases: config.abc.ABCConfigPool, abc.ABC

基础配置池类

实现了一些通用方法

在 0.2.0 版本发生变更: 重命名 BaseConfigPool 为 BasicConfigPool

参数:: root_path (str) -- 配置根路径

__contains__(item: Any) → bool¶: 在 0.1.2 版本加入.

__getitem__(item: str | tuple[str, str]) → dict[str, config.abc.ABCConfigFile[Any]] | config.abc.ABCConfigFile[Any]¶

__len__() → int¶: 配置文件总数

__repr__() → str¶

_get_formats(file_name: str, config_formats: str | collections.abc.Iterable[str] | None, configfile_format: str | None = None) → collections.abc.Iterable[str]¶

从给定参数计算所有可能的配置格式

注意

返回所有可能的配置格式，不会检查配置格式是否存在！可迭代对象的产生顺序即为配置格式优先级，优先级逻辑见下表

参数:

file_name (str) -- 文件名
config_formats (str | Iterable[str] | None) -- 配置格式
configfile_format --
该配置文件对象本身配置格式属性的值可选项，一般在保存时填入用于在没手动指定配置格式且没文件后缀时使用该值进行尝试

参见

ABCConfigFile.config_format

返回:

配置格式

返回类型:

Iterable[str]

抛出:

UnsupportedConfigFormatError -- 不支持的配置格式

格式计算优先级¶

1.config_formats的bool求值为真

2.文件名注册了对应的SL处理器

3.configfile_format非None

在 0.2.0 版本加入.

_try_sl_processors(namespace: str, file_name: str, config_formats: str | collections.abc.Iterable[str] | None, processor: collections.abc.Callable[[Self, str, str, str], BasicConfigPool._try_sl_processors.R], file_config_format: str | None = None) → BasicConfigPool._try_sl_processors.R¶

自动尝试推断ABCConfigFile所支持的config_format

参数:

namespace (str) -- 命名空间
file_name (str) -- 文件名
config_formats (str | Iterable[str] | None) -- 配置格式
processor (Callable[[Self, str, str, str], R]) -- 处理器，参数为[配置池对象, 命名空间, 文件名, 配置格式]返回值会被直接返回，出现意料内的SL处理器无法处理需抛出FailedProcessConfigFileError以允许继续尝试别的SL处理器
file_config_format --
该配置文件对象本身配置格式属性的值可选项，一般在保存时填入用于在没手动指定配置格式且没文件后缀时使用该值进行尝试

参见

ABCConfigFile.config_format

返回:

处理器返回值

返回类型:

抛出:

UnsupportedConfigFormatError -- 不支持的配置格式
FailedProcessConfigFileError -- 处理配置文件失败

参见

格式计算优先级

_get_formats()

在 0.1.2 版本加入.

在 0.2.0 版本发生变更: 拆分格式计算到方法 _get_formats()

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

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

参数:

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

返回:

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

返回类型:

Self

在 0.2.0 版本加入.

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

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

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

获取配置

如果配置不存在则返回None

参数:

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

返回:

配置

返回类型:

dict[str, ABCConfigFile] | ABCConfigFile | None

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

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

参数:

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

返回:

配置对象

返回类型:

ABCConfigFile

在 0.2.0 版本加入.

load(namespace: str, file_name: str, *args: Any, config_formats: str | collections.abc.Iterable[str] | None = None, allow_initialize: bool = False, **kwargs: Any) → config.abc.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

现在由 ABCConfigFile.initialize() 创建新的空 ABCConfigFile 对象

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

从配置池移除配置文件

参数:

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

返回:

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

返回类型:

Self

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

重命名 delete 为 remove

save(namespace: str, file_name: str, config_formats: str | collections.abc.Iterable[str] | None = None, config: config.abc.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 版本发生变更: 返回当前实例便于链式调用

save_all(*, ignore_err: bool = False) → dict[str, dict[str, tuple[config.abc.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 为仅关键字参数

set(namespace: str, file_name: str, config: config.abc.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__ = ()¶

_configs: dict[str, dict[str, config.abc.ABCConfigFile[Any]]]¶

_helper¶

_root_path = './.config'¶

property configs: dict[str, dict[str, config.abc.ABCConfigFile[Any]]]¶: 配置文件字典

property helper: config.abc.ABCProcessorHelper¶: 处理器助手

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

class BasicIndexedConfigData(data: D)¶

Bases: BasicSingleConfigData[BasicIndexedConfigData.D], config.abc.ABCIndexedConfigData[BasicIndexedConfigData.D], abc.ABC

支持 索引 操作的配置数据基类

在 0.1.5 版本加入.

在 0.2.0 版本发生变更: 重命名 BaseSupportsIndexConfigData 为 BasicIndexedConfigData

参数:: data (Any) -- 配置的原始数据

__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¶

__getitem__(index: Any) → Any¶

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

__len__() → int¶

__repr__() → str¶

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

__str__() → str¶

_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

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

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 一样的类型新建路径

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 版本加入.

__hash__ = None¶

__slots__ = ()¶

_data: D¶

_read_only: bool | None = False¶

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

property data_read_only: bool | None¶

配置数据是否为只读

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

在 0.1.3 版本加入.

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

property read_only: bool | None¶

配置数据是否为 只读模式

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

class BasicSingleConfigData(data: D)¶

Bases: BasicConfigData[BasicSingleConfigData.D], abc.ABC

单文件配置数据基类

在 0.2.0 版本加入.

参数:: data (Any) -- 配置的原始数据

__bool__() → bool¶

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

__eq__(other: Any) → bool¶

__format__(format_spec: str) → str¶

__repr__() → str¶

__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 版本发生变更: 现在会自适应初始化参数

__hash__ = None¶

__slots__ = ()¶

_data: D¶

_read_only: bool | None = False¶

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

property data_read_only: bool | None¶

配置数据是否为只读

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

在 0.1.3 版本加入.

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

property read_only: bool | None¶

配置数据是否为 只读模式

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

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

Bases: config.abc.ABCConfigFile[ConfigFile.D]

配置文件类

参数:

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

小心

本身并未对 initial_config 参数进行深拷贝，但是 ConfigDataFactory 分发的类可能会将其深拷贝

在 0.2.0 版本发生变更: 现在会自动尝试使用 ConfigDataFactory 转换 initial_config 参数

重命名参数 config_data 为 initial_config

__bool__() → bool¶

__eq__(other: Any) → bool¶

__repr__() → str¶

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

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

参数:

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

返回:

配置对象

返回类型:

Self

抛出:

UnsupportedConfigFormatError -- 不支持的配置格式

在 0.2.0 版本加入.

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

从SL处理器加载配置

参数:

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

返回:

配置对象

返回类型:

Self

抛出:

UnsupportedConfigFormatError -- 不支持的配置格式

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

save(processor_pool: config.abc.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 PHelper¶

Bases: config.abc.ABCProcessorHelper

处理器助手类

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__ = ()¶