如何在Pydantic V2 BaseModel中序列化Polars DataFrame类型？

方案一：针对单个字段定制处理 #

直接在模型类中使用@field_serializer（序列化）和@field_validator（反序列化）装饰器，指定目标字段即可：

from typing import Any
from pydantic import BaseModel, field_serializer, field_validator
import polars as pl
import json

def json_serializable_dataframe(df: pl.DataFrame) -> dict[str, Any]:
    return json.loads(df.write_json())

def dataframe_from_dict(df_dict: dict[str, Any]) -> pl.DataFrame:
    # 将字典转回JSON字符串后用Polars读取
    return pl.read_json(json.dumps(df_dict))

class Foo(BaseModel, arbitrary_types_allowed=True):
    df: pl.DataFrame = pl.DataFrame({"foo":[1,2,3], "bar":[4,5,6]})

    @field_serializer('df')
    def serialize_df(self, df: pl.DataFrame) -> dict[str, Any]:
        return json_serializable_dataframe(df)

    @field_validator('df', mode='before')
    def deserialize_df(cls, value: dict[str, Any]) -> pl.DataFrame:
        # mode='before'表示在类型校验前处理原始输入（JSON解析后的字典）
        return dataframe_from_dict(value)

# 测试序列化
foo_instance = Foo()
json_output = foo_instance.model_dump_json(indent=2)
print("序列化结果：")
print(json_output)

# 测试反序列化
foo_new = Foo.model_validate_json(json_output)
print("\n反序列化后的DataFrame：")
print(foo_new.df)

方案二：全局通用处理（所有Polars DataFrame字段自动生效） #

如果需要多个模型共享Polars DataFrame的序列化规则，可以通过注解类型+全局配置实现：

from typing import Any
from pydantic import BaseModel, BeforeValidator, Annotated
import polars as pl
import json

# 定义序列化/反序列化工具函数
def json_serializable_dataframe(df: pl.DataFrame) -> dict[str, Any]:
    return json.loads(df.write_json())

def dataframe_from_dict(df_dict: dict[str, Any]) -> pl.DataFrame:
    return pl.read_json(json.dumps(df_dict))

# 定义带校验规则的注解类型
PolarsDataFrame = Annotated[pl.DataFrame, BeforeValidator(dataframe_from_dict)]

class Foo(BaseModel):
    df: PolarsDataFrame = pl.DataFrame({"foo":[1,2,3], "bar":[4,5,6]})

    model_config = {
        "arbitrary_types_allowed": True,
        "json_encoders": {
            pl.DataFrame: json_serializable_dataframe
        }
    }

# 测试功能
foo_instance = Foo()
json_str = foo_instance.model_dump_json(indent=2)
print(json_str)

foo_deserialized = Foo.model_validate_json(json_str)
print(foo_deserialized.df)

关键说明 #

• arbitrary_types_allowed=True：必须开启，允许Pydantic处理Polars DataFrame这类非标准类型
• @field_serializer('df')：指定对df字段进行序列化，将DataFrame转为可JSON序列化的字典
• @field_validator('df', mode='before')：mode='before'确保在Pydantic进行类型校验前，先将JSON解析后的字典转回Polars DataFrame
• 全局方案中的json_encoders：配置后，所有模型中pl.DataFrame类型的字段都会自动使用指定的序列化函数

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