pydantic 库（Python 数据接口定义）基本使用指南

痛定思痛。 2024-02-20 12:29 72阅读 0赞

## pydantic 概述 ##

pydantic 库是 python 中用于数据接口定义检查与设置管理的库。

pydantic 在运行时强制执行类型提示，并在数据无效时提供友好的错误。

具有如下优点：

*  易于使用： Pydantic 很容易安装与使用，并且有一个简单的 API，使得所有开发者都可以快速上手使用。
 *  快速验证： Pydantic 快速有效地执行数据验证，使其适合于在高性能的应用程序中使用。
 *  自动生成文档： Pydantic 可以为数据模型自动生成文档，节省时间，并且更容易的理解数据结构。
 *  类型提示支持： Pydantic 支持类型提示，使开发人员更容易定义数据结构，避免在代码中出现错误。
 *  与 FastAPI 集成： Pydantic 可以很容易地与 FastAPI（一个高性能的 Python 网络框架）集成，为 API 提供自动请求和响应验证。
 *  自定义验证规则： Pydantic 允许开发人员定义自定义的验证规则，使得在需要的时候可以实现复杂的验证逻辑。
 *  一致的数据： Pydantic 确保项目中使用的数据是一致的，并符合所需的标准，减少了错误的风险，使代码库的维护更加容易。
 *  与 IDE/linter 完美搭配，不需要学习新的模式，只是使用类型注解定义类的实例
 *  多用途，BaseSettings 既可以验证请求数据，也可以从环境变量中读取系统设置
 *  可扩展，可以使用 validator 装饰器装饰的模型上的方法来扩展验证
 *  数据类集成，dataclass 装饰器可以创建带有输入数据解析和验证的普通 Python 数据类。

**Pydantic 的工作方式**

*  Pydantic 的工作方式是允许开发人员使用 Python 类来定义数据模型。这些类继承自 Pydantic 提供的 BaseModel 类，可以包括类型提示、默认值和验证规则。当收到数据时，Pydantic 使用数据模型来验证传入的数据，并确保其符合所定义的要求。
 *  在验证过程中，Pydantic 对照数据模型中定义的类型提示和验证规则，检查数据中的每个字段。如果数据不符合要求，Pydantic 会提出一个错误，并停止验证过程。如果数据是有效的，Pydantic 就会创建一个数据模型的实例，用传入的数据来填充它，并将其返回给用户。
 *  Pydantic 还提供了一些高级功能，例如字段别名，自定义验证函数，以及对嵌套数据模型的支持，使得它可以处理广泛的数据验证场景。此外，Pydantic 支持序列化和反序列化，允许根据需要将数据转换为 Python 数据结构、JSON 和其他格式。

## 环境准备 ##

*  安装 pydantic 命令：`pip install pydantic`
 *  测试 pydantic 是否已编译
    
        import pydantic
        print('compiled:', pydantic.compiled)

## BaseModel（基本模型） ##

### 简述 ###

在 Pydantic 中，`BaseModel` 是一个用于定义数据模型的基类。它允许创建一个描述数据结构、验证数据和进行数据转换的类。`BaseModel` 基本模型提供了属性和方法来定义字段，校验数据以及序列化数据。

`BaseModel` 提供的常用功能有：

*  **数据验证**：当创建模型实例时，Pydantic 会自动验证传入的数据是否满足字段定义的规则。
 *  **数据转换**：Pydantic 会尝试将输入数据转换为模型中定义的字段类型，例如将字符串转换为整数或浮点数。
 *  **自动文档生成**：基于模型的字段定义，Pydantic 可以自动生成文档和模型验证的错误消息。
 *  **嵌套模型**：可以在模型内部使用其他模型，从而创建复杂的数据结构。
 *  **序列化和反序列化**：允许根据需要将数据转换为 Python 数据结构、JSON 和其他格式。

### pydantic 和 @dataclass 的异同 ###

pydantic 和 @dataclass 都是用于创建数据类（data class）的工具，它们有一些相似之处，但也有一些重要的区别。

*  **@dataclass**：
    
     *  `@dataclass` 是 Python 标准库中的一个装饰器，自 Python 3.7 引入。
     *  它用于创建数据类，可以轻松地定义类的属性，并自动生成常见的特殊方法，如 `__init__()`、`__repr__()`、`__eq__()` 等。
     *  `@dataclass` 不提供数据验证功能，仅用于数据类的创建。
     *  适用于简单的数据类，不涉及数据验证或输入的复杂处理逻辑。
 *  **pydantic**：
    
     *  `pydantic` 是一个用于数据验证和数据解析的 Python 库，它提供了强大的数据验证和输入处理功能。
     *  它允许定义模型类，为模型属性添加验证规则，以确保数据的有效性。
     *  `pydantic` 支持丰富的验证规则，包括类型检查、最小值、最大值、正则表达式匹配等。
     *  适用于需要数据验证和处理的场景，特别是用于处理输入数据、API 请求等情况。

**总结：**

*  如果只需要创建简单的数据类，并且不需要进行数据验证和处理，那么使用 `@dataclass` 是一个简单而方便的选择。
 *  如果需要对输入数据进行验证，确保数据的有效性，或者处理来自外部系统的复杂数据，那么 `pydantic` 更适合，因为它提供了更强大的数据验证和处理功能

### 定义 BaseModel 数据模型 ###

*  在 pydantic 中定义一个对象模型的主要方法是通过模型继承自 BaseModel 类，然后声明属性并显式地注解属性的数据类型。
 *  属性可以设置默认值，设置了默认值的属性在创建模型对象时可选传参数，否则为必传参数。
 *  支持的数据类型包括 `str`、`int`、`float`、`List` 等基本数据类型以及其他的 Pydantic 类型，如 `EmailStr`、`UrlStr`、`PositiveInt` 等，来增强字段的验证能力。
 *  **简单示例**
    
        from pydantic import BaseModel
        
        class User(BaseModel):
            id: int
            name: str = 'Jane Doe'
                
        # 创建对象，传参方式1
        user = User(id=1)
        
        # 创建对象，传参方式2
        item_data = {
              
            "id": 2,
            "name": 'aaa'
        }
        user_2 = User(**item_data)

### BaseModel 常用 API ###

**类属性：**

*  **`model_fields`**：它包含了模型中每个字段的 `FieldInfo` 对象，以字典的形式存储。`FieldInfo` 对象提供了有关字段的详细信息，如字段类型、默认值等。

**类方法：**

*  **`model_construct()`** ：允许在没有验证的情况下创建模型
 *  **`model_validate()`** ：用于使用 model 对象或字典创建模型的实例
 *  **`model_validate_json()`** ：用于使用 JSON 字符串创建模型的实例

**类对象方法：**

*  **`model_copy()`**：创建模型的一个副本。
 *  **`model_dump()`**：将模型转换为字典，其中包含字段名称和对应的值。
 *  **`model_dump_json()`**：将模型转换为 JSON 格式的字符串。

### @validator：自定义验证器 ###

*  **@validator** 装饰器用于在 Pydantic 的 BaseModel 子类中定义验证函数，以在模型创建时自动验证字段的值。
    
    使用 @validator 装饰器可以实现自定义验证和对象之间的复杂关系。
 *  **@validator 常用的参数和说明：**
    
     *  \***fields** （可变位置参数）：要验证的字段名称，可以是一个或多个字段。这些字段的值将作为验证函数的参数传递给验证函数。
        
        传参多个字段需配合 allow\_reuse 参数使用
     *  **allow\_reuse**（默认为 `False`）：如果设置为 `True`，则允许验证函数重复使用。
        
        如果多个字段需要相同的验证逻辑，可以将此参数设置为 `True` 以提高代码的复用性。
        
            @validator("age", "height", allow_reuse=True)
     *  **each\_item** （默认为 False）：设置验证器是否被施加到单独的值（例如 List，Dict，Set 等），而不是整个对象
     *  **pre**（默认为 False）：设置验证函数是在字段验证之前（`pre=True`）还是之后（`pre=False`）执行。
        
        通常情况下，会将其保留为默认值 False，以便在字段验证之后执行验证。
     *  **pre\_root**（默认为 False）：与 pre 参数一起使用，用于在整个模型层次结构中的字段验证之前或之后执行验证函数。
        
        通常情况下，会将其保留为默认值 False，以便在字段验证之后执行验证。
     *  **always**（默认为 False）：如果设置为 True，则无论字段是否在模型中被赋值，验证函数都会被执行。
        
        通常情况下，会将其保留为默认值 False，以便只在字段被赋值时执行验证。
 *  **注意：**
    
     *  验证器是“类方法”，因此它们接收的第一个参数值是类（形参 cls），而不是对象（形参 self）
     *  第二个参数始终是要验证的字段值，可以随意命名，常用 v
     *  单个验证器可以通过传递多个字段名称来应用于多个字段，也可以通过传递特殊值在所有字段上调用单个验证器
 *  代码示例
    
        from pydantic import BaseModel, ValidationError, validator
        
        class UserModel(BaseModel):
            name: str
            names: List[str]
        
            @validator('name')
            def name_must_contain_space(cls, v):
                if ' ' not in v:
                    raise ValueError('must contain a space')
                return v.title()
            
            @validator('names', each_item=True)
            def check_names_not_empty(cls, v):
                assert v != '', 'Empty strings are not allowed.'
                return v

## BaseSettings：管理配置 ##

### BaseSettings 基类 ###

*  **BaseSettings** 是 Pydantic 提供的一个基类，用于管理应用程序的配置设置。
    
    它允许从环境变量、配置文件、命令行参数、Python 常量等多个来源加载配置选项，并进行验证和类型转换。
    
    BaseSettings 的目标是简化配置管理和设置的过程，使得应用程序的配置更加可靠和可维护。
 *  **基本使用**：创建一个继承自 **BaseSettings** 的模型，模型初始化程序将自动尝试通过从环境变量中读取，来确定未作为关键字参数传递的任何字段的值（如果未设置匹配的环境变量，则仍将使用默认值）
 *  **注意**：
    
     *  在 Pydantic 2.3.0 版本，BaseSettings 的导包路径为（`from pydantic.v1 import BaseSettings`），或使用独立的 pydantic-settings 包（安装命令：`pip install pydantic-settings`）

### BaseSettings 类的 Config 内部类 ###

*  在 Pydantic 的 `BaseSettings` 类中，`Config` 内部类提供了一些属性和配置选项，用于自定义配置的行为。
    
    可以在 `Config` 类中定义这些属性，以影响配置的加载和验证过程。
 *  常用的 `Config` 配置选项：
    
     *  **`env_file`**：指定配置文件（ Dotenv 文件）的名称。可以是文件名字符串，用于从指定的文件加载配置。
        
        pydantic 有两种方式加载它：
        
            class Settings(BaseSettings):
                ...
            
                class Config:
                    # 方式1：Settings.Config 类中直接设置默认值
                    env_file = '.env'
                    
            # 方式2：实例化BaseSettings子类对象时传参。注意内部类属性在类为传参时加一个下划线（_）
            settings = Settings(_env_file='prod.env')
        
        注意：
        
         *  使用该配置需要 python-dotenv 包的支持（安装命令：`pip install python-dotenv`）
         *  即使使用 dotenv 文件，pydantic 仍会读取环境变量，环境变量将始终优先于从 dotenv 文件加载的值。
     *  **`env_prefix`**：配置环境变量的前缀。设置前缀后，Pydantic 将只加载以该前缀开头的环境变量作为配置项。
     *  **`env_file_encoding`**：指定配置文件的编码。默认是 `"utf-8"`。
     *  **`case_sensitive`**：设置为 `True` 以启用字段名称的大小写敏感性，或设置为 `False` 以忽略大小写。默认是 `False`。
     *  **`arbitrary_types_allowed`**：设置为 `True` 以允许在配置文件中使用自定义类型。默认是 `False`。
     *  **`validate_all`**：是否验证所有字段，而不仅仅是被访问的字段。默认是 `True`。
     *  **`secrets_dir`**：设置敏感信息文件目录
        
        即使使用 secrets 目录，pydantic 仍会从 dotenv 文件或环境中读取环境变量，**环境变量和dotenv 文件将始终优先于从 secrets 目录加载的值**。
    
    这些是一些常用的 `Config` 配置选项，可以通过在 `Settings` 类中的 `Config` 子类中定义来自定义 `BaseSettings` 的行为。

### 代码示例 ###

*      #from pydantic import BaseSettings
        from pydantic.v1 import BaseSettings
        
        class Settings(BaseSettings):
            app_name: str = "My App"
            api_key: str
        
            class Config:
                env_file = ".env"  # 从环境文件加载配置
        
        settings = Settings()
    
     *  定义了一个名为 `Settings` 的 `BaseSettings` 子类。在这个类中，声明了两个配置选项：`app_name` 和 `api_key`。`app_name` 有一个默认值，而 `api_key` 则需要从配置中加载。
     *  `Config` 内部类用于配置 `BaseSettings` 的行为。在这个示例中，使用了 `env_file` 来指定从名为 `.env` 的环境文件中加载配置。
     *  通过创建 `Settings` 类的实例，可以轻松地访问配置选项，并自动进行验证和类型转换。如果 `api_key` 在配置文件中未设置或类型不匹配，Pydantic 将引发相应的异常。