Pydantic

#Pydantic #Python #VeriDoğrulama #LLM #FastAPI #JSONSchema

Python tip ipuclariyla runtime veri dogrulama ve seri hale getirme saglayan Python kutuphanesi.

Pydantic, Python'da veri doğrulama ve yapılandırma yönetimi için kullanılan açık kaynak bir kütüphanedir. Python tip ipuçlarını (type hints) kullanarak çalışma zamanında (runtime) otomatik veri doğrulama sağlar; hatalı veya uyumsuz veri geldiğinde net ve anlaşılır hata mesajları üretir. Samuel Colvin tarafından geliştirilen Pydantic, Python ekosisteminin en çok indirilen kütüphanelerinden biri konumuna gelmiştir. Pydantic'te veri yapıları, BaseModel sınıfı miras alınarak tanımlanır. Her alan, tip annotasyonuyla belirtilir; kütüphane bu tiplere göre otomatik doğrulama yapar. Gelen veriyi gerektiğinde dönüştürür: string'i integer'a, ISO tarih dizesini datetime nesnesine otomatik çevirebilir (coercion). Field() fonksiyonu ile minimum/maksimum değer, desen eşleştirmesi ve varsayılan değer gibi ek kısıtlamalar tanımlanabilir. Pydantic v2, Rust ile yeniden yazılmış çekirdek doğrulama motoruyla v1'e kıyasla 5–50 kat daha hızlıdır. model_validator ve field_validator dekoratörleriyle modele özgül kısıtlamalar ve çapraz alan doğrulamaları eklenebilir. Mevcut v1 projeleri pydantic-v1-compat paketi yardımıyla kademeli olarak taşınabilir. Yapay zeka ekosistemindeki önemi giderek artmaktadır. LangChain ve LlamaIndex, Pydantic modellerini yapılandırılmış çıktı için kullanır. OpenAI API'si Pydantic modelini doğrudan kabul ederek yapılandırılmış JSON doğrulama gerçekleştirir. Instructor kütüphanesi, herhangi bir LLM'den Pydantic model doğrulamasıyla yapılandırılmış çıktı almayı kolaylaştırır. FastAPI ise Pydantic'i HTTP istek ve yanıt doğrulaması için temel altyapı olarak kullanır. pydantic-settings paketi, çevre değişkenlerini ve .env dosyalarındaki yapılandırmayı Pydantic modeli olarak yönetmeyi sağlar; tip-güvenli yapılandırma yönetiminin fiili standardı hâline gelmiştir. Her Pydantic modeli, model_json_schema() metoduyla tam bir JSON Schema'ya dönüştürülebilir; bu özellik OpenAI function calling ve yapılandırılmış çıktı (structured output) desteği için kritik öneme sahiptir. Pydantic'in yaygınlığı yalnızca bireysel projelerle sınırlı değildir: Hugging Face, Azure SDK, AWS CDK ve Databricks gibi kurumsal projeler de veri katmanlarında Pydantic'ten yararlanmaktadır.

Temel Kullanım

from pydantic import BaseModel ile bir sınıf oluşturulur ve alanlar tip annotasyonuyla tanımlanır. Örnek: class User(BaseModel): name: str; age: int; email: str. User(name='Ali', age=30, email='ali@ex.com') şeklinde örnek oluşturunca Pydantic tipleri doğrular. Yanlış tip verilirse ValidationError fırlatılır ve hangi alanın hangi nedenle geçersiz olduğu net biçimde raporlanır.

Alan Kısıtlamaları ve Validatörler

Field() ile ek kısıtlamalar eklenir: age: int = Field(ge=0, le=150) sadece 0–150 aralığını kabul eder; email: str = Field(pattern=r'.+@.+') regex doğrulaması yapar. @field_validator ile özel doğrulama mantığı eklenir. @model_validator ile çapraz alan doğrulaması (örneğin başlangıç tarihi bitiş tarihinden önce olmalı) uygulanabilir.

LLM ve Yapay Zeka Entegrasyonu

OpenAI'nin Structured Outputs özelliği Pydantic modelini doğrudan kabul eder: client.beta.chat.completions.parse(model=..., messages=..., response_format=MyModel). Bu sayede LLM yanıtı otomatik olarak Pydantic modeline dönüştürülür ve doğrulanır. Instructor kütüphanesi bu yaklaşımı OpenAI, Anthropic ve diğer sağlayıcılara genişletir. LangChain'in PydanticOutputParser, LLM çıktısını Pydantic modeline parse eder.

FastAPI ile Entegrasyon

FastAPI, request body, query parametreleri ve response modeli için Pydantic kullanır. @app.post('/users', response_model=UserOut) şeklinde endpoint tanımlanınca FastAPI, giriş doğrulaması, hata mesajları ve otomatik OpenAPI dokümantasyonu üretimini Pydantic üzerinden gerçekleştirir. Bu entegrasyon, type-safe API geliştirmeyi önemli ölçüde kolaylaştırır ve geliştirici verimliliğini artırır.

Pydantic Settings ve JSON Schema

pydantic-settings paketi, çevre değişkenlerini ve .env dosyalarını tip-güvenli Pydantic modellerine dönüştürür. class Settings(BaseSettings): database_url: str; debug: bool = False şeklinde tanımlanan yapılandırma, 12-Factor App metodolojisine uygun olarak ortamdan otomatik okunur. model_json_schema() metodu ise her Pydantic modelinden eksiksiz bir JSON Schema üretir; OpenAI function calling ve tool use için bu şema doğrudan kullanılabilir.

Sık Sorulan Sorular

Pydantic v1 ile v2 arasındaki fark nedir? v2, Rust tabanlı çekirdek motoruyla v1'e göre 5–50 kat daha hızlıdır; API değişiklikleri mevcut olmakla birlikte pydantic-v1-compat paketi geçişi kolaylaştırır.

Python dataclass yerine neden Pydantic tercih edilmeli? Python dataclass çalışma zamanında doğrulama yapmaz; Pydantic runtime doğrulama, otomatik dönüştürme (coercion), serileştirme ve JSON Schema üretimi sağlar.

Pydantic Settings ne işe yarar? Çevre değişkenlerini ve .env dosyalarını tip-güvenli Pydantic modelleri olarak yönetir; FastAPI uygulamalarında yapılandırma yönetiminin standardı hâline gelmiştir.

marshmallow veya attrs ile farkı nedir? Pydantic, Python tip ipuçlarını kullanarak daha Pythonic bir deneyim sunar ve LLM/FastAPI ekosistemiyle çok daha derin entegrasyon sağlar.

Pydantic hangi Python sürümünü gerektirir? Pydantic v2, Python 3.8 ve üzerini destekler; tip ipuçlarından maksimum yararlanmak için Python 3.10+ önerilir.

LLM uygulamalarında neden bu kadar önemlidir? OpenAI Structured Outputs, Instructor ve LangChain gibi araçlar yapılandırılmış çıktı garantisi için Pydantic modellerini temel alır; bu sayede LLM yanıtları tip-güvenli nesnelere dönüşür.

terminal Pydantic kurulumu ve ilk model

  • check_circle Paketi kur: pip install pydantic komutu v2 serisini kurar ve ek bağımlılık gerektirmez. Kurulu sürümü python -c "import pydantic; print(pydantic.VERSION)" ile doğrulayabilirsin.
  • check_circle Python sürümünü kontrol et: Pydantic v2'nin güncel sürümleri Python 3.9 ve üzerinde çalışır. 3.10 ve sonrası önerilir, çünkü str veya None birleşimini tek satırda yazmaya izin veren sözdizimi orada gelir.
  • check_circle Ek paketleri ayır: E-posta doğrulaması için pip install pydantic[email] gerekir, EmailStr tipi bu ek olmadan çalışmaz. Ortam değişkeni yönetimi de ayrıldı: pip install pydantic-settings kurulmadan BaseSettings kullanılamaz.
  • check_circle İlk modeli yaz: from pydantic import BaseModel ile sınıf tanımla, alanları tip ipucuyla belirt. User(name='Ali', age='30') çağrısında metin olarak gelen yaş otomatik olarak int'e çevrilir; çevrilemeyecek bir değerde ValidationError yükselir.
  • check_circle Veriyi al ve geri ver: Sözlükten model üretmek için model_validate, JSON metninden üretmek için model_validate_json, modeli geri çevirmek için model_dump ve model_dump_json kullanılır.
  • check_circle Editör desteğini aç: mypy veya pyright ile birlikte kullanıldığında yanlış alan adı ve uyumsuz tip kod yazılırken yakalanır. Bu, doğrulamanın bir kısmını çalışma zamanından önce çekmenin en ucuz yolu.

swap_horiz Pydantic v1'den v2'ye geçiş: değişen isimler

  • check_circle .dict() yerine .model_dump(): Modeli sözlüğe çevirme metodu yeniden adlandırıldı. Eski ad uyarı vererek çalışmaya devam ediyor ama kaldırılmak üzere işaretli.
  • check_circle .json() yerine .model_dump_json(): JSON metni üretimi. Tarih, UUID ve Decimal gibi tipler bu metotla beklendiği biçimde serileştirilir.
  • check_circle parse_obj ve parse_raw yerine model_validate: Dışarıdan gelen sözlük için model_validate, ham JSON metni için model_validate_json kullanılır.
  • check_circle schema() yerine model_json_schema(): JSON Schema üretimi. OpenAI function calling ve tool tanımlarında doğrudan bu çıktı kullanılıyor.
  • check_circle @validator yerine @field_validator: Tek alan doğrulaması. v2'de doğrulamanın tip dönüşümünden önce mi sonra mı çalışacağı mode parametresiyle açıkça yazılır.
  • check_circle @root_validator yerine @model_validator: Alanlar arası doğrulama. mode değeri after olduğunda tüm alanlar dolduktan sonra çalışır, başlangıç ve bitiş tarihi karşılaştırması gibi kontroller buraya yazılır.
  • check_circle class Config yerine model_config: Ayarlar iç sınıf yerine ConfigDict sözlüğüyle tanımlanır. orm_mode artık from_attributes, allow_mutation kapalı ayarı ise frozen olarak geçiyor.
  • check_circle Toplu dönüşüm: bump-pydantic aracı kod tabanındaki yeniden adlandırmaların çoğunu otomatik uygular. Kalan uyarıları tek tek gözden geçirmek gerekir, özellikle özel validatörlerde davranış farkı çıkabilir.

bug_report ValidationError yakalamak ve hatayı Türkçe göstermek

Pydantic doğrulama başarısız olduğunda ValidationError yükseltir ve hangi alanın neden reddedildiğini yapılandırılmış biçimde taşır. try ile except ValidationError bloğunda e.errors() çağrısı, her hata için type, loc, msg ve input alanlarını içeren sözlükler döndürür. e.json() aynı listeyi JSON metni olarak verir, log'a yazarken bu biçim daha kullanışlı.

Varsayılan mesajlar İngilizcedir ve son kullanıcıya doğrudan gösterilmeye uygun değildir. Yaygın çözüm, e.errors() çıktısındaki type değerini (missing, int_parsing, string_too_short, greater_than gibi) Türkçe karşılıklara eşleyen bir sözlük tutmak ve arayüze o mesajı basmaktır. loc alanı hatalı alanın yolunu verdiği için formda ilgili kutuyu işaretlemek de kolaylaşır.

FastAPI tarafında doğrulama hatası RequestValidationError olarak gelir. Kendi exception handler'ını yazıp aynı eşlemeyi tek yerde uygulayabilir, bütün uç noktalarda tutarlı bir Türkçe hata gövdesi döndürebilirsin. Alan düzeyinde özel mesaj gerekiyorsa Field içindeki açıklamayı ya da özel bir validatör içinde yükseltilen ValueError metnini kullanmak en kısa yol.

help Sıkça Sorulan Sorular

  • check_circle Pydantic nasıl kurulur? pip install pydantic komutu güncel v2 sürümünü kurar. E-posta doğrulaması için pip install pydantic[email], ortam değişkeni yönetimi için pip install pydantic-settings ayrıca kurulmalıdır. Kurulu sürümü pydantic.VERSION değeriyle kontrol edebilirsin.
  • check_circle Pydantic ücretsiz mi? Evet, Pydantic MIT lisanslı açık kaynak bir kütüphanedir ve ticari projelerde ücretsiz kullanılır. Aynı ekibin ticari ürünü olan Logfire ayrı bir gözlemlenebilirlik servisidir; kütüphaneyi kullanmak için gerekli değildir.
  • check_circle Pydantic'te .dict() neden çalışmıyor? v2'de metot .model_dump() olarak yeniden adlandırıldı; .dict() geriye dönük uyumluluk için uyarı vererek duruyor. Aynı şekilde .json() yerine .model_dump_json(), parse_obj yerine model_validate kullanılır. Kod tabanını toplu güncellemek için bump-pydantic aracı işi kısaltır.
  • check_circle PydanticAI nedir, Pydantic'ten farkı nedir? PydanticAI, aynı ekibin geliştirdiği ayrı bir ajan çerçevesidir: model çağrılarını, araç kullanımını ve yanıt tiplerini Pydantic modelleriyle tanımlar. Pydantic ise yalnızca veri doğrulama kütüphanesidir. LLM yanıtını tip güvenli nesneye çevirmek için Pydantic tek başına yeter; araç çağrısı ve yeniden deneme mantığı gerekiyorsa PydanticAI devreye girer.