如何使用Pydantic实现自定义约束？以3位数字字符串验证为例

问题描述 #

希望使用Pydantic强制执行自定义约束：验证输入为仅包含数字且长度恰好为3的字符串，对应验证函数如下：

def valid(x): 
   if type(x) != str: 
      return False 
   else: 
      return x.isnumeric() and len(x)==3

询问是否可直接实现该约束，若不可行能否通过链式调用Pydantic其他方法实现。

直接实现自定义约束 #

完全可以直接实现，有两种常用方式：

方式一：字段验证器 #

直接把验证逻辑写到字段验证器里，简单直接：

from pydantic import BaseModel, field_validator

class MyModel(BaseModel):
    code: str

    @field_validator('code')
    def check_three_digit_str(cls, value):
        if not isinstance(value, str):
            raise ValueError('输入必须是字符串类型')
        if not value.isnumeric() or len(value) != 3:
            raise ValueError('输入必须是长度为3的纯数字字符串')
        return value

方式二：自定义可复用类型 #

如果这个约束要用到多个字段，可以封装成自定义类型，复用性更强：

from pydantic import GetCoreSchemaHandler
from pydantic_core import core_schema
from typing import Any

class ThreeDigitStr(str):
    @classmethod
    def __get_pydantic_core_schema__(cls, source_type: Any, handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
        # 基于字符串类型添加自定义验证
        return core_schema.no_info_wrap_validator_function(
            cls.validate,
            core_schema.str_schema(),
        )

    @classmethod
    def validate(cls, value: Any) -> str:
        if not isinstance(value, str):
            raise ValueError('必须是字符串')
        if not value.isnumeric() or len(value) != 3:
            raise ValueError('必须是长度为3的纯数字字符串')
        return cls(value)

# 使用自定义类型
class MyModel(BaseModel):
    code: ThreeDigitStr

链式调用Pydantic内置约束实现 #

不用写自定义验证逻辑，直接组合Pydantic的内置约束也能实现：
针对Pydantic v2，可以用StringConstraints配合正则表达式和长度限制：

from pydantic import BaseModel, StringConstraints
from typing import Annotated

# 组合内置约束：长度固定3位，且匹配纯数字正则
ThreeDigitStr = Annotated[str, StringConstraints(min_length=3, max_length=3, pattern=r'^\d{3}$')]

class MyModel(BaseModel):
    code: ThreeDigitStr

这里min_length和max_length确保字符串长度恰好为3，pattern=r'^\d{3}$'保证内容是纯数字，两者组合完全满足你的约束要求。

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