使用 Pydantic 验证 Python 数据

​

简介

• 本文将引导你完成使用 pydantic 进行数据验证的过程。Pydantic 是一个 Python 库，其验证核心（pydantic-core）用 Rust 编写。示例使用 pydantic v2。
• 在开始之前，请确保你的环境中已安装 Python 和 pydantic 库。请查看下面的 pydantic 安装命令。

pip install pydantic

​

创建模型

• 首先，我们需要导入并让我们的类继承自 pydantic.BaseModel 以开始验证。在我们的示例中，我们将创建一个名为 Person 的类，它将包含姓名、年龄和一个电子邮件。

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int
    email: str

• 有了这个类，当我们实例化它时，pydantic 将验证 name 和 email 是否为字符串，以及 age 是否为整数。

​

使用模型

• 现在我们已经创建了它，接下来我们将实例化该类。我们将创建一个包含数据的字典，并将其解包传入我们的类。

data = {
    "name": "John",
    "age": 19,
    "email": "john@example.com"
}
person = Person(**data)

• 上面的示例不会引发任何错误，因为所有字段的类型都正确。默认情况下，pydantic 还会转换兼容的值：如果 age 是字符串 "19"，它会变成整数 19。现在我们将传入错误的数据，以确认我们的验证是否生效。

data = {
    "name": "John",
    "age": "nineteen",
    "email": "john@example.com"
}
person = Person(**data)

• 上面的示例会引发 ValidationError，因为 age 需要是整数，而 "nineteen" 无法转换为整数：

1 validation error for Person
age
  Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='nineteen', input_type=str]

• 如果想处理这个错误，而不是让它中断程序，请用 try/except 捕获它。它的 errors() 方法会列出每个无效字段：

from pydantic import ValidationError

try:
    Person(name="John", age="nineteen", email="john@example.com")
except ValidationError as error:
    for item in error.errors():
        print(item["loc"], item["msg"])
# ('age',) Input should be a valid integer, unable to parse string as an integer

​

严格模式

• 如果你也想拒绝 "19" 这样的字符串，请在模型中启用严格模式。这样 age 只接受真正的 int，Person(name="John", age="19", email="john@example.com") 会引发 ValidationError。

from pydantic import BaseModel, ConfigDict

class Person(BaseModel):
    model_config = ConfigDict(strict=True)

    name: str
    age: int
    email: str

​

创建 dataclass

• 你也可以使用 pydantic 创建 dataclass。它们与标准的 Python dataclass 类似，但会像 BaseModel 一样验证字段。

from pydantic.dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int
    email: str

• 如果我们向 age 发送字符串 "19"，它将被转换为 int 类型的 19。

​

附加内容

• Pydantic 有一些附加功能，例如电子邮件验证和一个后备的时区包。要安装它们，请运行以下命令：

pip install "pydantic[email]"

pip install "pydantic[timezone]"

• 你可以通过运行以下命令将两者一起安装。

pip install "pydantic[email,timezone]"

• pydantic[email] 添加了 EmailStr 类型，它会验证 user@domain.tld 格式并规范化地址。

from pydantic import EmailStr
from pydantic.dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int
    email: EmailStr

​

在启动时验证环境变量

• 机器人和 API 会从环境变量中读取令牌和设置。使用 pydantic-settings 时，缺失或无效的变量会让应用在启动时就以清晰的错误停止，而不是在之后处理请求的过程中失败。

pip install pydantic-settings

• 在一个继承自 BaseSettings 的类中声明应用所需的变量。每个字段都会读取同名的环境变量（不区分大小写）：discord_token 读取 DISCORD_TOKEN。

from pydantic import SecretStr
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    discord_token: SecretStr  # required: the application doesn't start without it
    port: int = 80  # optional: 80 when PORT isn't set
    debug: bool = False


settings = Settings()

• 如果没有设置 DISCORD_TOKEN，Settings() 会为 discord_token 引发 ValidationError，消息为 Field required。像 PORT=abc 这样的值也会以同样的方式失败，因为 port 必须是整数。
• SecretStr 会在你打印或记录设置时隐藏令牌。请使用 settings.discord_token.get_secret_value() 读取真实值。
• 在 Square Cloud 上，请在控制面板中或使用 squarecloud app env set 设置这些变量，并在你的 requirements.txt 中列出 pydantic-settings。请参阅环境变量。

​

后续步骤

​

你喜欢这篇文章吗？

• 我们精心创作了这些内容，只为提供尽可能好的帮助。 如果这篇文章对你有任何帮助，请支持我们的工作！已经有开发者在 Google 和 Trustpilot 上给 Square Cloud 打出了 4.9/5 分（共 402 条评价），也留下你的评价吧！这能帮助我们了解什么对你最重要。