Pydantic: verilənlərin yoxlanması

Pydantic v2 ilə xarici verilənlərin yoxlanması: modellər, yumşaq və sərt rejim, `Field` məhdudiyyətləri, `Annotated` və `Literal`, sahə və model validatorları, iç-içə modellər və JSON, aliaslar, `pydantic-settings` ilə parametrlər və FastAPI-də istifadə — müraciətlərin yoxlanması layihəsi ilə.

  • İrəli
  • 22 dəq
  • 12 sual
  • 66 dərsdən 39-cusu

Bu dərsdə öyrənəcəksən

  • Pydantic modeli yazmaq, ValidationError-u oxumaq və yumşaq rejimlə sərt rejimin fərqini izah etmək
  • Field, Annotated, Literal və validatorlarla qaydalar qoymaq
  • İç-içə modelləri JSON-dan oxumaq və JSON-a yazmaq, aliaslardan istifadə etmək
  • Parametrləri BaseSettings ilə yükləmək və modelləri FastAPI-də istifadə etmək

Qeydiyyat forması server-ə {"name": "Aysel", "age": "15", "city": "Bakı"} göndərir: yaş ədəd əvəzinə sətirdir, bəzən sahə ümumiyyətlə yoxdur, bəzən e-poçtda @ unudulub. Python-un tip annotasiyaları icra zamanı yoxlanmır (bax: «Tip annotasiyaları və dataclass-lar»), ona görə belə verilənlər proqramın dərinliklərində gözlənilməz xətalara səbəb olur. Pydantic verilənləri tip annotasiyaları ilə təsvir etməyə imkan verir və onları girişdə yoxlayır, lazım olanda çevirir, səhvləri isə aydın siyahı ilə qaytarır. FastAPI də məhz onun üzərində qurulub; Pydantic v2-nin nüvəsi Rust dilində yazıldığı üçün çox sürətlidir.

İlk model

Model BaseModel-dən törənən sinifdir: hər sahənin tipi annotasiya ilə, susmaya görə qiyməti isə = ilə verilir. Obyekt yaradılan anda yoxlama işləyir; uğursuz olarsa, ValidationError bütün səhvləri birdən qaytarır: loc — harada, type — səhvin kodu, msg — izah. Pydantic brauzerdə işləmir: öz kompüterində pip install pydantic ilə sına.

Python
from datetime import date
from pydantic import BaseModel, ValidationError

class Student(BaseModel):
    name: str
    age: int
    grade: int = 9
    birthday: date | None = None

s = Student(name='Aysel', age='15', birthday='2010-03-14')
print(s)
print(s.age + 1, type(s.birthday).__name__)
print(s.model_dump())

try:
    Student(name='Murad', age='fifteen')
except ValidationError as e:
    print(e.error_count(), 'error')
    for err in e.errors():
        print(err['loc'], err['type'], '-', err['msg'])

Gözlənilən nəticə

name='Aysel' age=15 grade=9 birthday=datetime.date(2010, 3, 14)
16 date
{'name': 'Aysel', 'age': 15, 'grade': 9, 'birthday': datetime.date(2010, 3, 14)}
1 error
('age',) int_parsing - Input should be a valid integer, unable to parse string as an integer
'15' sətri tam ədəd 15-ə, '2010-03-14' isə date obyektinə çevrildi, ona görə s.age + 1 işləyir. model_dump() modeli lüğətə çevirir. 'fifteen' ədədə çevrilmir — xəta harada və niyə baş verdiyini göstərir.

Yumşaq (lax) və sərt (strict) rejimTərif

Susmaya görə Pydantic yumşaqdır: məlumat itirmədən mümkün olan çevrilmələri edir ('42' → 42, 42.0 → 42, 'yes' → True). Məlumat itəcəksə (42,5 → 42), xəta verir. ConfigDict(strict=True) ilə heç bir çevrilmə edilmir — tip dəqiq uyğun gəlməlidir.

Python
from pydantic import BaseModel, ConfigDict, ValidationError

class Lax(BaseModel):
    n: int

class Strict(BaseModel):
    model_config = ConfigDict(strict=True)
    n: int

for value in ['42', 42.0, 42.5, 'forty']:
    try:
        print(repr(value), '->', Lax(n=value).n)
    except ValidationError as e:
        print(repr(value), '->', e.errors()[0]['type'])
try:
    Strict(n='42')
except ValidationError as e:
    print('strict:', e.errors()[0]['msg'])

Gözlənilən nəticə

'42' -> 42
42.0 -> 42
42.5 -> int_from_float
'forty' -> int_parsing
strict: Input should be a valid integer
42,5 tam ədədə çevrilsəydi, kəsr hissə itərdi — ona görə int_from_float xətası. Sərt rejimdə hətta '42' sətri də qəbul edilmir.
GirişSahənin tipiNəticə (yumşaq rejim)
'16'int16
16.0int16
'16.5'intxəta int_parsing
'yes' / 'no'boolTrue / False
'2010-02-30'datexəta: belə gün yoxdur

Davamını oxumaq üçün pulsuz qeydiyyatdan keç

Dərsin qalan bölmələri, test və qeydlər Educora hesabı ilə açılır. Qeydiyyat bir dəqiqə çəkir; irəliləyişin bütün cihazlarında saxlanılır.

Tiplər və məhdudiyyətlər

Field(...) sahəyə şərt əlavə edir: sətirlər üçün min_length, max_length, pattern, ədədlər üçün gt, ge, lt, le. Annotated[int, Field(ge=0, le=100)] təkrar istifadə olunan tip yaradır. Literal[...] qiymətləri siyahı ilə məhdudlaşdırır, str | None = None sahəni qeyri-məcburi edir, default_factory=list isə hər obyektə öz boş siyahısını verir. E-poçt üçün hazır EmailStr tipi də var, amma o, pip install "pydantic[email]" tələb edir.

Python
from typing import Annotated, Literal
from pydantic import BaseModel, Field, ValidationError

Score = Annotated[int, Field(ge=0, le=100)]

class Registration(BaseModel):
    name: str = Field(min_length=2, max_length=50)
    email: str = Field(pattern=r'^[\w.+-]+@[\w-]+\.[\w.]+$')
    city: Literal['Bakı', 'Gəncə', 'Sumqayıt']
    scores: list[Score] = Field(default_factory=list)

print(Registration(name='Leyla', email='leyla@example.com', city='Bakı', scores=[95, '90']))
try:
    Registration(name='L', email='leyla.example.com', city='Quba', scores=[101])
except ValidationError as e:
    for err in e.errors():
        print(err['loc'], '-', err['msg'])

Gözlənilən nəticə

name='Leyla' email='leyla@example.com' city='Bakı' scores=[95, 90]
('name',) - String should have at least 2 characters
('email',) - String should match pattern '^[\w.+-]+@[\w-]+\.[\w.]+$'
('city',) - Input should be 'Bakı', 'Gəncə' or 'Sumqayıt'
('scores', 0) - Input should be less than or equal to 100
Siyahının elementləri də yoxlanır və çevrilir ('90' → 90). Səhvli girişdə dörd problemin hamısı birdən göstərilir; ('scores', 0) «scores siyahısının 0 nömrəli elementi» deməkdir.

Nümunə: xətanı oxuyaq

Məsələ

Hər səhvin loc-u nəyi göstərir? 1) ('name',); 2) ('scores', 1); 3) ('items', 1, 'price').

Həllini göstərHəllini gizlət

Həll

1) Modelin name sahəsi.
2) scores siyahısının ikinci elementi (sayma 0-dan başlayır): scores=[50, 101] üçün 101.
3) items siyahısındakı ikinci məhsulun price sahəsi — iç-içə modellərdə yol açardan-açara gedir.

Validatorlar

Hazır məhdudiyyətlər çatmayanda öz qaydanı yaz. @field_validator('guest') bir sahəni yoxlayır və ya təmizləyir: o, artıq çevrilmiş qiyməti alır və qiyməti qaytarmalıdır. ValueError atmaq adi ValidationError səhvinə çevrilir. Bir neçə sahəni müqayisə etmək üçün (gediş tarixi gəlişdən sonra olmalıdır) @model_validator(mode='after') lazımdır — o, hazır obyekti alır.

  1. before-validatorlar

    mode='before' xam girişi alır, məsələn, "1 200"-dən boşluğu silmək üçün.

  2. Tipə çevirmə

    Annotasiyaya görə çevirmə və yoxlama (yumşaq və ya sərt rejim).

  3. Məhdudiyyətlər

    Field(...) şərtləri: uzunluq, diapazon, şablon.

  4. after-validatorlar

    @field_validator (susmaya görə after), sonra bütöv obyekt üçün @model_validator(mode='after').

Python
from datetime import date
from pydantic import BaseModel, ValidationError, field_validator, model_validator

class Booking(BaseModel):
    guest: str
    check_in: date
    check_out: date

    @field_validator('guest')
    @classmethod
    def clean_name(cls, value: str) -> str:
        return ' '.join(value.split()).title()

    @model_validator(mode='after')
    def check_dates(self):
        if self.check_out <= self.check_in:
            raise ValueError('check_out must be after check_in')
        return self

print(Booking(guest='  aysel   məmmədova ', check_in='2026-07-01', check_out='2026-07-05'))
try:
    Booking(guest='Murad', check_in='2026-07-05', check_out='2026-07-01')
except ValidationError as e:
    print(e.errors()[0]['msg'])

Gözlənilən nəticə

guest='Aysel Məmmədova' check_in=datetime.date(2026, 7, 1) check_out=datetime.date(2026, 7, 5)
Value error, check_out must be after check_in
Validator artıq boşluqları silir və adları böyük hərflə yazır. Tarixlər yanlış ardıcıllıqdadırsa, model validatoru ValueError atır və mesajın əvvəlinə Value error, əlavə olunur.

Pydantic v1 (köhnə)

from pydantic import BaseModel, validator

class User(BaseModel):
    name: str

    @validator('name')
    def strip(cls, value):
        return value.strip()

user = User.parse_obj({'name': ' Aysel '})
print(user.dict(), user.json())

Pydantic v2

from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str

    @field_validator('name')
    @classmethod
    def strip(cls, value):
        return value.strip()

user = User.model_validate({'name': ' Aysel '})
print(user.model_dump(), user.model_dump_json())
İnternetdəki bir çox nümunə hələ v1 üçündür. v2-də: validator → field_validator (+ @classmethod), parse_obj → model_validate, .dict() → model_dump(), .json() → model_dump_json().

İç-içə modellər və JSON

Sahənin tipi başqa model ola bilər: sifarişdə list[Item] məhsul siyahısıdır və hər məhsul ayrıca yoxlanır. model_validate_json JSON sətrini bir addımda oxuyur və yoxlayır. JavaScript-də adlar adətən camelCase olur (orderId), Python-da isə snake_case — Field(alias='orderId') onları birləşdirir. Diqqət: aliası olan sahəyə giriş də aliasla verilməlidir.

Python
from pydantic import BaseModel, Field, ValidationError

class Item(BaseModel):
    product: str
    price: float = Field(gt=0)
    qty: int = Field(default=1, ge=1)

class Order(BaseModel):
    order_id: int = Field(alias='orderId')
    customer: str
    items: list[Item]

    def total(self) -> float:
        return round(sum(i.price * i.qty for i in self.items), 2)

raw = ('{"orderId": 7, "customer": "Anar", "items": [{"product": "Notebook", '
       '"price": 3.2, "qty": 5}, {"product": "Pen set", "price": 7.9}]}')
order = Order.model_validate_json(raw)
print(order.items[1], order.total())
print(order.model_dump_json(by_alias=True, exclude={'items'}))
bad = [{'product': 'Pen', 'price': 1}, {'product': 'Lamp', 'price': -5}]
try:
    Order(orderId=8, customer='Lalə', items=bad)
except ValidationError as e:
    print(e.errors()[0]['loc'], e.errors()[0]['msg'])

Gözlənilən nəticə

product='Pen set' price=7.9 qty=1 23.9
{"orderId":7,"customer":"Anar"}
('items', 1, 'price') Input should be greater than 0
İkinci məhsulun qty-si verilməyib, susmaya görə 1 götürülür: 3,2 · 5 + 7,9 = 23,9. by_alias=True JSON-u yenidən camelCase ilə yazır, exclude sahələri çıxarır. Səhvin yolu: items → 1 nömrəli element → price.
MetodNə edir
Model.model_validate(data)lüğətdən yoxlanmış obyekt
Model.model_validate_json(text)JSON sətrindən yoxlanmış obyekt
obj.model_dump()Python lüğəti
obj.model_dump_json(by_alias=True)JSON sətri (aliaslarla)
Model.model_json_schema()JSON Schema — FastAPI sənədləri üçün

Parametrlər və FastAPI

Parolları və ünvanları koda yazmaq olmaz — onlar mühit dəyişənlərində və ya .env faylında saxlanır. Ayrıca pydantic-settings paketindəki BaseSettings sahələri həmin mənbələrdən oxuyur və adi model kimi yoxlayır; SecretStr isə çap olunanda qiyməti gizlədir.

Python
import os
from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix='APP_', env_file='.env')
    debug: bool = False
    database_url: str = 'sqlite:///school.db'
    api_key: SecretStr
    max_upload_mb: int = 10

os.environ.update({'APP_DEBUG': 'true', 'APP_API_KEY': 'demo-key-123', 'APP_MAX_UPLOAD_MB': '25'})
settings = Settings()
print(settings.debug, settings.max_upload_mb, settings.database_url)
print(settings.api_key, len(settings.api_key.get_secret_value()))

Gözlənilən nəticə

True 25 sqlite:///school.db
********** 12
APP_ prefiksi ilə max_upload_mb sahəsi APP_MAX_UPLOAD_MB dəyişənindən oxunur və '25' sətri 25-ə çevrilir. Verilməyən database_url susmaya görə qiyməti saxlayır, açar isə ulduzlarla göstərilir.

FastAPI-də endpoint funksiyasının parametri model olanda sorğunun JSON gövdəsi Pydantic ilə yoxlanır, qaytarılan tip isə cavabı süzür (ətraflı: «FastAPI ilə veb servis»). Yoxlamadan keçməyən sorğu funksiyaya çatmır — klient 422 cavabı və səhvlərin siyahısını alır.

Python
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, Field

app = FastAPI()

class StudentIn(BaseModel):
    name: str = Field(min_length=2)
    age: int = Field(ge=10, le=18)

class StudentOut(BaseModel):
    id: int
    name: str

@app.post('/students', status_code=201)
def create_student(student: StudentIn) -> StudentOut:
    return StudentOut(id=1, name=student.name)

client = TestClient(app)
r = client.post('/students', json={'name': 'Aysel', 'age': '15'})
print(r.status_code, r.json())
r = client.post('/students', json={'name': 'Aysel', 'age': 25})
print(r.status_code, r.json()['detail'][0]['loc'], r.json()['detail'][0]['msg'])

Gözlənilən nəticə

201 {'id': 1, 'name': 'Aysel'}
422 ['body', 'age'] Input should be less than or equal to 18
pip install "fastapi[standard]" lazımdır. Giriş (StudentIn) və çıxış (StudentOut) modelləri ayrıdır: cavabda age yoxdur. Yaş 25 olanda funksiya çağırılmır, loc isə sorğunun gövdəsini göstərir: ['body', 'age'].

Mini-layihə: müraciətlərin yoxlanması

Yay məktəbinə müraciətlər JSON faylında gəlir. Məqsəd: düzgün müraciətləri təmiz fayla yazmaq, səhvliləri isə sətir nömrəsi ilə hesabata çıxarmaq ki, operator onları düzəldə bilsin. Bir səhvli sətir bütün emalı dayandırmamalıdır — ona görə hər sətir ayrıca yoxlanır.

Python
import json
from pydantic import BaseModel, Field, ValidationError

class Applicant(BaseModel):
    name: str = Field(min_length=2)
    age: int = Field(ge=10, le=18)
    city: str = 'Bakı'
    email: str | None = None

raw = '''[{"name": "Aysel", "age": "15", "email": "aysel@example.com"},
          {"name": "M", "age": 16},
          {"name": "Leyla", "age": "fourteen", "city": "Gəncə"},
          {"name": "Elvin", "age": 17, "city": "Sumqayıt"}]'''
valid, report = [], []
for i, row in enumerate(json.loads(raw), start=1):
    try:
        valid.append(Applicant.model_validate(row))
    except ValidationError as e:
        for err in e.errors():
            report.append(f"row {i}: {'.'.join(map(str, err['loc']))} - {err['msg']}")
print(len(valid), 'valid:', [a.name for a in valid])
print('\n'.join(report))
with open('applicants.json', 'w', encoding='utf-8') as f:
    json.dump([a.model_dump() for a in valid], f, ensure_ascii=False, indent=2)

Gözlənilən nəticə

2 valid: ['Aysel', 'Elvin']
row 2: name - String should have at least 2 characters
row 3: age - Input should be a valid integer, unable to parse string as an integer
Aysel-in "15" yaşı çevrilir, Elvin keçir. 2-ci sətirdə ad çox qısadır, 3-cüdə yaş sözlə yazılıb. model_dump() təmiz verilənləri JSON-a hazırlayır; ensure_ascii=False Azərbaycan hərflərini olduğu kimi saxlayır.

Tapşırıq

Pydantic-in etdiyini əl ilə təkrarla: validate_applicant(data) səhvlərin (sahə, mesaj) siyahısını qaytarsın. Ad (boşluqlar silinəndən sonra) ən azı 2 simvol olmalıdır, əks halda 'too short'; yaş tam ədədə çevrilməlidir ('not an integer') və 10–18 aralığında olmalıdır ('out of range').

Tapşırıq · Python
def validate_applicant(data):
    errors = []
    # check the name, then try int(data.get('age'))
    return errors

print(validate_applicant({'name': 'Aysel', 'age': '15'}))
print(validate_applicant({'name': 'M', 'age': 'fifteen'}))
print(validate_applicant({'name': 'Elvin', 'age': 25}))
print(validate_applicant({}))
Gözlənilən nəticə
[]
[('name', 'too short'), ('age', 'not an integer')]
[('age', 'out of range')]
[('name', 'too short'), ('age', 'not an integer')]

Tapşırıq

Aliasları özün yarat: to_camel(name) snake_case adı camelCase-ə çevirsin (order_id → orderId), dump_by_alias(data) isə lüğətin bütün açarlarını belə çevirsin. Pydantic-də eyni işi ConfigDict(alias_generator=to_camel) görür.

Tapşırıq · Python
def to_camel(name):
    # split by '_', keep the first word, capitalize the rest
    return name

def dump_by_alias(data):
    return data

print(to_camel('order_id'), to_camel('max_upload_mb'), to_camel('name'))
print(dump_by_alias({'order_id': 7, 'customer_name': 'Anar', 'total': 23.9}))
Gözlənilən nəticə
orderId maxUploadMb name
{'orderId': 7, 'customerName': 'Anar', 'total': 23.9}

Yadda saxla

  • BaseModel sahələri tip annotasiyaları ilə təsvir edir; yoxlama obyekt yaradılanda işləyir və bütün səhvlər ValidationError-da (loc, type, msg) toplanır.
  • Yumşaq rejim məlumat itirmədən çevirir ('15' → 15), sərt rejim çevirmir; 42,5 → int həmişə xətadır.
  • Field(...), Annotated və Literal hazır qaydalar verir; @field_validator bir sahəni, @model_validator(mode='after') bir neçə sahəni yoxlayır.
  • model_validate(_json) girişdir, model_dump(_json) çıxışdır; alias və by_alias=True camelCase JSON ilə işləməyə imkan verir.
  • BaseSettings parametrləri mühitdən və .env-dən oxuyur, SecretStr sirləri gizlədir; FastAPI yoxlamadan keçməyən sorğuya 422 qaytarır.
Dərsdə səhv və ya qeyri-dəqiqlik gördün?

Özünü yoxla

12 sual. Hər düzgün cavab XP qazandırır.

Sual 1 / 12

Sual 1 / 12. class Student(BaseModel): name: str; age: int. Student(name='Aysel', age='15').age nədir?