ConfZ – 基于Pydantic的配置管理

ConfZ是一个基于pydantic的Python配置管理库。它可以让你轻松地：

从配置文件、环境变量、命令行参数等加载配置
将加载的数据转换为所需格式并验证
以Python数据类似对象的方式访问结果，并获得完整的IDE支持

它还支持常见的用例，如：

多环境
单例模式和延迟加载
单元测试的配置更改
自定义配置源

更新：ConfZ 2已经发布，支持pydantic 2并改进了命名约定。查看迁移指南。

:package: 安装

ConfZ已发布在PyPI上，可以使用pip安装：

pip install confz

:rocket: 快速入门

使用ConfZ的第一步是声明你的配置类和源，例如在config.py中：

from confz import BaseConfig, FileSource
from pydantic import SecretStr, AnyUrl

class DBConfig(BaseConfig):
    user: str
    password: SecretStr

class APIConfig(BaseConfig):
    host: AnyUrl
    port: int
    db: DBConfig

    CONFIG_SOURCES = FileSource(file='/path/to/config.yml')

得益于pydantic，你可以使用多种字段类型和验证器。

从现在开始，在任何其他文件中，你都可以直接访问你的配置：

from config import APIConfig

print(f"API服务运行在 {APIConfig().host}，端口 {APIConfig().port}。")

如你所见，配置既不需要显式加载，也不需要全局实例化。ConfZ会在你第一次访问配置时，按照CONFIG_SOURCES中定义的方式自动加载。由于采用了单例机制，这只会发生一次，之后你会得到一个缓存的、不可变的实例，行为与其他_pydantic_实例相同。

assert APIConfig() is APIConfig()   # 由于单例机制，这是正确的
APIConfig().port = 1234             # 由于不可变性，这会引发错误
APIConfig().model_dump()            # 调用pydantic的方法获取字典表示

注意： 虽然配置的隐式和隐藏加载可能起初会让人感到惊讶，感觉有点像Python的魔法，但它可以帮你减少大量样板代码。你不需要显式加载配置，然后将其传递给所有需要它的代码层，而是可以通过导入配置类并直接访问例如APIConfig().db.user来从任何地方访问它。

显式加载

在某些情况下，配置不应该是全局单例，而应该显式加载并在本地传递。可以在构造函数中直接定义源，而不是将CONFIG_SOURCES定义为类变量：

from confz import BaseConfig, FileSource, EnvSource

class MyConfig(BaseConfig):
    number: int
    text: str

config1 = MyConfig(config_sources=FileSource(file='/path/to/config.yml'))
config2 = MyConfig(config_sources=EnvSource(prefix='CONF_', allow=['text']), number=1)
config3 = MyConfig(number=1, text='hello world')

如你所见，还可以提供额外的关键字参数。

注意： 如果既没有提供类变量CONFIG_SOURCES，也没有提供构造函数参数config_sources，BaseConfig的行为就像一个普通的_pydantic_类。

更改配置值

在某些情况下，你可能想要更改配置值，例如在单元测试中。但是，如果你设置了CONFIG_SOURCES类变量，这就不能直接进行。为了解决这个问题，每个配置类都提供了一个上下文管理器，可以临时更改你的配置：

from confz import BaseConfig, FileSource, DataSource

class MyConfig(BaseConfig):
    number: int
    CONFIG_SOURCES = FileSource(file="/path/to/config.yml")

print(MyConfig().number)                            # 将打印配置文件中的值

new_source = DataSource(data={'number': 42})
with MyConfig.change_config_sources(new_source):
    print(MyConfig().number)                        # 将打印'42'

print(MyConfig().number)                            # 将再次打印配置文件中的值

早期验证

默认情况下，你的配置会在你第一次实例化类时加载，例如通过MyConfig().attribute。这可以防止在导入配置类时产生副作用，如加载文件。如果配置类无法以正确格式填充所有必需字段，_pydantic_会在这一点上引发错误。为了确保这不会在不方便的时候发生，你也可以指示ConfZ提前加载所有配置：

from confz import validate_all_configs

if __name__ == '__main__':
    validate_all_configs()
    # 你的应用程序代码

函数validate_all_configs会实例化在你代码中任何（可达）位置定义的、设置了CONFIG_SOURCES的所有配置类。

:book: 文档

现在你已经看到了ConfZ可以使用的两种方式：使用类变量配置源，实现单例和延迟加载，或使用关键字参数配置源，允许直接加载配置值。在这两种情况下，从文件、命令行参数和环境变量定义配置源都非常灵活（而且可扩展），同时_pydantic_仍然确保一切最终符合你的期望。你还看到了如何在单元测试中临时更改配置，以及如何在代码早期验证单例配置类。

ConfZ完整功能的文档可以在readthedocs上找到。