Pydantic（Pydantic）

Pydantic 是一个通过标准 Python 类型注解定义数据模型的数据验证库。 PyCharm 为 Pydantic 模型提供了专门支持，构建在与其他类型提示功能相同的类型引擎之上。

支持涵盖 pydantic.BaseModel 及其子类、 pydantic.dataclasses.dataclass 、泛型模型，以及相关构造，如 字段 、模型和字段验证器及 ConfigDict 选项。 PyCharm 同时识别 Pydantic v1 和 v2，但不会读取 v1 class Config 的选项，例如 allow_population_by_field_name。

模型字段的代码洞察

实例化 Pydantic 模型时，PyCharm 会将已声明的字段视为 __init__ 的关键字实参，并提供以下代码洞察：

字段名称作为关键字参数的补全，考虑它们的声明类型和默认值。
针对每个字段传递值时的类型检查，依据相应的注解进行。
用于高亮显示缺失的必填字段的检查。使用 Annotated[..., Field(...)] 声明且在 ＝ 后带有默认值的字段不是必需的。
支持从 __init__ 调用中的关键字实参导航到字段声明及返回，包括跨子类和基类。

            from pydantic import BaseModel

            class User(BaseModel):
                id: int
                name: str
                is_active: bool = True

            User(id=1, name="Alice")            # valid
            User(id="not-an-int", name="Steve") # type mismatch on id
            User(id=1)                          # name is missing
        
  

字段别名和验证配置

PyCharm 接受通过 Field(alias=...) 以别名声明的字段作为构造函数调用中的关键字实参，而不会给出错误的“unexpected argument”警告。

PyCharm 遵循模型配置，因此编辑器中的代码洞察与运行时验证行为一致。 PyCharm 从类关键字实参、 model_config 以及 config 实参或 pydantic.dataclasses.dataclass 的 __pydantic_config__ 读取选项。子类继承其基类的选项。

populate_by_name=True 或 validate_by_name=True ：PyCharm 除别名外还接受字段名称。
validate_by_alias=False ：PyCharm 仅接受字段名称。默认情况下，PyCharm 接受别名。

PyCharm 会在将 ConfigDict 选项作为关键字实参传递到模型的类头中时补全其名称，因此无需记住确切的选项名称。

当两个选项都启用时，PyCharm 接受字段名称及其别名作为关键字实参：

            from pydantic import BaseModel, Field

            class Model(BaseModel, validate_by_name=True, validate_by_alias=True):
                my_field: str = Field(alias='my_alias')

            Model(my_alias='foo')   # valid
            Model(my_field='foo')   # valid

PyCharm 会在常规注解中以及在 typing.Annotated 内部使用时识别 字段：

            from typing import Annotated
            from pydantic import BaseModel, Field

            class User(BaseModel):
                name: Annotated[str, Field(alias='alias_name')] = "Lucy"
                age: int = Field(alias='alias_age', default=20)
        
  

字段约束验证旎裨撪},{

PyCharm 会根据在 字段 上声明的基本约束检查传递给模型构造函数的字面量值，并在值不满足这些约束时报告警告。可识别以下约束：

min_length 和 max_length 用于字符串字段。
gt、 ge、 lt 和 le 用于数值字段。

            from pydantic import BaseModel, Field

            class User(BaseModel):
                name: str = Field(..., min_length=2, max_length=50)
                age: int = Field(..., gt=0, lt=120)
                price: float = Field(..., gt=0)

            User(name="J", age=150, price=0)   # name is too short, age is out of range, price must be greater than 0
        
  

通过 typing.Annotated 声明时，也会识别这些约束。

该检查由违反 Pydantic 字段约束检查执行。选择外部类型引擎时，它不会运行。

重构和验证器

重命名模型字段时，也会重命名模型的 __init__ 调用中的关键字实参。重命名这样的关键字实参时，也会重命名字段声明。

在 @field_validator、 @field_serializer 和旧版 @validator 中，PyCharm 会解析以字符串形式传递的字段名称：可以补全这些名称、导航到字段声明，并将字段与这些字符串一起重命名。

当 @field_validator、 @model_validator 或 @validator 与 @classmethod 组合使用时，装饰器嵌套存在问题检查不会报告它。

2026年 11月 3日

Pydantic​（Pydantic）

模型字段的代码洞察

字段别名和验证配置

字段约束验证旎裨撪},{

重构和验证器

Pydantic（Pydantic）