آموزش کار با Pydantic V2 در پایتون (راهنمای جامع و کاربردی ۲۰۲۶)

کتابخانه Pydantic به عنوان ستون فقرات اعتبارسنجی داده، مدیریت تنظیمات و ساخت APIهای مدرن با FastAPI، با انتشار نسخه ۲ دستخوش یک بازطراحی بنیادین شد. هسته اعتبارسنجی در Pydantic V2 به طور کامل به زبان Rust (pydantic-core) بازنویسی شده است؛ این تغییر معماری سرعتی بین ۵ تا ۱۷ برابر بیشتر را نسبت به نسخه ۱ به همراه آورده و الگوهای تایپسیف و مدرنتری را در پایتون ۳ ارائه میدهد.
پاسخ کوتاه: پایدنتیک ۲ ابزار استاندارد اعتبارسنجی داده در پایتون مدرن است. در این نسخه متدهای قدیمی مانند .dict() با model_dump()، کلاس داخلی Config با دیکشنری تایپشده ConfigDict، و دکوراتورهای @validator با field_validator و model_validator جایگزین شدهاند.
چرا Pydantic V2 یک جهش بزرگ است؟
در نسخههای ۱.x پایدنتیک، تمام محاسبات اعتبارسنجی و سریالسازی توسط کدهای پایتون اجرا میشدند که در پردازش درخواستهای با حجم دیتای بالا یا فایلهای JSON بزرگ گلوگاه عملکردی ایجاد میکرد.
در Pydantic V2:
- هسته پرسرعت Rust: لایه پارسینگ و اعتبارسنجی بدون نیاز به درگیر کردن مفسر کند پایتون، با زبان Rust و به شکل صفر-اورهد اجرا میشود.
- پشتیبانی کامل از استانداردهای Typing پایتون: سازگاری عمیق با
typing.Annotated، انواع Union مدرن (|) و TypeAdapter. - حالت اعتبارسنجی سختگیرانه (Strict Mode): جلوگیری از تبدیلهای ناخواسته نوع داده (مانند تبدیل خودکار رشته
"123"به عدد صحیح123). - جداسازی دقیق Serialization از Validation: کنترل دقیق نحوه ذخیره، فیلتر یا تبدیل دادهها به JSON.
نصب و پیشنیازها
برای استفاده از نسخه ۲، پایتون ۳.۸ به بالا نیاز است:
pip install "pydantic>=2.0"
اگر از FastAPI استفاده میکنید، نسخههای اخیر FastAPI (از ۰.۱۰۰ به بعد) به طور کامل و بومی با Pydantic V2 سازگارند.
تغییرات کلیدی: مقایسه Pydantic V1 و V2
جدول زیر مهمترین تغییرات نحوی و مفهومی بین دو نسخه را خلاصه میکند:
| قابلیت | در Pydantic V1 (قدیمی) | در Pydantic V2 (مدرن ۲۰۲۶) |
|---|---|---|
| تبدیل مدل به دیکشنری | model.dict() | model.model_dump() |
| تبدیل مدل به JSON | model.json() | model.model_dump_json() |
| ساخت مدل از دیکشنری | Model.parse_obj(data) | Model.model_validate(data) |
| ساخت مدل از JSON خام | Model.parse_raw(json_str) | Model.model_validate_json(json_str) |
| تنظیمات پیکربندی مدل | class Config: درونی | model_config = ConfigDict(...) |
| اعتبارسنجی فیلد اختصاصی | @validator("field") | @field_validator("field") |
| اعتبارسنجی چندفیلدی | @root_validator | @model_validator(mode="after/before") |
پیادهسازی مدل داده پایه با Pydantic V2
کد زیر نحوه تعریف یک موجودیت کاربر با فیلدهای دارای ولیدیشن و متادیتا را نشان میدهد:
from datetime import datetime
from typing import Annotated
from pydantic import BaseModel, ConfigDict, EmailStr, Field
class UserProfile(BaseModel):
# تنظیمات مدل از طریق ConfigDict
model_config = ConfigDict(
str_strip_whitespace=True, # حذف فاصلههای اضافی رشتهها
extra="forbid", # رد درخواست در صورت ارسال فیلد اضافه
frozen=False,
)
id: int
username: Annotated[str, Field(min_length=3, max_length=30, pattern="^[a-zA-Z0-9_]+$")]
email: EmailStr
age: Annotated[int, Field(ge=18, le=100, description="سن کاربر باید حداقل ۱۸ سال باشد")]
bio: str | None = None
created_at: datetime = Field(default_factory=datetime.utcnow)
استفاده از این مدل:
# اعتبارسنجی دادههای ورودی
user_data = {
"id": 101,
"username": "taha_heidary",
"email": "contact@taha-heidaryfard.ir",
"age": 24,
"bio": "Software Engineer & Backend Developer",
}
user = UserProfile.model_validate(user_data)
print(user.username) # taha_heidary
# خروجی به صورت دیکشنری یا JSON
data_dict = user.model_dump(exclude={"id"})
data_json = user.model_dump_json(indent=2)
اعتبارسنجیهای پیشرفته: field_validator و model_validator
۱. استفاده از field_validator
دکوراتور @field_validator جایگزین @validator شده و پارامتر cls و v (مقدار فیلد) را دریافت میکند:
from pydantic import BaseModel, field_validator
class RegisterRequest(BaseModel):
password: str
phone: str
@field_validator("phone")
@classmethod
def validate_iran_phone(cls, v: str) -> str:
clean = v.replace(" ", "").replace("-", "")
if not (clean.startswith("09") and len(clean) == 11 and clean.isdigit()):
raise ValueError("شماره موبایل وارد شده معتبر نیست (باید ۱۱ رقم و با ۰۹ آغاز شود)")
return clean
۲. اعتبارسنجی روی کل مدل با model_validator
اگر بخواهید دو فیلد را با هم مقایسه کنید (مثلاً تطابق رمز عبور و تکرار آن)، از @model_validator استفاده میشود:
from typing import Self
from pydantic import BaseModel, model_validator
class PasswordChangeForm(BaseModel):
new_password: str
confirm_password: str
@model_validator(mode="after")
def check_passwords_match(self) -> Self:
if self.new_password != self.confirm_password:
raise ValueError("رمز عبور جدید و تکرار آن یکسان نیستند")
return self
استفاده از TypeAdapter برای ساختارهای خارج از BaseModel
در نسخههای قبلی، اعتبارسنجی یک لیست از دیکشنریها یا ساختارهای توکار نیاز به تعریف یک کلاس کمکی احمقانه داشت. در V2 قابلیت قدرتمندی به نام TypeAdapter اضافه شده است:
from pydantic import TypeAdapter
# اعتبارسنجی مستقیم لیست از اعداد مثبت
positive_ints = TypeAdapter(list[int])
# این اعتبارسنجی موفق است
result = positive_ints.validate_python([1, 2, 3, 4])
# تبدیل مستقیم به JSON
json_bytes = positive_ints.dump_json([10, 20, 30])
قابلیت اعتبارسنجی سختگیرانه (Strict Validation)
به طور پیشفرض پایدنتیک سعی میکند انواع سازگار را تبدیل کند (Coercion)؛ به عنوان مثال "42" به عدد 42 تبدیل میشود. اگر به دنبال انضباط صددرصدی هستید، کافی است حالت Strict را فعال کنید:
from pydantic import BaseModel, ConfigDict
class StrictTransaction(BaseModel):
model_config = ConfigDict(strict=True)
amount: int
approved: bool
# این خط خطای ValidationError تولید میکند چون ورودی عدد نیست بلکه استرینگ است:
# StrictTransaction.model_validate({"amount": "1000", "approved": True})
بهترین روشها در پروژههای سازمانی و FastAPI
- همواره از
Annotatedاستفاده کنید: این الگو خوانایی کد را بالا برده و وابستگی به متادیتاهای خارجی را کاهش میدهد. - پیکربندی با
ConfigDict: برای جلوگیری از ایجاد باگهای تایپی از شیء تایپشدهConfigDictبه جای کلاس توکار بهره ببرید. - از
model_validate_jsonبه جایjson.loadsدستی استفاده کنید: کتابخانه Rust زیرساخت پایدنتیک به طور مستقیم بایتهای JSON را با کارایی به مراتب بالاتری نسبت به پکیجjsonاستاندارد پایتون پارس میکند.
سوالات متداول
تفاوت عملکردی Pydantic V2 با نسخه ۱ چقدر است؟
به دلیل کامپایل شدن هسته اعتبارسنجی به کدهای باینری بهینه زبان Rust، عملیات پارسینگ دادهها و تبدیل به JSON بسته به پیچیدگی دادهها بین ۴ تا ۱۷ برابر سریعتر انجام میشود.
آیا کدهای قدیمی Pydantic V1 روی نسخه جدید کار میکنند؟
بسیاری از قابلیتهای قدیمی در ماژول pydantic.v1 برای پشتیبانی موقت نگهداری شدهاند؛ اما برای پروژههای جدید و مهاجرت کدهای قدیمی حتماً باید سینتکس V2 شامل model_dump و دکوراتورهای جدید را جایگزین کنید.
آیا Pydantic فقط با FastAPI کار میکند؟
خیر؛ Pydantic یک پکیج عمومی پایتون است و برای مدیریت متغیرهای محیطی (pydantic-settings)، اعتبارسنجی فایلهای YAML/JSON، پردازش دیتای دیتابیسها و ارتباط با مدلهای هوش مصنوعی (مانند ساختارهای خروجی JSON در LLMها) کاربرد فراوان دارد.
برچسبهای این مقاله:
