معرفی کتابخانه pydantic در پایتون

pydantic یکی از کتابخانه‌های مشهور پایتون برای اعتبارسنجی (validation) و سریالایزیشن داده‌ها است. این کتابخانه با استفاده از type hints پایتون، مدل‌هایی تعریف می‌کند که داده‌های ورودی را تایپ‌چک و پاک‌سازی می‌کنند و خطاهای واضحی برمی‌گردانند. pydantic برای توسعه وب (مثلاً همراه با FastAPI)، پردازش ورودی‌های API، تنظیمات برنامه و کار با داده‌های متعلق به پایگاه‌داده بسیار محبوب است.

ویژگی‌های کلیدی

• استفاده از تایپ‌های پایتون و تایپ‌های ترکیبی (typing)
• خطاهای خوانا و قابل پردازش
• پشتیبانی از سریالایز و دی‌سریالایز JSON
• قابلیت تعریف Validator های سفارشی
• عملکرد بالا (pydantic v2 مبتنی بر pydantic-core)
• قابلیت کار با ORMها و تبدیل از/به اشیاء

چرا از pydantic استفاده کنیم؟

پیش از pydantic، اعتبارسنجی دستی داده‌ها زمان‌بر و خطاپذیر بود. pydantic با ترکیب annotations و validation، کد خواناتر و ایمن‌تری ارائه می‌دهد. به‌علاوه در پروژه‌های API، مدل‌های pydantic می‌توانند مستندسازی و تست را ساده‌تر کنند.

مثال‌های عملی

مثال پایه‌ای — تعریف مدل و اعتبارسنجی خودکار

from pydantic import BaseModel, ValidationError
from typing import List

class User(BaseModel):
    id: int
    name: str
    tags: List[str] = []

try:
    u = User(id='10', name='علی', tags=[1, 'python'])
    print(u.json())
except ValidationError as e:
    print(e.json())

توضیح: این کد یک مدل ساده User تعریف می‌کند. pydantic تلاش می‌کند مقادیر را به نوع درست تبدیل کند (مثلاً ’10’ به int). اگر مقداری غیرقابل تبدیل باشد، ValidationError با جزئیات خطا صادر می‌شود. خروجی json() مدل سریال‌شده را نمایش می‌دهد.

مثال: validator سفارشی (pydantic v2)

from pydantic import BaseModel, field_validator
import re

class Contact(BaseModel):
    email: str

    @field_validator('email')
    def check_email(cls, v):
        if not re.match(r'^[^@]+@[^@]+.[^@]+$', v):
            raise ValueError('invalid email')
        return v

c = Contact(email='user@example.com')

توضیح: این مثال از سینتکس pydantic v2 استفاده می‌کند: @field_validator برای اعتبارسنجی فیلد email. اگر فرمت ایمیل نامعتبر باشد، خطا پرتاب می‌شود. استفاده از validatorهای سفارشی به شما کنترل دقیق بر پاک‌سازی و نرمال‌سازی داده‌ها می‌دهد.

بهینه‌سازی یا نسخه‌های متفاوت — نکات انتقالی (v1 → v2)

در pydantic v1 از @validator و BaseSettings استفاده می‌شد. در v2، عملکردها به pydantic-core منتقل شده و decoratorها به نام‌های جدید (@field_validator و @model_validator) تغییر یافته‌اند و مدیریت تنظیمات (settings) به پکیجی جداگانه به نام pydantic-settings منتقل شده است. هنگام مهاجرت، به مستندات رسمی مراجعه کنید تا تغییرات در Config و روش‌های سریالایز را رعایت کنید.

کاربردها و سناریوهای عملی

• FastAPI: pydantic به‌عنوان هسته مدل‌دهی برای مسیریاب‌های API استفاده می‌شود.
• تنظیمات برنامه: مدیریت متغیرهای محیطی با BaseSettings (v1) یا pydantic-settings (v2).
• ورودی‌های کاربر و پردازش فایل: پاک‌سازی داده‌ها قبل از ذخیره یا محاسبه.
• تعامل با ORM: تبدیل اشیاء دیتابیسی به مدل‌های نوع‌دار برای خروجی API.

مثال — استفاده از مدل برای تنظیمات (v1)

from pydantic import BaseSettings

class Settings(BaseSettings):
    debug: bool = False
    database_url: str

    class Config:
        env_file = '.env'

s = Settings()

توضیح: در این مثال BaseSettings مقادیر را از متغیرهای محیطی یا فایل .env می‌خواند. توجه کنید در pydantic v2 نگهداری تنظیمات در بسته‌ای مجزا توصیه می‌شود؛ در صورت استفاده از v2 از پکیج pydantic-settings بهره ببرید.

مدیریت خطاها و خروجی‌های خوانا

ValidationError شیئی است که حاوی اطلاعات ساختاری از خطاها است؛ می‌توان آن را به JSON تبدیل کرد یا برای ثبت (logging) و پاسخ‌دهی API استفاده کرد. این قابلیت برای تجربه کاربری بهتر و دیباگ سریع‌تر بسیار مفید است.

ORM Mode و تبدیل از اشیاء

اگر می‌خواهید مدل را مستقیماً از اشیاء ORM بسازید (مثل SQLAlchemy)، در pydantic v1 می‌توانید Config.orm_mode = True را تنظیم کنید. در v2 معادل آن تنظیمات مختلفی وجود دارد (مثلاً from_attributes در ConfigDict).

نمونه جدول مقایسه‌ای

نکات پیشرفته و توصیه‌های عملکردی

• از تایپ‌های صحیح و ساده استفاده کنید تا زمان اعتبارسنجی کاهش یابد.
• برای پردازش مقادیر زیاد، از pydantic v2 استفاده کنید که مبتنی بر pydantic-core است و بسیار سریع‌تر است.
• در validatorها از عملیات سنگین خودداری کنید؛ بهتر است منطق پیچیده را خارج از مرحله validate اجرا کنید.
• از قابلیت‌های مدل برای مستندسازی و تست واحد بهره ببرید (مثلاً نمونه‌سازی و assert روی خطاها).

نتیجه‌گیری مختصر

pydantic کتابخانه‌ای قدرتمند برای اعتبارسنجی و سریالایز داده‌ها است که با تایپ‌هینت‌ها یک تجربه توسعه‌ای ایمن و خوانا فراهم می‌کند. با ورود v2، عملکرد بهبود یافته و برخی APIها تغییر کرده‌اند؛ بنابراین در پروژه‌های جدید از v2 استفاده کرده و در پروژه‌های قدیمی با دقت مهاجرت کنید.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال