Pydantic空串转None最小改动方案及isinstance校验失败原因

问题背景 #

我拥有上百个定义Pydantic Schema的Python文件，现需将空字符串视为None，希望对所有文件的修改尽可能少。

已尝试的方案 #

创建了一个继承自str的类：

class ConstrainedStr(str):
    @classmethod
    def __get_validators__(cls):
        yield cls.validate

    @classmethod
    def validate(cls, v: str, field: Field) -> Optional[str]:
        v = v.strip()
        if v == "":
            return None
        return v

随后在所有Python文件中添加导入语句：

from package.module import ConstrainedStr as str

初看该方案有效，但后续遇到问题：在某用户文件中：

from package.module import ConstrainedStr as str

def validate(cls, value:str): # sample value 'asd'
    if isinstance(value, str):
        validation_rule()

此处的条件判断语句执行失败。

疑问 #

1. 有无无需大量修改的可行方案来实现需求？
2. 为何isinstance检查失败？ConstrainedStr继承自str，我的理解是否有误？

为理解问题2，做了进一步测试：

type(ConstrainedStr) 

返回type<class>；

type('123') 

返回type<str>。
查看builtins包可知str也是类，但type函数对str返回str，对ConstrainedStr返回class，由此产生疑问2。另一个测试示例：

class A(int):
    pass

isinstance(2, A)
# False

这也印证了疑问2。

问题2的原因解释 #

isinstance(value, str)检查失败的核心逻辑很明确：

• 你用from package.module import ConstrainedStr as str覆盖了当前文件作用域的str名称，此时代码里的str指的是自定义的ConstrainedStr类，而非Python内置的str。
• 示例中传入的value是原生字符串'asd'，它是内置str的实例，但不是ConstrainedStr的实例——就像你测试的isinstance(2, A)返回False一样：2是内置int的实例，不是自定义子类A的实例，自然通不过检查。

至于type函数的返回差异：所有自定义类的类型都是type，而内置str是Python底层实现的特殊类型，它既是type的实例，同时自身作为类型返回，这是内置类型的特性，和你的继承逻辑无关。

问题1的低改动方案 #

方案1：全局基础模型验证器（推荐） #

利用Pydantic的全局字段验证器，只需要修改基础模型类，所有子类自动生效：

from pydantic import BaseModel, field_validator
from typing import Any

class BaseSchema(BaseModel):
    @field_validator('*', mode='before')
    def convert_empty_str_to_none(cls, v: Any):
        if isinstance(v, str) and v.strip() == "":
            return None
        return v

把所有现有Pydantic模型的父类从BaseModel改成BaseSchema即可——如果原本就有统一的基础模型，只改这一个文件就行，改动量极小。

方案2：自定义类型不覆盖内置str #

保留你的ConstrainedStr类，但不要用as str导入，而是直接用它作为字段类型。用IDE的全局批量替换功能，把模型中所有str类型替换为ConstrainedStr，注意排除非Pydantic字段的场景即可。

也可以用Annotated结合验证器，更灵活：

from pydantic import BeforeValidator
from typing import Annotated, Optional

def empty_str_to_none(v: str) -> Optional[str]:
    stripped = v.strip()
    return None if stripped == "" else stripped

EmptyStrToNoneStr = Annotated[str, BeforeValidator(empty_str_to_none)]

同样用批量替换把模型中的str替换为EmptyStrToNoneStr，改动可控。

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