Gawain her Python değişkenine type annotation zorunlu kılıyor, ardından ty veya pyrefly ile doğruluyor

Gawain ne yapıyor

Gawain, Hacker News ana sayfasında öne çıkan, geliştirici matheuzgomes'un hazırladığı yeni bir open-source araç; Python değişkenlerinde, fonksiyon parametrelerinde, dönüş tiplerinde ve sınıf niteliklerinde type annotation zorunlu kılıyor — ardından bu annotation'ların tutarlı olduğunu doğrulamak için bir type checker çalıştırıyor.

Projenin GitHub README'sine göre mypy, Pyright, ty ve pyrefly gibi mevcut type checker'lar annotation'sız bir değişkenin tipini yalnızca çıkarım yoluyla belirliyor; ruff'un ANN kontrolleri ve flake8-annotations gibi linting kuralları ise yalnızca fonksiyonlarda annotation istiyor. Gawain daha da ileri giderek değişkenlerde ve sınıf niteliklerinde de annotation talep ediyor. Geliştiricinin motivasyonu oldukça netti: dict[str, Any] kullanımından hoşlanmamak.

Tek çalışmada iki kontrol

Gawain iki aşamada çalışıyor. Önce eksik annotation'ları tarayıp her birini bir kural koduyla raporluyor: annotation olmadan atanan değişkenler için GW001, annotation'sız parametreler için GW002, dönüş tipi eksik fonksiyonlar için GW003 ve sınıf gövdesinde hiç bildirilmemiş bir self.x ataması dahil annotation'sız sınıf nitelikleri için GW004. Bu varlık hataları düzeltilene kadar type checking atlanıyor.

Tüm annotation'lar yerleştirildikten sonra Gawain aynı dosyalar üzerinde bir type checker çalıştırıyor — varsayılan olarak ty ya da pyrefly — ve bulduklarını yazdırıyor; örneğin imzası int sözü verirken string döndüren bir fonksiyon gibi.

Ek kurallar Final[T] eksik sabitleri (GW010), tipsiz çıplak Final (GW011) ve bir annotation içinde geçen Any'yi (GW020) kapsıyor; ayrıca okunamayan dosyalar ile hatalı veya kullanılmayan bastırma (suppression) işlemleri için kodlar var. Tek tek satırlar # gawain: ignore[GW001] gibi bir yorumla susturulabiliyor.

Modlar, kurulum ve yapılandırma

Varsayılan mod obvious olarak adlandırılıyor: bir isim, değeri bariz bir tipe sahipse ve yeniden atanmıyorsa annotation'ı atlayabiliyor — count = 0 gibi bir literal, ids = [1, 2, 3] gibi literal'lerden oluşan bir container ya da user = User("ada") gibi bir constructor çağrısı. [tool.gawain] altında mode = "strict" ile etkinleştirilen strict mod ise her atamada annotation istiyor. Sabitler ayrı ele alınıyor; Final[T] olarak annotate edilmeyen her sabit GW010 tarafından işaretleniyor.

Kurulumda bir type checker extra olarak birlikte geliyor: uv tool install "gawain[ty]" veya pip install "gawain[pyrefly]". ty extra'sı ty 0.0.100 sürümünü sabitliyor; pyrefly extra'sı pyrefly 1.4.1'i sabitliyor ve ty'yi kurmuyor. Çıplak bir pip install gawain yalnızca gawain komutunu sağlıyor; bu komutun ardından PATH üzerinde bir type checker gerekiyor — ya da yalnızca annotation kontrollerini çalıştırmak için --no-types bayrağı. README, ty'nin beta aşamasında olduğunu ve tanılamalarının sürümler arasında değişebileceğini belirterek etkilenen projeleri pyrefly veya --no-types seçeneğine yönlendiriyor.

Gawain hiçbir şey raporlanmadığında 0, hata raporlandığında 1 ve kullanım hatasında ya da type checker çalıştırılamadığında 2 koduyla çıkıyor. Bir pre-commit hook'u var, ancak derlenmesi Rust 1.97 veya daha yeni bir sürüm gerektiriyor; --format json ise diğer araçlar için makine tarafından okunabilir çıktı üretiyor.

Performans

README'deki benchmark, CPython 3.14 standart kütüphanesi üzerinde — 1.847 dosya ve 974.586 satır — 30 çalıştırma boyunca obvious modundaki Gawain için medyan 0,46 saniye, strict modunda 0,36 saniye raporluyor. Yalnızca parametreleri ve dönüş değerlerini kontrol eden ruff'un ANN kuralları 0,35 saniye sürerken flake8-annotations 11,4 saniye sürdü. Geliştirici, bunun tek bir makinede — WSL2 altında bir AMD Ryzen 7 3700X — yapılan tek bir benchmark olduğuna ve Gawain'in --no-types ile çalıştırıldığına dikkat çekiyor. Gawain Python'u ruff_python_parser ile ayrıştırıyor; type checker'ları ise Astral (ty) ve Meta'dan (pyrefly) geliyor. Geliştiricinin itiraf ettiği üzere, aracın adı ise yalnızca Arthur efsanelerine duyulan bir sevginin yansıması.

Neden önemli

Python tipleme araçlarının çoğu iki noktadan birinde duruyor: sessizce tip çıkaran checker'lar ya da yalnızca fonksiyonları annotate eden linter'lar. Gawain'in iddiası, her yerde — modül düzeyi değişkenler ve sınıf nitelikleri dahil — açık tiplerin kodu okumayı kolaylaştırdığı ve bozmayı zorlaştırdığı, bir imzadan sızan Any'nin ise gelecekte patlayacak bir kusur olduğudur. Varlık kontrollerini gerçek bir type checker ile eşleştirerek ve kabaca ruff hızında çalışarak, her şeyi annotate etme tarzını CI'da benimsemeyi yeterince ucuz hale getiriyor. Zaten sıkı tipleme yapmaya kararlı ekipler bunun ruff ve flake8'un bıraktığı gerçek bir boşluğu doldurduğunu düşünebilir; çıkarıma güvenmekten memnun geliştiriciler ise README'nin neşeyle ifade ettiği gibi, uzak durmakta özgür.