اگر تا حالا با داده‌های کثیف، خطاهای تایپ ناگهانی یا APIهایی که هر بار یک شکل جدید از JSON برمی‌گردانند کلنجار رفته باشی، Pydantic دقیقاً همان ابزاری است که جای خالی‌اش را حس کرده‌ای. این کتابخانه پایتون به تو کمک می‌کند داده‌ها را قبل از اینکه وارد منطق اصلی برنامه شوند، با قدرت Type Hintها اعتبارسنجی، تمیز و تبدیل کنی — بدون نوشتن ده‌ها if و try تکراری. در این راهنمای کامل، از نصب و ساخت اولین مدل تا اعتبارسنجی‌های پیشرفته، مدیریت خطا و استفاده واقعی در FastAPI را قدم‌به‌قدم یاد می‌گیری.

Pydantic چیست و چرا اعتبارسنجی هوشمند اهمیت دارد؟

Pydantic یک کتابخانه اعتبارسنجی داده برای پایتون است که با تکیه بر Type Hintها، ورودی‌ها را به‌صورت خودکار بررسی، تبدیل و گزارش می‌دهد. کافی‌ست یک کلاس مدل بسازی و نوع هر فیلد را مشخص کنی؛ Pydantic خودش چک می‌کند داده درست است یا نه و در صورت خطا، گزارشی دقیق و قابل فهم می‌دهد. اگر می‌خواهی کد تمیزتر، امن‌تر و آماده برای محیط پروداکشن داشته باشی، ادامه این آموزش را از دست نده.

فهرست مطالب

Pydantic چیست و چه مشکلی را حل می‌کند؟
نصب و راه‌اندازی اولیه Pydantic
ساخت مدل و انواع فیلدها در Pydantic
اعتبارسنجی پیشرفته با Field و validator
مدیریت خطاها و کار با داده‌های تو در تو
کاربرد Pydantic در پروژه‌های واقعی و FastAPI
مقایسه Pydantic با ابزارهای مشابه
سوالات متداول

Pydantic چیست و چه مشکلی را حل می‌کند؟

در پروژه‌های واقعی، داده از منابع مختلف می‌آید: فرم کاربر، فایل JSON، دیتابیس، یا یک API خارجی. مشکل اینجاست که پایتون به‌صورت پیش‌فرض داده را اعتبارسنجی نمی‌کند و یک اشتباه کوچک — مثلاً ارسال رشته به‌جای عدد — می‌تواند کل سرویس را زمین بزند. Pydantic این خلأ را پر می‌کند: تو فقط شکل درست داده را توصیف می‌کنی و Pydantic تضمین می‌کند هر چیزی که وارد سیستم می‌شود، دقیقاً همان شکل را دارد.

تفاوت Pydantic با dataclass و دیکشنری معمولی

dataclass فقط ساختار داده را نگه می‌دارد ولی اعتبارسنجی نمی‌کند؛ اگر عدد رشته‌ای بفرستی، قبول می‌کند. دیکشنری هم که هیچ تضمینی ندارد. Pydantic اما هر فیلد را با نوعش چک می‌کند، تبدیل خودکار انجام می‌دهد — مثلاً رشته‌ی "123" را به عدد 123 — و اگر داده نامعتبر باشد، خطای ValidationError با جزئیات کامل می‌دهد. همین ویژگی، دیباگ را ده برابر سریع‌تر می‌کند.

چرا Pydantic V2 یک جهش بزرگ بود؟

نسخه ۲ با بازنویسی هسته به Rust و کتابخانه pydantic-core، تا ۲۰ برابر سریع‌تر از V1 شد. همچنین API تمیزتری آورد: BaseModel ساده‌تر، field_validator و model_validator به‌جای validatorهای قدیمی، و پشتیبانی عالی از JSON Schema و سریالایز هوشمند. اگر هنوز روی V1 هستی، مهاجرت به V2 ارزشش را دارد؛ هم سرعت و هم تجربه توسعه‌دهنده بهتر شده.

نصب و راه‌اندازی اولیه Pydantic

شروع کار با Pydantic کمتر از یک دقیقه طول می‌کشد و نیاز به تنظیمات خاصی ندارد.

نصب Pydantic V2

برای نصب آخرین نسخه کافی‌ست دستور زیر را اجرا کنی:

pip install "pydantic>=2.0"
# یا با uv
uv add pydantic

اگر می‌خواهی از قابلیت ایمیل ولیدیشن یا تنظیمات محیطی استفاده کنی، وابستگی‌های اضافی را نصب کن:

pip install "pydantic[email]"
pip install pydantic-settings

نسخه را با import pydantic; print(pydantic.__version__) چک کن تا مطمئن شوی V2 نصب شده.

اولین مدل ساده

بیایید یک مدل کاربر بسازیم:

from pydantic import BaseModel, EmailStr

class User(BaseModel):
id: int
name: str
email: EmailStr
age: int | None = None

user = User(id="1", name="سارا", email="sara@example.com")
print(user) # id=1 name='سارا' email='sara@example.com' age=None
print(user.model_dump()) # دیکشنری تمیز

نکته جالب اینجاست که id را به‌صورت رشته "1" دادیم ولی Pydantic خودش به عدد تبدیل کرد. اگر ایمیل نامعتبر باشد یا id قابل تبدیل نباشد، همان لحظه خطا می‌دهد و اجازه نمی‌دهد آبجکت ناقص ساخته شود.

ساخت مدل و انواع فیلدها در Pydantic

قلب Pydantic مدل‌هایش هستند. هر مدل مثل یک قرارداد است که می‌گوید داده ورودی باید چه شکلی باشد.

فیلدهای اجباری و اختیاری

فیلد اجباری: فقط نوع را بنویس؛ اگر مقدار ندهی خطا می‌دهد. مثل name: str
فیلد اختیاری با پیش‌فرض: مقدار پیش‌فرض بده. مثل age: int = 18
اختیاریِ واقعاً اختیاری: از Optional یا | None استفاده کن. مثل bio: str | None = None
مقدار کارخانه‌ای: برای لیست یا دیکشنری از Field(default_factory=list) استفاده کن تا هر نمونه لیست جدا داشته باشد.

from pydantic import BaseModel, Field

class Product(BaseModel):
title: str
price: float
tags: list[str] = Field(default_factory=list)
stock: int = 0

اعتبارسنجی خودکار با Type Hint

Pydantic از تمام تایپ‌های استاندارد پایتون پشتیبانی می‌کند: int, float, str, bool, datetime, UUID, Literal, Union و حتی تایپ‌های پیچیده مثل list[User]. به‌علاوه، تبدیل هوشمند دارد: رشته "true" به bool، عدد اعشاری رشته‌ای به float و ISO Date مثل "2026-08-31" به datetime تبدیل می‌شود. این یعنی ورودی‌های کثیف API را بدون کد اضافی تمیز می‌کنی.

برای یادگیری عمیق‌تر مدیریت هم‌زمانی در پروژه‌های پایتونی، پیشنهاد می‌کنیم نگاهی به آموزش AsyncIO در پایتون؛ اجرای هم‌زمان تسک‌ها به زبان ساده بیندازی؛ ترکیب AsyncIO با مدل‌های Pydantic برای سرویس‌های سریع عالی جواب می‌دهد.

اعتبارسنجی پیشرفته با Field و validator

گاهی فقط نوع کافی نیست؛ می‌خواهی بگویی «سن باید بین ۰ تا ۱۲۰ باشد» یا «پسورد حداقل ۸ کاراکتر». اینجا Field و ولیدیتورها وارد می‌شوند.

استفاده از Field برای محدودیت‌ها

from pydantic import BaseModel, Field

class Signup(BaseModel):
username: str = Field(min_length=3, max_length=20, pattern=r"^[a-zA-Z0-9_]+$")
password: str = Field(min_length=8)
age: int = Field(ge=13, le=120, description="سن کاربر")
price: float = Field(gt=0, description="باید مثبت باشد")

پارامترهای پرکاربرد Field عبارت‌اند از: min_length, max_length, pattern, gt, ge, lt, le, description, examples, strict. با strict=True می‌توانی تبدیل خودکار را غیرفعال کنی تا فقط داده با نوع دقیق قبول شود.

ساخت اعتبارسنج سفارشی با field_validator و model_validator

برای منطق‌های خاص، ولیدیتور سفارشی بنویس:

from pydantic import BaseModel, field_validator, model_validator

class PasswordForm(BaseModel):
password: str
confirm_password: str

@field_validator("password")
@classmethod
def strong_password(cls, v: str) -> str:
if v.isdigit() or v.isalpha():
raise ValueError("پسورد باید ترکیبی از حروف و عدد باشد")
return v

@model_validator(mode="after")
def check_match(self):
if self.password != self.confirm_password:
raise ValueError("تکرار پسورد مطابقت ندارد")
return self

field_validator برای یک فیلد و model_validator برای کل مدل است. حالت mode="before" قبل از تبدیل و mode="after" بعد از ساخته‌شدن مدل اجرا می‌شود. این ابزار به تو اجازه می‌دهد هر قانون تجاری را دقیق پیاده کنی.

مدیریت خطاها و کار با داده‌های تو در تو

یکی از نقاط قوت Pydantic، گزارش خطای انسانی و ساختار تو‌در‌تو است.

خواندن خطاهای ValidationError

from pydantic import BaseModel, ValidationError

class Item(BaseModel):
name: str
qty: int = Field(gt=0)

try:
Item(name=123, qty=-2)
except ValidationError as e:
print(e.errors())
# [{'type': 'string_type', 'loc': ('name',), 'msg': '...'},
# {'type': 'greater_than', 'loc': ('qty',), 'msg': '...'}]
print(e.json(indent=2))

هر خطا شامل loc (آدرس فیلد)، type و msg است. می‌توانی آن را مستقیم به کلاینت برگردانی یا لاگ کنی. برای نمایش کاربرپسند، از e.errors() یک لیست تمیز بساز.

مدل‌های تودرتو و لیست مدل‌ها

class Address(BaseModel):
city: str
street: str

class Customer(BaseModel):
name: str
address: Address
orders: list[Item]

data = {
"name": "علی",
"address": {"city": "تهران", "street": "ولیعصر"},
"orders": [{"name": "موس", "qty": 2}]
}
cust = Customer(**data)
print(cust.model_dump_json(indent=2))

Pydantic به‌صورت خودکار دیکشنری‌های تو‌در‌تو را به مدل تبدیل می‌کند و برعکس با model_dump و model_dump_json می‌توانی خروجی JSON تمیز بگیری. پارامتر by_alias و exclude_none هم برای کنترل خروجی عالی هستند.

کاربرد Pydantic در پروژه‌های واقعی و FastAPI

اگر با FastAPI کار کرده باشی، بدون اینکه بدانی از Pydantic استفاده کرده‌ای؛ چون تمام request/response modelهای FastAPI همان مدل‌های Pydantic هستند.

اتصال Pydantic به FastAPI

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class CreateUser(BaseModel):
name: str
email: EmailStr

@app.post("/users")
def create_user(payload: CreateUser):
# payload همین الان ولید شده است
return {"msg": f"کاربر {payload.name} ساخته شد"}

FastAPI به‌صورت خودکار داکیومنت Swagger را از روی مدل می‌سازد، ورودی را ولید می‌کند و در صورت خطا، پاسخ ۴۲۲ با جزئیات برمی‌گرداند. ترکیب این دو باعث می‌شود توسعه API هم سریع و هم ایمن شود.

مدیریت تنظیمات با Pydantic Settings

برای مدیریت env و تنظیمات از pydantic-settings استفاده کن:

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
app_name: str = "MyApp"
debug: bool = False
db_url: str

class Config:
env_file = ".env"

settings = Settings() # خودکار از متغیر محیطی و .env می‌خواند

این روش به مراتب امن‌تر از خواندن دستی os.getenv است؛ چون نوع متغیرها چک می‌شود و اگر متغیری جا افتاده باشد، برنامه همان اول با خطای واضح متوقف می‌شود نه در میانه اجرا.

وقتی پروژه‌ات بزرگ شد، اتوماسیون انتشار و تست اهمیت پیدا می‌کند؛ برای همین پیشنهاد می‌کنیم آموزش GitHub Actions از صفر؛ ساخت پایپ‌لاین CI/CD خودکار را هم ببینی تا مدل‌های Pydantic‌ات را با هر push به‌صورت خودکار تست و دیپلوی کنی.

مقایسه Pydantic با ابزارهای مشابه

انتخاب ابزار به نیازت بستگی دارد، اما جدول زیر تفاوت‌ها را شفاف می‌کند:

ابزار	سرعت	اعتبارسنجی	تبدیل خودکار	بهترین برای
Pydantic V2	بسیار بالا (Rust)	کامل + سفارشی	بله، هوشمند	API، سرویس‌های پروداکشن، FastAPI
dataclass	بالا	ندارد	ندارد	ساختار ساده داخلی
attrs	بالا	محدود	محدود	کلاس‌های سبک با ولیدیشن ساده
marshmallow	متوسط	خوب	نیاز به Schema جدا	پروژه‌های قدیمی، سریالایز پیچیده
TypeBox / msgspec	بسیار بالا	خوب	بله	نیاز به سرعت فوق‌العاده و JSON خالص

اگر سرعت و تجربه توسعه‌دهنده برایت اولویت دارد، Pydantic V2 بهترین تعادل بین قدرت و سادگی را می‌دهد.

سوالات متداول

آیا Pydantic فقط برای FastAPI است؟

خیر. Pydantic یک کتابخانه مستقل است و در هر پروژه پایتونی — از اسکریپت ساده تا ETL، ربات تلگرام یا پردازش داده — قابل استفاده است. FastAPI فقط یکی از معروف‌ترین مصرف‌کننده‌های آن است، چون مدل‌های Pydantic را به‌عنوان ورودی/خروجی API می‌پذیرد.

تفاوت Pydantic با تایپ‌هینت معمولی چیست؟

تایپ‌هینت فقط راهنماست و در زمان اجرا چیزی را چک نمی‌کند؛ اما Pydantic در زمان اجرا ولیدیشن واقعی انجام می‌دهد، خطا می‌دهد و داده را تبدیل می‌کند. به زبان ساده، تایپ‌هینت «پیشنهاد» است و Pydantic «پلیس» داده‌هاست.

آیا مهاجرت از Pydantic V1 به V2 سخت است؟

تا حد زیادی نه. بیشتر کدها با تغییر class Config به model_config = ConfigDict(...) و جایگزینی @validator با @field_validator مهاجرت می‌کنند. ابزار bump-pydantic هم به‌صورت خودکار بخش زیادی از تغییرات را اعمال می‌کند؛ حتماً تست‌ها را بعد از مهاجرت اجرا کن.

آموزش Pydantic در پایتون؛ اعتبارسنجی هوشمند داده‌ها از صفر تا حرفه‌ای