Pydantic V2如何让类型检查器识别字段验证器的输入类型？

要让类型检查器识别field_validator支持的多输入类型，同时保证字段最终类型为str，可以采用以下几种方案：

方案一：为模型__init__添加重载签名 #

通过@overload明确告知类型检查器模型实例化时允许的输入类型，既保留字段最终的str类型提示，又支持多类型输入：

from typing import Iterable, overload
from pydantic import BaseModel, field_validator

class Example(BaseModel):
    my_string: str
    
    @field_validator('my_string', mode='before')
    @classmethod
    def parse_my_string(cls, value: str | Iterable[str]) -> str:
        if isinstance(value, str):
            return value
        return ', '.join(value)

# 重载__init__方法，声明支持的输入类型
@overload
def Example(my_string: str) -> Example: ...
@overload
def Example(my_string: Iterable[str]) -> Example: ...

这样类型检查器会允许传入str或Iterable[str]，访问example.my_string时仍会提示为str类型。

方案二：联合类型字段+验证器+属性包装 #

将字段类型标注为支持的输入联合类型，通过验证器转换为str，再用属性包装提供准确的类型提示：

from typing import Iterable, cast
from pydantic import BaseModel, field_validator

class Example(BaseModel):
    my_string: str | Iterable[str]
    
    @field_validator('my_string')
    @classmethod
    def parse_to_str(cls, value: str | Iterable[str]) -> str:
        if isinstance(value, str):
            return value
        return ', '.join(value)
    
    @property
    def normalized_my_string(self) -> str:
        """确保返回str类型的字段值"""
        return cast(str, self.my_string)

实例化时可传入str或Iterable[str]，访问normalized_my_string时类型检查器会识别为str；直接访问my_string虽显示联合类型，但运行时已被转换为str。

方案三：Annotated+类型别名 #

使用Annotated关联验证器，同时通过类型别名告知类型检查器允许的输入类型：

from typing import Iterable, Annotated, TypeAlias
from pydantic import BaseModel, BeforeValidator

# 定义输入类型别名
MyStringInput: TypeAlias = str | Iterable[str]

def parse_my_string(value: MyStringInput) -> str:
    if isinstance(value, str):
        return value
    return ', '.join(value)

class Example(BaseModel):
    my_string: Annotated[str, BeforeValidator(parse_my_string)]

# 实例化时用类型别名标注输入
example = Example(my_string=MyStringInput(['A', 'B', 'C']))

主流类型检查器（如Pyright/Pylance）会识别这种标注，允许传入Iterable[str]，同时字段访问时保持str类型提示。

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