Pandera 0.22: DataFrame Doğrulama Rehbe…

Q: Pandera şemasını mevcut bir DataFrame'den otomatik oluşturabilir miyim?

Evet, pa.infer_schema(df) ile başlangıç şeması üretebilirsiniz. schema.to_script() çıktıyı Python kodu olarak verir; bu kodu kopyalayıp iş kurallarınızla sıkılaştırırsınız. Genellikle observed minimum/maximum değerleri olduğu gibi kullanmak yerine iş mantığına göre sınırlamak gerekir.

Güncelleme: 21 Haziran 2026

Pandera, Pandas ve Polars DataFrame'leri için açık kaynaklı, statik tipli bir şema doğrulama kütüphanesidir; runtime sırasında sütun tipleri, değer aralıkları, eşsizlik ve iş kuralları gibi varsayımları otomatik olarak kontrol eder. Veri bilimi pipeline'larında "sessizce yanlış" sonuçların başlıca nedeni olan veri sözleşmesi ihlallerini, üretime taşınmadan ortaya çıkarır. Bu rehberde Pandera 0.22 ile sınıf tabanlı DataFrameModel kullanarak ETL akışlarınızı nasıl tip güvenli hâle getireceğinizi, Polars desteğini ve pytest entegrasyonunu adım adım göstereceğim.

Pandera 0.22 (Mayıs 2026), Pandas, Polars ve PySpark için tek bir şema sözdizimi sunar; backend'i değiştirmek için kodunuzun yalnızca pa.DataFrameModel import satırını güncellemeniz yeterlidir.
Sınıf tabanlı DataFrameModel yaklaşımı, Pydantic'e benzer ve mypy ile statik tip kontrolü için DataFrame[Schema] jeneriklerini destekler.
lazy=True doğrulama, ilk hatada durmak yerine tüm ihlalleri tek bir SchemaErrors nesnesinde toplar; CI/CD raporları için kritik.
Hipotez testleri (Hypothesis) sayesinde "ortalama gelir > ortalama gider" gibi istatistiksel kuralları şemanın parçası yapabilirsiniz.
pa.infer_schema() mevcut bir DataFrame'den başlangıç şeması üretir; ardından sıkılaştırarak retrospektif olarak validation eklersiniz.
Pytest entegrasyonu (@pa.check_types) ile pipeline fonksiyonlarınızın girdi ve çıktısı her testte otomatik doğrulanır.

Pandera nedir ve neden gerekli?

Pandera, başlangıçta Niels Bantilan tarafından 2019'da geliştirilen ve şu anda Union AI tarafından sürdürülen, DataFrame doğrulama için bir Python kütüphanesidir. Resmi tanımıyla "istatistiksel olarak tipli DataFrame'ler" sağlar: yani bir DataFrame'in yalnızca yapısını (sütun adları, dtype'lar) değil aynı zamanda istatistiksel özelliklerini (değer aralıkları, dağılımlar, eşsizlik koşulları) da bir sözleşme olarak ifade etmenize izin verir. Bu yaklaşım, yazılım mühendisliğindeki "design by contract" prensibinin veri bilimine uyarlanmış hâlidir.

Pratikte neden önemli? Çünkü Pandas, varsayılan olarak veri tipini ve değer geçerliliğini sessizce kabul eder. Örneğin bir CSV dosyasında beklenmeyen bir "N/A" string'i nümerik bir sütuna karışırsa, Pandas o sütunu object dtype'ına çevirir; aşağıdaki mean() hata değil, anlamsız bir sonuç üretir. Üretim pipeline'larında bu tür "sessiz başarısızlıklar", model performansının haftalarca düşmesine neden olabilir. Pandera, böyle bir veri girdiğinde SchemaError fırlatarak hatayı veriyi tüketen sisteme değil, verinin kendisine bağlar.

Veri kalitesi denetimleri uygulamadan önce ham veriyi düzgünce hazırlamak isterseniz, iyi bir başlangıç noktası olarak Python ile Pandas 3.0 veri temizleme rehberini öneririm. Pandera doğrulama, temizleme akışınızın son adımı olarak en iyi yerine oturur.

Kurulum ve 2026 versiyon notları

Pandera 0.22.0 (Mayıs 2026), bu yazının yazıldığı sırada güncel olan major sürümdür. Tek bir pandera paketi yerine artık backend'ler "extras" olarak ayrı dağıtılır; bu, üretim imajlarınızın gereksiz bağımlılık taşımasını engeller. Kurulum komutları:

pip install "pandera[pandas]==0.22.0"   # Pandas backend
pip install "pandera[polars]==0.22.0"   # Polars backend (Polars 1.x ile çalışır)
pip install "pandera[pyspark]==0.22.0"  # Apache Spark backend
pip install "pandera[hypotheses]"       # İstatistiksel hipotez testleri için

Python 3.10 ve üzeri zorunludur; Pandera 0.20'den itibaren Python 3.9 desteği kaldırılmıştır. Tip kontrolü için mypy 1.10+ ya da pyright 1.1.350+ tavsiye edilir. Pandera 0.22 ile gelen önemli değişiklikler:

DataFrameModel, eski SchemaModel sınıfının yerini tamamen aldı (SchemaModel artık DeprecationWarning üretir ve 1.0'da kaldırılacak).
Polars backend artık lazy frame'leri (pl.LazyFrame) yerel olarak doğruluyor.
Pydantic v2 ile tam entegrasyon: bir DataFrameModel'i bir BaseModel'in alanı olarak kullanabilirsiniz.
JSON Schema export'u (Schema.to_json_schema()) OpenAPI 3.1 uyumludur.

Resmi notları Pandera dokümantasyonundan teyit edebilirsiniz.

DataFrameModel ile şema tanımlama

Modern Pandera kullanımı, DataFrameModel sınıfından miras alarak şema tanımlamaya dayanır. Bu sözdizimi, Pydantic'e aşina olanlar için doğal hissedilir: her sınıf değişkeni bir sütunu tanımlar, tip anotasyonu dtype'ı, pa.Field(...) ise kısıtları ifade eder. Örnek olarak bir e-ticaret işlem şemasını ele alalım:

import pandas as pd
import pandera.pandas as pa
from pandera.typing import Series, DataFrame
from datetime import datetime

class IslemSemasi(pa.DataFrameModel):
    """E-ticaret işlem kayıtları için sözleşme."""
    islem_id: Series[str] = pa.Field(unique=True, str_matches=r"^TX-\d{8}$")
    musteri_id: Series[int] = pa.Field(ge=1)
    urun_kategorisi: Series[str] = pa.Field(isin=["elektronik", "giyim", "gida", "kitap"])
    tutar_tl: Series[float] = pa.Field(gt=0, le=1_000_000)
    iskonto_orani: Series[float] = pa.Field(ge=0, le=0.95, nullable=True)
    olusturulma_tarihi: Series[datetime] = pa.Field(le=datetime(2026, 12, 31))

    class Config:
        strict = True          # Şemada olmayan sütun varsa hata ver
        coerce = True          # Mümkünse dtype'ı otomatik dönüştür
        ordered = False        # Sütun sırası önemli değil

# Kullanım
ham_df = pd.read_csv("islemler.csv")
dogrulanmis_df: DataFrame[IslemSemasi] = IslemSemasi.validate(ham_df)

Burada birkaç noktanın altını çizmek istiyorum. str_matches kontrolü, işlem kimliğinin regex desenine uymasını zorunlu kılar; bu, basit bir dtype kontrolünün yakalayamayacağı bir format hatasıdır. isin, kategorik bir sütunun yalnızca beklenen değerleri içermesini garanti eder. Üretimde "Elektronik" (büyük E ile) gibi tipo'lar bu sayede modele ulaşmadan yakalanır. Son olarak coerce=True, "2026-01-15" gibi string tarihleri otomatik olarak datetime'a çevirir; pratikte CSV/JSON girdileri için olmazsa olmaz. Geçen sene tam da bu coerce ayarını unuttuğum için bir gecelik ETL job'u sessizce 40 bin satırı object dtype'ında bırakmıştı, sonraki sabah aggregasyonlar tuhaf sonuçlar verdiğinde işin kaynağına ulaşmam üç saatimi almıştı.

Doğrulama başarısız olduğunda Pandera, hangi satırın hangi kuralı ihlal ettiğini gösteren detaylı bir SchemaError fırlatır. Bu hata mesajı, geleneksel assert ifadelerinin aksine doğrudan loglara aktarılabilir ve hata izleme sistemlerine (Sentry, Datadog) gönderilebilir.

DataFrameSchema vs DataFrameModel: Hangisini seçmeli?

Pandera iki API sunar: nesne tabanlı DataFrameSchema ve sınıf tabanlı DataFrameModel. Hangisini ne zaman tercih edeceğiniz, kullanım senaryonuza bağlıdır. Aşağıdaki karşılaştırma tablosu pratik farkları özetliyor:

Özellik	DataFrameSchema	DataFrameModel
Tanım stili	Programatik (dict + Column objesi)	Bildirimsel (sınıf + tip anotasyonu)
Statik tip kontrolü (mypy)	Sınırlı	Tam destek (`DataFrame[Schema]`)
Şemanın dinamik üretimi	İdeal (loop'larla oluşturulabilir)	Zor (metaclass gerekir)
IDE otomatik tamamlama	Zayıf	Güçlü
Şema mirası ve genişletme	Manuel kopyalama	Doğal class inheritance
Pydantic v2 entegrasyonu	Yok	Var
Tipik kullanım alanı	Şema config dosyasından geliyor	Şema kodun parçası

Pratikte: uygulama kodunuzun parçası olan şemalar için her zaman DataFrameModel kullanın. Kod okunabilirliği, IDE desteği ve tip güvenliği belirgin biçimde daha iyi. Veri yöneticisi YAML'ından okunan ya da kullanıcının yüklediği şemalar için DataFrameSchema'nın programatik esnekliği daha uygundur. Pandera 0.21'den itibaren bir DataFrameModel'i .to_schema() ile DataFrameSchema'ya çevirebilir, böylece dinamik manipülasyon yapıp tekrar dönebilirsiniz.

Polars backend ile Pandera kullanımı

Pandera 0.18'den itibaren Polars için ilk sınıf destek sunar; 0.22 ile birlikte LazyFrame doğrulama da production-ready hâle geldi. Polars 1.x'in pandas'a göre 10x hızlı DataFrame işlemleri sayesinde büyük veri setlerinde anlamlı performans kazanımı elde edebilirsiniz; Pandera, bu hızı tip güvenliğinden ödün vermeden korumanıza izin verir.

Polars için import yolunun farklı olduğuna dikkat edin. Backend'i pandera.polars olarak değiştiriyoruz:

import polars as pl
import pandera.polars as pa
from pandera.typing.polars import Series, LazyFrame

class IslemSemasiPolars(pa.DataFrameModel):
    islem_id: Series[str] = pa.Field(unique=True)
    musteri_id: Series[int] = pa.Field(ge=1)
    tutar_tl: Series[float] = pa.Field(gt=0)

    class Config:
        strict = True

# LazyFrame ile uçtan uca tip güvenli pipeline
lazy_df: LazyFrame[IslemSemasiPolars] = (
    pl.scan_parquet("islemler.parquet")
    .filter(pl.col("tutar_tl") > 100)
    .pipe(IslemSemasiPolars.validate)   # Validation lazy plan'a eklenir
)

sonuc_df = lazy_df.collect()

Burada dikkat çeken nokta: validate çağrısı LazyFrame üzerinde materialize tetiklemez. Pandera, doğrulama mantığını Polars'ın sorgu planına ekler ve collect() çağrıldığında tek bir Arrow-tabanlı geçişte hem dönüşümleri hem doğrulamayı çalıştırır. Bu sayede milyonlarca satırlık ETL akışlarında bile validation overhead'i tipik olarak %5'in altında kalır. Apache Arrow tabanlı bellek modeli sayesinde Pandera, sütunları zero-copy okur.

Lazy validation ve hata raporlama

Varsayılan olarak Pandera, ilk başarısız kontrolde durur (SchemaError). Üretim akışlarında ise genellikle bütün ihlalleri görmek istersiniz; örneğin bir veri tedarikçisinden gelen dosyanın tüm sorunlarını tek bir hata raporunda toplamak için. Bu işlem lazy=True parametresi ile yapılır:

try:
    IslemSemasi.validate(ham_df, lazy=True)
except pa.errors.SchemaErrors as e:
    # e.failure_cases bir DataFrame'dir
    raporlar = e.failure_cases.groupby(["column", "check"]).size()
    print(raporlar)
    e.failure_cases.to_parquet("validation_errors.parquet")

SchemaErrors nesnesi iki kıymetli alan içerir: failure_cases her bir ihlali satır bazında listeler (sütun adı, başarısız olan check, hatalı değer, satır indeksi); schema_errors ise her şema kuralının kaç kez başarısız olduğunu özetler. Bu yapı, hata izleme dashboard'larına doğrudan beslenebilir.

CI/CD pipeline'larında benim tercih ettiğim pattern şudur: pull request açıldığında dummy veri üzerinde lazy=True ile doğrulama yapılır, başarısız vakalar bir Markdown tablosuna dönüştürülüp PR yorumuna eklenir. Bu, veri kontratı değişikliklerinin code review'a girmesini sağlar.

Hipotez testleri ile istatistiksel kurallar

Şema doğrulama yalnızca tip ve aralık kontrolünden ibaret değildir. Pandera'nın Hypothesis sınıfı, bir DataFrame üzerinde gerçek istatistiksel testler çalıştırmanıza izin verir; örneğin "kadın ve erkek müşterilerin ortalama harcaması arasında anlamlı fark yok" hipotezi. Bu özellik, üretim verisinde modelin eğitildiği dağılım varsayımının hâlâ geçerli olup olmadığını izlemek için son derece yararlıdır (data drift detection).

from pandera import Hypothesis
from scipy import stats

class MusteriSemasi(pa.DataFrameModel):
    cinsiyet: Series[str] = pa.Field(isin=["K", "E"])
    aylik_harcama: Series[float] = pa.Field(ge=0)

    @pa.dataframe_check
    def harcama_dagilimi_benzer(cls, df):
        kadin = df[df["cinsiyet"] == "K"]["aylik_harcama"]
        erkek = df[df["cinsiyet"] == "E"]["aylik_harcama"]
        _, p_degeri = stats.ttest_ind(kadin, erkek, equal_var=False)
        return p_degeri > 0.01   # %1 anlamlılık düzeyinde fark olmamalı

Bu yaklaşım, klasik veri doğrulamanın ötesinde, modelinizin varsayımlarının da CI/CD'de test edilmesini sağlar. Bantilan'ın orijinal Pandera makalesinde (SciPy 2020) de altı çizildiği gibi, "veri sözleşmesi" sadece şemadan değil, beklenen istatistiksel davranıştan da oluşur.

Mevcut DataFrame'den şema çıkarımı

Var olan bir kod tabanına Pandera eklemek, sıfırdan şema yazmaya kıyasla daha yorucu olabilir. Bu noktada pa.infer_schema() yardımcı olur: mevcut bir DataFrame'i inceleyip ilk taslak şemayı üretir. Çıktıyı saklayıp insan müdahalesiyle sıkılaştırırsınız.

import pandera.pandas as pa

ornek_df = pd.read_parquet("ornek_islemler.parquet")
taslak_sema = pa.infer_schema(ornek_df)

# Python kodu olarak dump et, version control'e ekleyebilirsiniz
with open("schemas/islem_schema.py", "w") as f:
    f.write(taslak_sema.to_script())

Çıkarılan şema; mevcut dtype'ları, observed min-max aralıklarını ve null oranlarını otomatik içerir. Pratikte ben şu adımları izliyorum: önce üretim verisinden bir hafta boyunca örnek topluyorum, ardından infer_schema ile taslak üretiyorum, son olarak iş bilgisini kullanarak kuralları daraltıyorum (örneğin "min değer 0.01" yerine "min değer 1.00" yazıyorum çünkü iş kuralı küçük bağışları yasaklıyor). Bu yaklaşımı veri ön işleme adımlarınız ile birlikte ele almak için Scikit-learn pipeline rehberi'ndeki ön işleme akışlarını referans alabilirsiniz.

pytest ve check_types entegrasyonu

Pandera'nın en güçlü özelliklerinden biri @pa.check_types dekoratörüdür: tip anotasyonlu fonksiyonların girdi ve çıktısını her çağrıda otomatik olarak doğrular. Bu, pytest fixture'larınızla birlikte kullanıldığında pipeline fonksiyonlarınızın hem unit hem integration testlerini "ücretsiz" hâle getirir.

from pandera.typing import DataFrame

@pa.check_types
def gunluk_ozet(df: DataFrame[IslemSemasi]) -> DataFrame[GunlukOzetSemasi]:
    return (
        df.groupby(df["olusturulma_tarihi"].dt.date)
          .agg(toplam=("tutar_tl", "sum"), adet=("islem_id", "count"))
          .reset_index()
    )

# pytest
def test_gunluk_ozet_sozlesmesi(islem_fixture):
    sonuc = gunluk_ozet(islem_fixture)
    assert sonuc["toplam"].sum() > 0

Pandera vs Great Expectations farkı nedir?

İki kütüphane de veri doğrulama yapar ama felsefeleri farklıdır. Great Expectations (GE) bir veri kalitesi platformudur: kendine ait bir docs sitesi (Data Docs), expectation suite versiyonlama, profil oluşturma UI'ı ve metadata store sunar. Pandera ise kod tabanlı bir kütüphanedir: tek yapısı şemadır, ek altyapı gerektirmez.

Hangisini seçeceğiniz büyük ölçüde ekibin yapısına bağlıdır. Veri mühendisliği ağırlıklı, dbt/Airflow odaklı ekipler için Great Expectations'ın platform tarafı caziptir; ML/data science ağırlıklı ekipler için Pandera'nın kodun parçası olan, statik tipli yaklaşımı genellikle daha üretkendir. Bu konuda Pandera GitHub tartışmalarında sürdürücülerin verdiği bir özet şudur: "Pandera, fonksiyon imzasının parçasıdır; Great Expectations, ayrı bir sistemdir."

Karma yaklaşım da mümkündür: kritik tablolar için Great Expectations'ın data docs özelliğini kullanırken, in-memory transformasyonlar için Pandera ile check_types dekoratörünü kullanabilirsiniz. Python ile aykırı değer tespiti rehberi'ndeki yaklaşımları Pandera'nın Hypothesis kontrolleri ile birleştirirseniz, üretim verisindeki anomalileri akış üzerinde yakalayan bir yapı kurmuş olursunuz.

Üretim için pratik öneriler

Son üç yılda farklı boyutlardaki ekiplerle Pandera'yı üretime aldıktan sonra öğrendiğim birkaç pratik tavsiye:

Şemaları ayrı bir modülde saklayın (örn. app/schemas/). Bu modül hiçbir iş mantığı içermemeli; sadece DataFrameModel sınıfları olmalı. Böylece şema değişikliği bir code review'da net biçimde görünür.
"Strict" mod varsayılan olsun. Config.strict = True ile beklenmedik sütunlar hata verir. Bu, upstream'deki sessiz schema değişikliklerini erken yakalar.
Production'da lazy, geliştirmede strict. Üretim ETL'lerinde lazy=True kullanın ve hataları metric olarak yayınlayın; geliştirme ortamında ilk hatada durması daha hızlı geri bildirim sağlar.
Şemaları semver gibi versiyonlayın. Breaking değişiklikler downstream consumer'ları kırar; bir IslemSemasiV2 sınıfı oluşturmak, eski tüketicileri kırmadan migrate olmanıza izin verir.

Sıkça sorulan sorular

Pandera Polars'ı destekliyor mu?

Evet. Pandera 0.18'den itibaren Polars için ilk sınıf destek vardır; 0.22 ile birlikte pl.LazyFrame doğrulaması da production-ready hâle gelmiştir. Import yolu pandera.polars olarak değişir, ancak şema sözdizimi Pandas backend'i ile birebir aynıdır.

Pandera ile Pydantic arasındaki fark nedir?

Pydantic, tekil Python nesnelerini (dict, dataclass benzeri) doğrular; Pandera, DataFrame gibi sütun-tabanlı tablo veri yapılarını doğrular. Yani milyonlarca satırlı bir Parquet dosyasını satır satır Pydantic ile doğrulamak verimsiz olurdu; Pandera vectorized check'lerle aynı işi 100x+ hızla yapar. Pandera 0.22, Pydantic v2 ile entegre çalışır, böylece bir API payload'unun bir alanı Pandera şemalı DataFrame olabilir.

Pandera doğrulama performansı ne kadar yavaşlatır?

Tipik üretim yüklerinde overhead %2-10 arasındadır; çoğu check vectorized (NumPy/Polars seviyesinde) çalışır. Çok sıcak yollarda PANDERA_VALIDATION_ENABLED=false ortam değişkeniyle global olarak devre dışı bırakabilir, check_types dekoratörünü kodda bırakabilirsiniz. lazy=True modu tüm DataFrame'i bir kez tarar; lazy=False ilk hatada durduğundan daha hızlıdır.

Pandera şemasını mevcut bir DataFrame'den otomatik oluşturabilir miyim?

Evet, pa.infer_schema(df) ile başlangıç şeması üretebilirsiniz. schema.to_script() çıktıyı Python kodu olarak verir; bu kodu kopyalayıp iş kurallarınızla sıkılaştırırsınız. Genellikle observed minimum/maximum değerleri olduğu gibi kullanmak yerine iş mantığına göre sınırlamak gerekir.

Pandera hangi Python sürümlerini destekliyor?

Pandera 0.22, Python 3.10, 3.11, 3.12 ve 3.13'ü resmi olarak destekler. Python 3.9 desteği 0.20 sürümünde kaldırılmıştır. Tip anotasyonları için mypy 1.10+ veya pyright 1.1.350+ tavsiye edilir.