Pydantic中ClassVar字段引发AttributeError错误，求解决方案

问题代码 #

from typing import ClassVar
from pydantic import BaseModel, Field


class IndexSchema(BaseModel):
    bodyKey: str = Field(..., description="Body Key in the data")


class Index(BaseModel):
    name: str = Field(..., description="Name of the index")
    schema: ClassVar[IndexSchema] = Field(..., description="schema of the data")

obj = Index(name="Rom",schema=IndexSchema(bodyKey="Rom is crazy"))
print(obj.name)
print(obj.schema.bodyKey)

错误信息 #

Rom
Traceback (most recent call last):
  File "/Users/rommonda/Desktop/Llama/test.py", line 15, in <module>
    print(obj.schema.bodyKey)
AttributeError: 'FieldInfo' object has no attribute 'bodyKey'

问题原因 #

1. ClassVar是类级别的变量，不属于实例属性，Pydantic不会对标记为ClassVar的字段做实例化解析。你在schema字段上同时使用Field，导致Pydantic将其保留为FieldInfo对象，而非你期望的IndexSchema实例。
2. 类变量应该直接在类级别赋值，你错误地在实例化Index时给ClassVar字段传值，这种操作不会给类变量赋值，反而会引发解析混乱。

解决方案 #

方案1：正确使用ClassVar（类级别变量）

去掉ClassVar字段上的Field（类变量不需要Pydantic的实例字段验证逻辑），直接在类级别赋值schema，访问时通过类名而非实例：

from typing import ClassVar
from pydantic import BaseModel, Field


class IndexSchema(BaseModel):
    bodyKey: str = Field(..., description="Body Key in the data")


class Index(BaseModel):
    name: str = Field(..., description="Name of the index")
    # 定义ClassVar类型的类变量，无需Field
    schema: ClassVar[IndexSchema]

# 在类级别赋值schema
Index.schema = IndexSchema(bodyKey="Rom is crazy")

obj = Index(name="Rom")
print(obj.name)
# 通过类名访问类变量
print(Index.schema.bodyKey)

方案2：改用实例字段（避免命名冲突）

如果需要每个实例拥有独立的schema属性，可将字段名改为data_schema（或其他不与BaseModel内置方法/属性冲突的名称），无需使用ClassVar：

from pydantic import BaseModel, Field


class IndexSchema(BaseModel):
    bodyKey: str = Field(..., description="Body Key in the data")


class Index(BaseModel):
    name: str = Field(..., description="Name of the index")
    data_schema: IndexSchema = Field(..., description="schema of the data")

obj = Index(name="Rom", data_schema=IndexSchema(bodyKey="Rom is crazy"))
print(obj.name)
print(obj.data_schema.bodyKey)

方案3：保留schema作为实例字段（处理命名冲突）

如果必须使用schema作为实例字段名，可通过Pydantic的别名配置避免与内置方法冲突（适用于Pydantic v2）：

from pydantic import BaseModel, Field, ConfigDict


class IndexSchema(BaseModel):
    bodyKey: str = Field(..., description="Body Key in the data")


class Index(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    name: str = Field(..., description="Name of the index")
    # 用alias定义字段别名，避免与内置schema方法冲突
    schema: IndexSchema = Field(..., alias="data_schema", description="schema of the data")

# 实例化时可以用别名或原字段名（因为开启了populate_by_name）
obj = Index(name="Rom", schema=IndexSchema(bodyKey="Rom is crazy"))
print(obj.name)
print(obj.schema.bodyKey)

内容的提问来源于stack exchange，提问作者Romit Mondal