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.
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.
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
int_from_float xətası. Sərt rejimdə hətta '42' sətri də qəbul edilmir.| Giriş | Sahənin tipi | Nəticə (yumşaq rejim) |
|---|---|---|
'16' | int | 16 |
16.0 | int | 16 |
'16.5' | int | xəta int_parsing |
'yes' / 'no' | bool | True / False |
'2010-02-30' | date | xə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.
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'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
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.
before-validatorlar
mode='before'xam girişi alır, məsələn,"1 200"-dən boşluğu silmək üçün.Tipə çevirmə
Annotasiyaya görə çevirmə və yoxlama (yumşaq və ya sərt rejim).
Məhdudiyyətlər
Field(...)şərtləri: uzunluq, diapazon, şablon.after-validatorlar
@field_validator(susmaya görə after), sonra bütöv obyekt üçün@model_validator(mode='after').
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
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())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.
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 0qty-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.| Metod | Nə 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.
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.
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 18pip 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.
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
"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').
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.
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
BaseModelsahələri tip annotasiyaları ilə təsvir edir; yoxlama obyekt yaradılanda işləyir və bütün səhvlərValidationError-da (loc,type,msg) toplanır.- Yumşaq rejim məlumat itirmədən çevirir (
'15'→ 15), sərt rejim çevirmir; 42,5 →inthəmişə xətadır. Field(...),AnnotatedvəLiteralhazır qaydalar verir;@field_validatorbir sahəni,@model_validator(mode='after')bir neçə sahəni yoxlayır.model_validate(_json)girişdir,model_dump(_json)çıxışdır;aliasvəby_alias=TruecamelCase JSON ilə işləməyə imkan verir.BaseSettingsparametrləri mühitdən və.env-dən oxuyur,SecretStrsirləri gizlədir; FastAPI yoxlamadan keçməyən sorğuya 422 qaytarır.