Python第三方库介绍

PyYAML

PyYAML 是 Python 中用于处理 YAML（YAML Ain’t Markup Language）格式数据的最常用第三方库。YAML 是一种人类可读的数据序列化格式，常用于配置文件、数据交换等场景。

---

一、安装 PyYAML

pip install pyyaml

注意：虽然包名是 pyyaml，但在代码中导入时使用的是 yaml。

---

二、基本用法

1. 读取 YAML 文件（反序列化）

import yaml

# 从文件读取
with open('config.yaml', 'r', encoding='utf-8') as f:
    data = yaml.safe_load(f)

print(data)

2. 将 Python 对象写入 YAML 文件（序列化）

import yaml

data = {
    'name': 'Alice',
    'age': 30,
    'hobbies': ['reading', 'coding']
}

with open('output.yaml', 'w', encoding='utf-8') as f:
    yaml.dump(data, f, allow_unicode=True, default_flow_style=False)

• allow_unicode=True：支持中文等 Unicode 字符。
• default_flow_style=False：使用块状风格（更易读），而不是行内风格。

---

三、安全注意事项

⚠️ 不要使用 yaml.load()！

旧版本中 yaml.load() 存在安全风险（可能执行任意代码），应始终使用 yaml.safe_load() 来加载不受信任的 YAML 内容。

# ❌ 危险（除非你完全信任输入）
data = yaml.load(yaml_str)

# ✅ 安全
data = yaml.safe_load(yaml_str)

safe_load() 只支持标准 YAML 标签（如 !!str, !!int, !!list, !!dict 等），不会实例化任意 Python 对象。

---

四、常见应用场景

• 应用程序配置文件（如 Django、FastAPI、Ansible 等）
• CI/CD 流水线定义（如 GitHub Actions、GitLab CI）
• 数据导出/导入（比 JSON 更易编辑）

---

五、示例：YAML 文件内容

# config.yaml
database:
  host: localhost
  port: 5432
  username: admin
  password: secret

features:
  - auth
  - logging
  - cache

debug: true

对应的 Python 字典：

{
  'database': {
    'host': 'localhost',
    'port': 5432,
    'username': 'admin',
    'password': 'secret'
  },
  'features': ['auth', 'logging', 'cache'],
  'debug': True
}

---

六、示例：与.env搭配使用

实现功能

.env文件和 yaml 文件存在相同的配置时，使用 .env 文件覆盖 yaml 文件配置

yaml

BASIC_MODEL:
  base_url: xxx
  api_key: xxx
  model_name: xxx

.env

BASIC_MODEL_BASE_URL=xxx
BASIC_MODEL_API_KEY=xxx
BASIC_MODEL_MODEL_NAME=xxx

loader.py

import os
from typing import Any, Dict, Final

import dotenv
import yaml
from pathlib import Path

from src.config.agents import LLM_TYPE

__config_cache: Dict[str, Dict[str, Any]] = {}
_llm_config_suffix: Final[str] = "_MODEL"

def get_llm_config(llm_type: LLM_TYPE) -> Dict[str, str]:
    """
    获取llm配置
    """
    llm_config_name = f"{llm_type}{_llm_config_suffix}"

    # 加载yaml配置
    yaml_llm_config = {}
    yaml_config: dict[str, Any] = _load_yaml_config()
    for key, value in yaml_config.items():
        if llm_config_name == key:
            yaml_llm_config.update(value)
    # 加载env配置
    env_llm_config = _get_llm_config_by_env(llm_config_name)
    # 合并配置
    merge_config = {**yaml_llm_config, **env_llm_config}

    return merge_config

def _load_yaml_config(file_name: str = "application.yaml") -> Dict[str, Any]:
    """
    根据yaml文件名称加载yaml配置文件
    yaml文件必须放在根目录下
    """

    if file_name in __config_cache:
        return __config_cache.get(file_name)
    # 约定：配置文件必须放在根目录下
    file_path = Path(__file__).parent.parent.parent.resolve() / file_name

    config_file = Path(file_path)
    if not config_file.is_file():
        raise FileNotFoundError(f"配置文件未找到: {config_file}")

    try:
        with config_file.open('r', encoding='utf-8') as f:
            __config_cache[file_name] = yaml.safe_load(f) or {}
            return __config_cache[file_name]
    except yaml.YAMLError as e:
        raise ValueError(f"YAML 格式错误: {e}")

def _get_llm_config_by_env(llm_config_name_prefix: str) -> Dict[str, str]:
    """从env文件中获取llm配置"""
    conf: Dict[str, str] = {}
    for key, value in os.environ.items():
        if key.startswith(llm_config_name_prefix):
            conf[key[len(llm_config_name_prefix) + 1:].lower()] = value
    return conf

if __name__ == '__main__':
    dotenv.load_dotenv()
    print(get_llm_config("BASIC"))

---

Pydantic 是一个用于 Python 的数据验证和设置管理库，它使用 Python 类型提示（type hints）来自动进行数据校验、序列化和反序列化。Pydantic 广泛用于 FastAPI、Django REST Framework 等现代 Web 框架中，因其简洁、高效、类型安全而广受欢迎。

---

Pydantic

官方文档

一、安装

pip install pydantic

注意：Pydantic v2 与 v1 有不兼容的 API 变更。以下内容基于 Pydantic v2（截至 2026 年主流版本）。

---

二、核心概念

• BaseModel：所有 Pydantic 模型的基类。
• 字段（Field）：模型中的属性，可添加验证规则。
• 验证器（Validator）：自定义验证逻辑。
• 序列化/反序列化：自动将字典、JSON 转为模型对象，反之亦然。
• 类型提示驱动：利用 typing 模块（如 List[str], Optional[int]）进行静态和运行时校验。

---

三、基本用法

1. 定义模型

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    email: str
    is_active: bool = True  # 默认值

# 创建实例（自动验证）
user = User(id=1, name="Alice", email="alice@example.com")
print(user)
# 输出: id=1 name='Alice' email='alice@example.com' is_active=True

2. 从字典或 JSON 创建模型

data = {"id": 2, "name": "Bob", "email": "bob@example.com"}
user = User.model_validate(data)  # Pydantic v2 推荐方法（替代 v1 的 parse_obj）

# 从 JSON 字符串
import json
json_str = '{"id": 3, "name": "Charlie", "email": "charlie@example.com"}'
user = User.model_validate_json(json_str)

3. 导出为字典或 JSON

user_dict = user.model_dump()          # 字典
user_json = user.model_dump_json()     # JSON 字符串

---

四、字段约束与验证

使用 Field 添加元数据和约束

from pydantic import BaseModel, Field, EmailStr
from typing import Optional

class User(BaseModel):
    id: int = Field(gt=0, description="用户ID必须大于0")
    name: str = Field(min_length=2, max_length=50)
    email: EmailStr  # 需要安装 email-validator: pip install email-validator
    age: Optional[int] = Field(default=None, ge=0, le=150)

# 测试
try:
    User(id=-1, name="A", email="invalid-email")
except Exception as e:
    print(e)

注意：EmailStr 在 v2 中需额外安装 email-validator。

---

五、嵌套模型

from typing import List

class Address(BaseModel):
    city: str
    country: str

class User(BaseModel):
    name: str
    addresses: List[Address]

data = {
    "name": "David",
    "addresses": [
        {"city": "Beijing", "country": "China"},
        {"city": "Shanghai", "country": "China"}
    ]
}
user = User.model_validate(data)
print(user.addresses[0].city)  # Beijing

---

六、自定义验证器（Validators）

字段级验证（field_validator）

from pydantic import field_validator

class User(BaseModel):
    name: str

    @field_validator('name')
    @classmethod
    def name_must_not_be_empty(cls, v):
        if not v.strip():
            raise ValueError('名称不能为空')
        return v.title()  # 自动首字母大写

user = User(name=" alice ")
print(user.name)  # Alice

模型级验证（model_validator）

from pydantic import model_validator

class UserModel(BaseModel):
    password: str
    confirm_password: str

    @model_validator(mode='after')
    def check_passwords_match(self):
        if self.password != self.confirm_password:
            raise ValueError('Passwords do not match')
        return self

# 使用
user = UserModel(password="123456", confirm_password="123456")
# UserModel(password="123", confirm_password="456") 会报错

---

七、处理可选字段与默认值

from typing import Optional
from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float = Field(default=0.0, gt=0)

item = Item(name="Book")
print(item.description)  # None

---

八、别名（Alias）

class User(BaseModel):
    user_id: int = Field(alias='userId')
    full_name: str = Field(alias='fullName')

# 输入使用别名
data = {"userId": 123, "fullName": "Eve"}
user = User.model_validate(data)

# 输出默认使用字段名
print(user.user_id)  # 123

# 若希望输出也用别名：
print(user.model_dump(by_alias=True))  # {'userId': 123, 'fullName': 'Eve'}

---

九、配置项（ConfigDict）

from pydantic import ConfigDict

class User(BaseModel):
    model_config = ConfigDict(
        extra='forbid',           # 禁止传入未定义字段
        str_strip_whitespace=True,
        str_to_lower=True
    )
    name: str

# User(name=" ALICE ", extra_field="x")  # 报错：extra fields not permitted

常用配置：

• extra: 'allow' | 'ignore' | 'forbid'
• str_strip_whitespace: 自动去除字符串首尾空格
• validate_assignment: 开启后对属性赋值也进行验证

---

十、与 FastAPI 集成示例（简略）

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
def create_item(item: Item):
    return {"item": item.model_dump()}

---

十一、常见数据类型支持

Pydantic 支持丰富的类型：

• 基础类型：int, float, str, bool
• 容器：List, Dict, Set, Tuple
• 日期时间：datetime, date, time
• URL、Email、UUID、IPv4Address 等
• 枚举（Enum）
• 自定义类型（通过 __get_validators__ 或 Annotated）

---

十二、性能

• Pydantic 使用 Rust 编写的底层库（如 pydantic-core）提升性能。
• 验证速度远快于手写校验逻辑。

---

总结

Pydantic 的优势：

✅ 类型安全
✅ 自动验证
✅ 清晰的错误信息
✅ 与现代 Python 工具链无缝集成
✅ 支持复杂嵌套结构和自定义逻辑

适合用于：

• API 请求/响应模型
• 配置文件解析
• 数据清洗与转换
• 数据库 ORM 的中间层（如配合 SQLAlchemy）

---