Pydantic

pydantic settings

pydantic-settings 是一个用于管理 Python 应用配置的工具，它可以自动从环境变量或 .env 文件中读取配置，并提供严格的类型检查。

1. 安装

在使用前，需要安装 pydantic-settings 库：

pip install pydantic-settings

2. 核心用法：定义 Settings 类

所有的配置都需要定义在一个继承自 BaseSettings 的类中。

from pydantic_settings import BaseSettings
from pydantic import Field
class Settings(BaseSettings):
    # 1. 必填项 (没有默认值)
    # 如果环境变量或 .env 中没配 API_KEY，程序启动会直接报错
    api_key: str

    # 2. 选填项 (带有默认值)
    # 如果没配 HOST，默认使用 "127.0.0.1"
    host: str = "127.0.0.1"

    # 3. 类型自动转换
    # 即便环境变量传进来的是字符串 "8080"，也会自动转成整数
    port: int = 8080

    # 4. 使用 Field：起别名 (Alias) 和 默认值
    # 代码里叫 db_password，但去环境变量里找叫 DB_PASS 的值
    db_password: str = Field(alias="DB_PASS")
    # 既有别名，又有默认值
    timeout_sec: int = Field(default=30, alias="API_TIMEOUT")
    # 5. 配置去哪里读取数据 (Config)
    model_config = {
        "env_file": ".env",             # 指定读取同目录下的 .env 文件
        "env_file_encoding": "utf-8",   # 指定编码格式
        "extra": "ignore"               # 忽略 .env 中多余的配置项，不报错
    }

    # 全局单例
    # 整个项目（比如在另外的 vector_store.py 文件中）
    # 只需要执行 from config import settings
    # 然后调用 settings.zai_api_key，就可以随时拿到配置了
    # 不用每次都去读一遍文件，这被称为“单例模式”。
    settings = Settings()

3. .env 文件长什么样？

在你的项目根目录下创建一个名为 .env 的文件（不需要带其它后缀），内容如下：

# 对应 api_key (Pydantic 默认大小写不敏感，写 API_KEY 也能匹配上)
API_KEY=sk-xxxxxx123456
# 对应 db_password，因为设定了 alias
DB_PASS=mySecretPassword
# 覆盖掉默认的 timeout_sec
API_TIMEOUT=60

4. 如何在代码中使用它？

通常我们会把配置类实例化为一个全局唯一的对象（单例模式），然后在其它文件直接引入使用。

# 实例化配置（此时会自动读取 .env 和 环境变量，并进行类型检查）
settings = Settings()
# 使用配置，享受到 IDE 的代码提示和自动补全！
print(settings.api_key)       # 输出: sk-xxxxxx123456
print(settings.host)          # 输出: 127.0.0.1 (使用的是默认值)
print(settings.db_password)   # 输出: mySecretPassword
print(settings.timeout_sec)   # 输出: 60 (覆盖了默认值 30)