详细文档

配置数据路径语法

一种简便的配置数据访问路径表示方法， 在一些高级方法如 retrieve() 中使用

由三种语法组成

属性键

由 \. 开头，紧随的字符串组成

例

r"\.key1\.key2\.key3"

小技巧

如果路径字符串以 属性键 开头可以省略 \.

例

r"key1\.key2\.key3"

# 这将被视为

r"\.key1\.key2\.key3"

索引键

由 \[ 开头，紧随的数字与 \] 组成

例

r"\[0\]"

元信息

由 \{ 开头，紧随的字符串与 \} 组成

元信息会被附加到紧随的键上

例

r"\{meta 1\}\.key\{meta 2\}\[0\]"

# 这相当于

[AttrKey("key", meta="meta 1"), IndexKey(0, meta="meta 2")]

转义

键名或元信息中如有 \ 需要转义 为 \\

例

r"\{1\\2\}\.\\key\{2\\2\}\[0\]"

# 这将解析为

[AttrKey(r"\key", meta=r"1\2"), IndexKey(0, meta=r"2\2")]

可以简单的通过 str.replace("\\", "\\\\") 来转义

注意

如果没有转义，且 \ 后面的字符不是以上特殊转义字符，则会原样保留并发出警告

不应依赖此行为

requireConfig

用于加载并验证配置数据的高层方法

小技巧

提供参数 static_config 以获得更高性能

参见

RequiredPath

有手动调用和装饰器两种获取验证数据的方式

手动调用和装饰器

from c41811.config import MappingConfigData
from c41811.config import JsonSL
from c41811.config import requireConfig

JsonSL().register_to()

require = requireConfig(
    "", "config.json", {
        "config": "data",
    },
)

# 调用check手动获取配置数据
config: MappingConfigData = require.check()
print(config)  # 打印：{'config': 'data'}


# 使用装饰器自动注入配置数据
@require
def test(cfg):
    print(cfg)  # 打印：{'config': 'data'}


test()


class Test:
    @require
    def __init__(self, cfg):
        print(self, cfg)  # 打印：<__main__.Test object at 0x0000025B37D812E0> {'config': 'data'}

    @classmethod
    @require
    def cls_func(cls, cfg):
        print(cls, cfg)  # 打印：<class '__main__.Test'> {'config': 'data'}
        return cls

    @staticmethod
    @require
    def static_func(cfg):
        print(cfg)  # 打印：{'config': 'data'}


Test().cls_func().static_func()

Pydantic验证器工厂

提示

pydantic 验证器工厂不支持 skip_missing 选项 这是因为pydantic自带该功能 如果提供了该参数会产生一个警告 不会起到任何实际作用

validator_factory 参数设为 PYDANTIC 或 "pydantic" 时使用该验证工厂

validator 参数为任意合法的 BaseModel

一个简单的pydantic验证器

from pydantic import BaseModel
from pydantic import Field

from c41811.config import MappingConfigData
from c41811.config import ConfigFile
from c41811.config import JsonSL
from c41811.config import requireConfig
from c41811.config import save

JsonSL().register_to()

save("", "test.json", config=ConfigFile(MappingConfigData({
    "key": "value"
})))


class Config(BaseModel):
    key: str = "default value"
    unknown_key: dict = Field(default_factory=dict)


print(requireConfig("", "test.json", Config, "pydantic").check())
# 打印：{'key': 'value', 'unknown_key': {}}

默认验证器工厂

validator_factory 参数设为 DEFAULT 或 None 时使用该验证工厂

validator 参数可以为 Iterable[str] 或 Mapping[str | ABCPath, Any]

Iterable 的元素或 Mapping 的键会被作为 配置数据路径语法 解析，如非特殊配置结果将一定包含这些 配置数据路径

备注

[path, path1, path2, ...] 与 {path: Any, path1: Any, path2: Any, ...} 等价

小技巧

如果validator同时包含路径和路径的父路径

例： r"\.first\.second\.third" 与 r"\.first" 同时出现

这时 first 中不仅包含 second ，还会允许任意额外的键

例

from c41811.config import MappingConfigData
from c41811.config import ConfigFile
from c41811.config import JsonSL
from c41811.config import requireConfig
from c41811.config import save

JsonSL().register_to()

save("", "test.json", config=ConfigFile(MappingConfigData({
    "first": {
        "second": {
            "third": 111,
            "foo": 222
        },
        "bar": 333
    },
    "baz": 444
})))

print(requireConfig("", "test.json", ["first", "first\\.second\\.third"]).check())
# 打印：{'first': {'second': {'third': 111}, 'bar': 333}}

Iterable[str]

一组需求的 配置数据路径 ，会检查路径存在与否，不会校验数据类型

例

from c41811.config import MappingConfigData
from c41811.config import ConfigFile
from c41811.config import JsonSL
from c41811.config import requireConfig
from c41811.config import save

JsonSL().register_to()

save("", "test.json", config=ConfigFile(MappingConfigData({
    "foo": {
        "bar": {
            "baz": "value"
        },
        "bar1": "value1"
    },
    "foo1": "value2"
})))

print(requireConfig("", "test.json", ["foo", "foo\\.bar\\.baz", "foo1"]).check())
# 打印：{'foo': {'bar': {'baz': 'value'}, 'bar1': 'value1'}, 'foo1': 'value2'}

Mapping[str | ABCPath, Any]

键为 配置数据路径 ，值为需求的数据类型，会检查路径存在与否，并校验数据类型

小技巧

r"first\.second\.third": int 与 "first": {"second": {"third": int}} 等价

• 允许混用路径与嵌套字典

路径与嵌套字典的等价操作

from c41811.config import MappingConfigData
from c41811.config import ConfigFile
from c41811.config import JsonSL
from c41811.config import requireConfig
from c41811.config import save

JsonSL().register_to()

save("", "test.json", config=ConfigFile(MappingConfigData({
    "first": {
        "second": {
            "third": 111,
            "foo": 222
        },
        "bar": 333
    },
    "baz": 444
})))

paths = requireConfig("", "test.json", {
    r"first\.second\.third": int,
    r"first\.bar": int,
}).check()
nested_dict = requireConfig("", "test.json", {
    "first": {
        "second": {
            "third": int
        },
        "bar": int
    }
}).check()

print(paths)  # 打印: {'first': {'second': {'third': 111}, 'bar': 333}}
print(nested_dict)  # 打印: {'first': {'second': {'third': 111}, 'bar': 333}}
print(paths == nested_dict)  # 打印: True

以下是两种验证器语法

两种验证器语法

from c41811.config import MappingConfigData
from c41811.config import ConfigFile
from c41811.config import JsonSL
from c41811.config import requireConfig
from c41811.config import save

JsonSL().register_to()

save("", "test.json", config=ConfigFile(MappingConfigData({
    "first": {
        "second": {
            "third": 111,
            "foo": 222
        },
        "bar": 333
    },
    "baz": 444
})))

# 使用路径字符串
print(requireConfig("", "test.json", {
    "first\\.second\\.third": int,
    "first\\.bar": int,
}).check())  # 打印：{'first': {'second': {'third': 111}, 'bar': 333}}

# 使用嵌套字典
print(requireConfig("", "test.json", {
    "first": {
        "second": {
            "third": int
        },
        "bar": int
    }
}).check())  # 打印：{'first': {'second': {'third': 111}, 'bar': 333}}

# 混搭
print(requireConfig("", "test.json", {
    "first": {
        "second\\.third": int,
        "second": dict,
        "bar": int
    },
    "baz": int
}).check())  # 打印： {'first': {'second': {'third': 111, 'foo': 222}, 'bar': 333}, 'baz': 444}

类型检查和填充默认值功能

类型检查和填充默认值

from typing import Sequence

from c41811.config import MappingConfigData
from c41811.config import ConfigFile
from c41811.config import FieldDefinition
from c41811.config import JsonSL
from c41811.config import requireConfig
from c41811.config import save
from c41811.config.errors import ConfigDataTypeError

JsonSL().register_to()

save("", "test.json", config=ConfigFile(MappingConfigData({
    "first": {
        "second": {
            "third": 111,
            "foo": 222
        },
        "bar": 333
    },
    "baz": [444]
})))

# 类型检查，如果不满足会报错
print(requireConfig("", "test.json", {
    "first\\.second": dict[str, int],
    "baz": list[int],
}).check())  # 打印：{'first': {'second': {'third': 111, 'foo': 222}}, 'baz': [444]}

try:
    requireConfig("", "test.json", {
        "first\\.second": dict[str, str]  # 类型不匹配
    }).check()
except ConfigDataTypeError as err:
    print(err)  # 打印：\.first\.second\.third -> \.third (3 / 3) Must be '<class 'str'>', Not '<class 'int'>'

try:
    requireConfig("", "test.json", {
        "baz": list[str]
    }).check()
except ConfigDataTypeError as err:
    print(err)  # 打印：\.baz\[0\] -> \[0\] (2 / 2) Must be '<class 'str'>', Not '<class 'int'>'

# 默认值，路径不存在时自动填充
print(requireConfig("", "test.json", {
    "first\\.second\\.third": 999,  # 因为路径已存在所以不会填充
    "not\\.exists": 987
}).check())  # 打印： {'first': {'second': {'third': 111}}, 'not': {'exists': 987}}

# 在提供默认值的同时提供类型检查
# 一般情况下用不着，因为会自动根据默认值的类型来设置类型检查
# 一般在传入的默认值类型与类型检查的类型不同或规避特殊语法时使用
print(requireConfig("", "test.json", {
    "first\\.second\\.third": FieldDefinition(int, 999),
    "not\\.exists": FieldDefinition(int, 987),
    "baz": FieldDefinition(Sequence[int], [654]),
}).check())  # 打印：{'first': {'second': {'third': 111}}, 'not': {'exists': 987}, 'baz': [444]}
print(requireConfig("", "test.json", {
    "first\\.second": FieldDefinition(dict, {"key": int}, allow_recursive=False),  # 并不会被递归处理，会被当作默认值处理
    "not exists": FieldDefinition(dict, {"key": int}, allow_recursive=False),
    "type": FieldDefinition(type, frozenset),
}).check())
# 打印：
#  {'first': {'second': {'third': 111, 'foo': 222}}, 'not exists': {'key': <class 'int'>}, 'type': <class 'frozenset'>}

# 含有非字符串键的子Mapping不会被递归处理
print(requireConfig("", "test.json", {
    "first\\.second": {"third": str, 3: 4},
    # 效果等同于FieldDefinition(dict, {"third": str, 3: 4}, allow_recursive=False)
    "not exists": {1: 2},
}).check())  # 打印：{'first': {'second': {'third': 111, 'foo': 222}}, 'not exists': {'key': <class 'int'>}}

几个关键字参数

关键字参数

from c41811.config import MappingConfigData
from c41811.config import ConfigFile
from c41811.config import JsonSL
from c41811.config import requireConfig
from c41811.config import save
from c41811.config.errors import RequiredPathNotFoundError

JsonSL().register_to()

raw_data = MappingConfigData({
    "first": {
        "second": {
            "third": 111,
            "foo": 222
        },
        "bar": 333
    },
    "baz": [444]
})

save("", "test.json", config=ConfigFile(raw_data))

# allow_modify, 在填充默认值时将默认值填充到源数据
requireConfig("", "test.json", {
    "not\\.exists": 987
}).check(allow_modify=False)

# 未提供allow_modify参数时不会影响源数据
print(raw_data.exists("not\\.exists"))  # 打印：False

# ConfigRequirementDecorator.__init__将allow_modify默认值设为True
requireConfig("", "test.json", {
    "not\\.exists": 987
}).check()

print(raw_data.exists("not\\.exists"))  # 打印：True
raw_data.delete("not\\.exists")

# skip_missing, 在没提供默认值且键不存在时忽略
try:
    requireConfig("", "test.json", {
        "not\\.exists": int
    }).check()
except RequiredPathNotFoundError as err:
    print(err)  # 打印：\.not\.exists -> \.exists (2 / 2) Operate: Read

data: MappingConfigData = requireConfig("", "test.json", {
    "not\\.exists": int
}).check(skip_missing=True)

print(data.exists("not\\.exists"))  # 打印：False

参见

DefaultValidatorFactory

自定义验证器

validator_factory 参数设为 CUSTOM 或 "custom" 时采用该策略

这将直接把 validator 参数当作验证器 Callable[[Ref[D], ValidatorOptions], D] 来使用，如果 validator 为 None 则验证器默认为 lambda ref:ref.value ，即无验证

一个修改所有值为"modified!"的验证器

from copy import deepcopy
from typing import Any

from c41811.config import ConfigFile
from c41811.config import JsonSL
from c41811.config import MappingConfigData
from c41811.config import ValidatorOptions
from c41811.config import requireConfig
from c41811.config import save
from c41811.config.utils import Ref


def modify_value_validator[D: MappingConfigData[Any]](ref: Ref[D], cfg: ValidatorOptions) -> D:
    data = deepcopy(ref.value)
    for path in data.keys(recursive=True, end_point_only=True):
        data.modify(path, "modified!")
    if cfg.allow_modify:
        ref.value = data
    return data


JsonSL().register_to()

save("", "test.json", config=ConfigFile(MappingConfigData({
    "key": "value"
})))
print(requireConfig("", "test.json", modify_value_validator, "custom").check())
# 输出：{'key': 'modified!'}

组件验证工厂

validator_factory 参数设为 COMPONENT 或 "component" 时使用该验证工厂

validator 参数为 Mapping[str | None, Any]

键为组件成员文件名，值为成员对应的验证器，组件成员文件名为None则为元配置信息验证器

危险

永远不应该尝试验证 NoneConfigData ，这将创建一个 parser 为 None 的 ComponentMeta，如果你没有在 额外验证器选项 传入默认的 组件元数据验证器 这将可能导致(至少目前默认情况下会)无法将组件元配置同步到组件元信息，最终导致元信息和组件成员不匹配抛出错误

参见

ComponentValidatorFactory

ConfigDataFactory

此类本身不提供任何实际配置数据操作，仅根据传入的参数类型从注册表中选择对应的类实例化并返回

注册表存储在 TYPES

传入的数据类型及其对应类

优先级从上倒下，取初始化参数的第一个参数的类型进行判断，未传入参数时取 None

数据类型	配置数据类
ABCConfigData	原样返回
types.NoneType	NoneConfigData
Mapping	MappingConfigData
str , bytes	StringConfigData
Sequence	SequenceConfigData
bool	BoolConfigData
numbers.Number	NumberConfigData
object	ObjectConfigData

备注

是的， ComponentConfigData 不在这里面，仅由 componentSL 或 ComponentValidatorFactory 创建

参见

具体原因与 组件验证工厂 所述大同小异

若希望作为类型提示请考虑下表

配置数据类型	描述
ABCConfigData	所有配置数据的抽象基类，仅提供了最基础的 freeze() from_data() 等方法
ABCIndexedConfigData	支持复杂嵌套数据的抽象基类，提供了 retrieve() modify() 等高级嵌套数据访问方法
BasicSingleConfigData	单文件配置数据的基类，提供的单文件配置数据的基本实现，如 data

NoneConfigData

无参数调用 ConfigDataFactory 的默认值，也是 initialize() 的默认返回值

初始化参数永远必须为 None 或压根不传，允许传参更大是为了兼容父类接口

MappingConfigData

最常见的配置数据类型，提供了 MutableMapping 的完整实现。

retrieve() 等高级方法当返回值为 Mapping 或 Sequence 时， retrieve() 会返回 MappingConfigData 或 SequenceConfigData

SequenceConfigData

提供了 MutableSequence 的完整实现

retrieve() 等高级方法当返回值为 Mapping 或 Sequence 时， retrieve() 会返回 MappingConfigData 或 SequenceConfigData

StringConfigData

字符串与字节串的配置数据

尚未完整实现 UserString 的接口

NumberConfigData

提供了 numbers.Integral 与 numbers.Real 的大部分实现

BoolConfigData

继承自 NumberConfigData ，提供了 bool 的实现

ComponentConfigData

组件配置数据由元信息与成员配置组成

元信息

存储了 元配置 、 成员定义 、 处理顺序 、 解析器 几部分必须的值。

参见

ComponentMeta

元配置

元信息默认存储在 __meta__ 配置文件内，元配置就是 __meta__ 内的原始配置数据，文件名由 meta_file 指定

注意

原始配置数据结构完全由 解析器 定义，除非你能保证数据结构在你的预期内，否则不应该直接对其进行操作(不同 解析器 的实现可能使用完全不同的数据结构甚至数据类型！)

以 MappingConfigData 存储

成员定义

成员 文件名 ， 别名 ，及其 配置格式

文件名 应严格与 成员 一一对应

别名 可以在 处理顺序 中或 键元信息语法指定成员进行操作 中使用

配置格式 会在保存加载期间优先使用

参见

ComponentMember

处理顺序

retrieve() 等方法从成员的搜索顺序，参见下表：

顺序表	使用该表的方法
create	modify(), setdefault()
read	retrieve(), exists(), get(), setdefault()
update	modify()
delete	delete(), unset()

参见

ComponentOrders

解析器

负责将 元配置 与 元信息 以一定格式互相转换，由 parser 属性存储，可以在 ComponentSL() 中通过初始化方法的 meta_parser 参数指定

参见

默认实现： ComponentMetaParser 讲解： 元配置数据结构

成员

成员配置文件的配置数据，支持所有 ABCIndexedConfigData 的子类

键元信息语法指定成员进行操作

retrieve() 等方法支持使用 键元信息 指定成员进行操作

指定从成员member.json读取数据

comp_data.retrieve(r"\{member.json\}\.key")
# 如果有别名也可以使用别名
comp_data.retrieve(r"\{alies-member\}\.key")
# 如果成员为SequenceConfigData
comp_data.retrieve(r"\{member.json\}\[0\]")

具体来说，会读取 path[0].meta ，所以只有第一个键的元信息起到作用

EnvironmentConfigData

继承自 MappingConfigData ，内部维护了与初始化参数的键差异

参见

Difference

SL处理器

项目中的 SL 都是 SaveLoad 的缩写

配置格式	处理器	注册名	支持的文件后缀	简介
JSON	JsonSL	json	.json	基于内置 json 模块
HJSON	HJsonSL	hjson	.hjson	基于第三方库 hjson
Pickle	PickleSL	pickle	.pickle .pkl	基于内置 pickle 模块
YAML	PyYamlSL	yaml	.yaml .yml	基于第三方库 PyYAML
YAML	RuamelYamlSL	ruamel_yaml	.yaml .yml	基于第三方库 ruamel.yaml
TOML	RTomlSL	toml	.rtoml	基于第三方库 rtoml
TOML	TomlKitSL	tomlkit	.toml	基于第三方库 tomlkit
CBOR	CBOR2SL	cbor2	.cbor	基于第三方库 cbor2
Properties	JPropertiesSL	jproperties	.properties	基于第三方库 jproperties
Python	PythonSL	python	.py	基于 exec()，尝试保存会将配置数据作为 locals() 传入 ，建议与 plaintext 搭配使用
PythonLiteral	PythonLiteralSL	python_literal	.python_literal .pyl .py	基于 literal_eval() 与 pformat()
PlainText	PlainTextSL	plaintext	.md .markdown .rst .txt	纯文本格式，支持额外参数 linesep: str 在保存时额外添加换行符， split_line: bool 加载时使用 readlines()， remove_linesep: str 在加载时使用 str.removesuffix() 移除换行符
TarFile	TarFileSL	tarfile:$compression_shortname$	.tar .tar.$compression_shortname$ .tar.$compression_fullname$	基于内置 tarfile 模块
ZipFile	ZipFileSL	zipfile:$compression_shortname$-$compress_level$	.$compress_level$.zip .zip .$compress_level$.$compression_fullname$ .$compress_level$.$compression_shortname$ .$compression_shortname$ .$compression_fullname$	基于内置 zipfile 模块
Component	ComponentSL	component	.component .comp	组合多个 ABCIndexedConfigData 为一个 ComponentConfigData
OSEnv	OSEnvSL	os.environ	.os.env .os.environ	基于内置 os.environ

ComponentMetaParser

ComponentSL 的默认 元配置 解析器。

元配置数据结构

详解

{
    "members": [  # 声明组件成员，此处声明的文件名必须与提供的组件成员严格匹配
        "filename.json",  # 可以直接提供文件名
        {
            "filename": "name",  # 也可以通过键值对声明
            # 通过键值对声明可以附带额外信息
            "alias": "na",  # 此成员别名为"na"，可被`键元信息`语法或下面的操作顺序使用
            "config_format": "ruamel_yaml",  # 此成员配置格式为ruamel.yaml的YAML解析器
        },
        {"filename": "my-member.pickle"},  # 当然上面这些额外信息是可选的
    ],
    # 操作顺序，并没有严格的检查，已经声明的组件成员可以不被使用但是禁止出现完全重复的名称
    "order": [  # 定义基础的操作顺序，若未提供则顺序敏感地使用members所声明的文件名(若存在则优先使用别名)，可以提供一个空列表以禁用默认行为
        # "filename.json",  # 越靠前优先级越高
        # "na",  # 这里是允许别名的
        # 这里order为空以禁用默认行为(只要提供了此项就会禁用默认行为，无论是否完全为空列表或只填充了部分/全部成员)
    ],
    "orders": {  # order会被同步追加到orders的create/read/update/delete，所以orders优先级最高
        # 会简单的检查将要追加的名称是否已经在表中(如果是则跳过)，这并不会同时检查文件名与别名是否同时存在
        "create": [],  # 禁止创建新的键，此项目控制setdefault方法在路径不存在时的写入顺序与modify无法替换一个现有的数据时来创建数据
        "read": ["filename.json", "my-member.pickle"],  # retrieve等方法仅按照此顺序读取配置数据
        "update": ["filename.json", "na"],  # 显然这是针对modify一类方法替换现有数据的
        "delete": ["filename.json", "my-member.pickle", "na"],  # delete,unset一类涉及删除路径的操作
        # 注意，当unset等方法最终得到的orders其中某项为空时(例如"delete": [])
        # 会抛出RequiredPathNotFoundError且未找到路径一定为根键
    },
}  # 显然，以上的顺序表都是允许完全为空(且不必包含全部成员)的，这将导致永远无法通过普通的顺序查找检索到未在顺序表中成员，但是仍然可以通过`键元信息`语法指定成员访问