Pyright Rehberi: Python Kodu için Hızlı Statik Tür Denetimi

Tür ipuçları, Python kodunu anlamayı ve bakımını kolaylaştırır. Ama işin püf noktası şu: İpuçları tek başına hataları yakalamaz. Deklare ettiğiniz türlere kodunuzun gerçekten uyup uymadığını doğrulamak için bir tür denetleyiciye ihtiyacınız vardır.

Üretimde hem Mypy hem de Pyright kullandım. Pyright'ın hız avantajı özellikle geliştirme sırasında belirgindir. Tür hataları, kaydettikten sonra değil, siz yazarken görünür. Büyük kod tabanlarında bu daha hızlı geri bildirim döngüsü gerçekten fark yaratır.

Bu eğitim, Pyright'ı etkili biçimde kullanmaya başlamak için gereken her şeyi kapsar. Nasıl kuracağınızı, projeniz için nasıl yapılandıracağınızı ve VS Code ile nasıl entegre edeceğinizi göstereceğim. Ayrıca Pyright ile Mypy arasındaki farkları da irdeleyeceğim.

Pyright Nedir?

Pyright, Microsoft tarafından geliştirilen bir Python statik tür denetleyicisidir. Kodunuzu okur, tür açıklamalarını analiz eder ve türler eşleşmediğinde hataları raporlar. Kod çalıştığında hataları yakalayan çalışma zamanı kontrollerinin aksine, statik analiz hataları bir şey çalıştırmadan önce yakalar.

Çoğu Python aracı Python ile yazılmışken, Pyright TypeScript ile yazılmıştır ve Node.js üzerinde çalışır. Bir Python aracı için tuhaf bir seçim, değil mi? Ama Pyright'ı bu kadar hızlı yapan da budur. V8 JavaScript motoru, CPython'dan çok daha hızlı çalışır.

Pyright ile iki şekilde karşılaşırsınız. Birleştirmelerden önce tür hatalarını yakalamak için CI/CD hatlarında komut satırı aracı olarak çalıştırabilirsiniz. Ya da farkında olmadan zaten kullanıyor olabilirsiniz. VS Code için Microsoft'un Python uzantısı olan Pylance'ı çalıştırır. Tür hatalarının altındaki kırmızı dalgalı çizgiler mi? Bu, perde arkasında çalışan Pyright'tır.

Araç, Python standart kitaplığı ve yaygın paketler için paketlenmiş tür kütükleriyle gelir. os, json veya typing kullanan kodu denetlemek için ekstra bir şey kurmanız gerekmez. Üçüncü taraf paketler için Pyright, typeshed'den topluluk tarafından bakım yapılan kütükleri veya ayrıca kurduğunuz paket özelindeki kütükleri kullanır.

Pyright Nasıl Kurulur

Şimdi Pyright'ı sisteminizde çalıştıralım. İki kurulum seçeneğiniz var: npm (yerel yaklaşım) veya pip (Python sarmalayıcı).

npm ile Pyright kurulumu

Önerilen kurulum, Pyright Node.js üzerinde çalıştığı için npm kullanır. Node.js sürümünüzün 14.0.0 veya üzeri olması gerekir.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyrightAltyapı:

Hızlı kontroller için global, sürümü sabitlemek istediğim projeler için yerel kurulum kullanırım. npx yaklaşımı, global paketlerinize ekleme yapmadan tek seferlik işler için kullanışlıdır.

Python sarmalayıcı ile Pyright kurulumu

Ekibiniz tamamen Python ile çalışıyor ve araç zincirinde Node.js istemiyorsa bir PyPI sarmalayıcısı mevcut:

# Standard installation
pip install pyright

# Recommended: includes Node.js automatically
pip install pyright[nodejs]Altyapı:

Sarmalayıcı, sisteminizde Node.js olup olmadığını denetler. Eksikse sarmalayıcı otomatik olarak bağımsız bir sürüm indirir. [nodejs] eklentisi, varsayılandan daha güvenilir bir indirme yöntemi kullanır.

Aklınızda bulunsun, bazı ödünler vardır. İlk çalıştırmada bağımlılıklar indirilirken daha uzun sürer. Ağ erişimi kısıtlı CI ortamlarında başarısız olabilir. Ayrıca PyPI sürümü bazen npm sürümlerinin birkaç gün gerisinden gelir.

Çoğu Python ekibi için sarmalayıcı gayet iyi çalışır. Ancak sorun yaşarsanız npm kurulumuna geri dönün. Daha güvenilirdir.

Bir Python Projesinde Pyright Çalıştırma

Kurulum tamamlandıktan sonra Pyright'ı çalıştırmak basittir. Proje dizininize gidin ve şunu çalıştırın:

pyrightAltyapı:

Hepsi bu. Pyright Python dosyalarını tarar, analiz eder ve bulduğu tür hatalarını raporlar. Karmaşık bir kurulum gerekmez.

Pyright varsayılan olarak neleri denetler

Pyright neye bakar? Herhangi bir yapılandırma olmadan birkaç denetim gerçekleştirir. Gerçek kullanım ile eşleşen tür açıklamalarını doğrular. Tanımsız değişkenleri ve erişilemeyen kodu yakalar. İçe aktarmaları doğru şekilde doğrular. Bir tamsayı beklenirken bir dizge geçirilmesi gibi bariz tür uyumsuzluklarını işaretler.

Hataları olan bir projeden örnek çıktı:

/src/utils.py:12:15 - error: Argument of type "str" cannot be assigned 
   to parameter "count" of type "int" in function "process_items"
   "str" is not assignable to "int" (reportArgumentType)
/src/main.py:45:9 - error: "user" is possibly unbound (reportPossiblyUnbound)
2 errors, 0 warnings, 0 informationsAltyapı:

Her hata dosya yolunu, satır ve sütunu ve bir açıklamayı gösterir. Parantez içindeki kural adı (ör. reportArgumentType) hatayı hangi denetimin tetiklediğini tam olarak söyler. Bu, belirli kuralları bastırmak istediğinizde önemlidir. Bunu birazdan ele alacağız.

Çıkış kodlarını anlama

Pyright, sonuça bağlı olarak farklı çıkış kodları döndürür:

CI hatlarında genellikle 1 çıkış kodunda derlemenin başarısız olmasını istersiniz. 2-4 kodları, aracın kendisiyle ilgili bir sorun olduğunu, kodunuzla değil, gösterir.

Pyright'ı Yapılandırma

Pyright kutudan çıktığı gibi çalışsa da gerçek projeler özelleştirme ister. Hangi dosyaların denetleneceğini, hedef Python sürümünü ve analizin ne kadar sıkı olacağını belirtmek istersiniz. Temel yapılandırma seçeneklerine bakalım.

Tür denetim modları

Pyright dört sıkılık düzeyi sunar. Seçeceğiniz mod, kaç kuralın etkinleşeceğini belirler.

Hangi modu seçmelisiniz? Yeni projeler için standard mod ile başlayın. Sizi hatalara boğmadan gerçek hataları yakalar. Eski kodla mı çalışıyorsunuz? Basic mod, yazım kurallarını kademeli benimsediğinizde daha iyi çalışır. Strict modu ise maksimum güvenlik istediğiniz kütüphaneler ve kritik altyapı için saklayın.

Uyarı: standard'dan strict'e geçiş ciddi bir sıçramadır. Strict mod, tüm işlev parametreleri ve dönüş değerleri için tür açıklamalarını zorunlu kılmak da dahil yaklaşık 30 ek kural etkinleştirir. Geçiş yaptığınızda raporlanan hatalarda 10 kat artış bekleyin. Bunu zor yoldan öğrendim.

Strict mod eksiksiz tür açıklamaları gerektirir. Görsel: Yazar

Yapılandırma dosyaları

Pyright yapılandırmayı pyrightconfig.json veya pyproject.toml dosyasından okur. Her ikisi de varsa pyrightconfig.json önceliklidir.

İşte en küçük pyrightconfig.json örneği:

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.venv"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}Altyapı:

pyproject.toml içindeki eşdeğeri:

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", "**/.venv"]
pythonVersion = "3.12"
typeCheckingMode = "standard"Altyapı:

Yapılandırma dosyası Pyright davranışını kontrol eder. Görsel: Yazar.

Birçok kişiyi ters köşe yapan kritik bir detay: exclude değerini elle tanımlarsanız bu, varsayılanları tamamen değiştirir. Her zaman node_modules, __pycache__ ve sanal ortamınızı özel dışlama kalıplarınıza ekleyin. Aksi halde Pyright bağımlılıklarınıza da analiz uygular ve büyük yavaşlamalara neden olur. Bana güvenin, tür denetimi için 10 dakika beklemek istemezsiniz.

Sanal ortam yapılandırması

Pyright kurulu paketlerinizi nasıl bulur? Nereye bakacağını söylemeniz gerekir. Bunu venvPath ve venv ile yapılandırın:

{
  "venvPath": ".",
  "venv": ".venv"
}Altyapı:

Bu, Pyright'a paketleri ./.venv içinde aramasını söyler. Farklı bir sanal ortam konumu kullanıyorsanız buna göre ayarlayın. Bunu yapmazsanız Pyright kurulu bağımlılıklarınızı bulamaz ve her şey için eksik içe aktarma hataları raporlar.

Teşhisleri bastırma

Bazen Pyright teknik olarak haklıdır ama yine de belirli hataları susturmanız gerekir. Belki eski kodla çalışıyorsunuz ya da belirli bir durumda tür denetleyiciden daha iyi biliyorsunuz. Hataları üç düzeyde bastırabilirsiniz.

Yapılandırma düzeyinde bastırma

Kuralları global olarak devre dışı bırakın:

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}Altyapı:

Dosya düzeyinde bastırma

Dosyanın en üstüne bir yorum ekleyin:

# pyright: basic
# pyright: reportPrivateUsage=falseAltyapı:

Satır düzeyinde bastırma

Tek bir satırı bastırın:

x: int = "hello"  # type: ignore
x: int = "hello"  # pyright: ignore
x: int = "hello"  # pyright: ignore[reportAssignmentType]Altyapı:

Belirli kural sözdizimi ([reportAssignmentType]), aynı satırda diğerlerini devre dışı bırakmadan yalnızca bir denetimi susturmak istediğinizde kullanışlıdır.

Yapılandırmayı ele aldığımıza göre Pyright'ın geliştirme ortamınızla nasıl entegre olduğuna bakalım.

VS Code ve IDE'lerde Pyright

Çoğu Python geliştiricisi gibiyseniz Pyright'ı komut satırından çok Pylance üzerinden deneyimleyeceksiniz. Bu ilişkiyi anlamak, düzenleyicinizi doğru yapılandırmanıza ve yaygın sorunlardan kaçınmanıza yardımcı olur.

Pyright vs. Pylance

Pylance, Pyright'ın tür denetim motorunu paketleyen Microsoft'un VS Code uzantısıdır. Pylance'ı kurduğunuzda Pyright'ı otomatik olarak edinirsiniz. Ancak Pylance, açık kaynak Pyright'ta olmayan özellikler ekler:

• Anlamsal vurgulama: değişkenler türlerine göre renklendirilir
• Gelişmiş otomatik içe aktarma: daha akıllı içe aktarma önerileri
• Kod gezinme: çalışma alanınız genelinde "Tüm Başvuruları Bul"

Bu özellikler kapalı kaynaktır ve yalnızca VS Code'da mevcuttur. Neovim, Emacs veya başka bir düzenleyici kullanıyorsanız bu ekstralar olmadan çekirdek Pyright işlevselliğini edinirsiniz.

Pylance, tür hatalarını düzenleyicide vurgular. Görsel: Yazar.

Gerekli VS Code ayarları

Pylance'ı VS Code ayarlarıyla yapılandırın:

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "standard",
  "python.analysis.diagnosticMode": "openFilesOnly"
}Altyapı:

diagnosticMode ayarı performansı etkiler. "openFilesOnly" yalnızca açık dosyaları analiz eder. "workspace" her şeyi analiz eder ama daha fazla bellek ve CPU kullanır.

Yaygın yapılandırma tuzakları

Yorumlayıcı seçimi önemlidir. Pylance, kurulu paketleri bulmak için seçili Python yorumlayıcınızı kullanır. Kurulu olduğunu bildiğiniz paketler için birdenbire hatalar görünürse VS Code durum çubuğunda doğru yorumlayıcının seçili olduğunu kontrol edin.

Yorumlayıcı seçimi, paket keşif yollarını etkiler. Görsel: Yazar.

CLI ve Pylance varsayılanları farklıdır. Pylance, typeCheckingMode'u "off" olarak varsayarken CLI "standard"'ı varsayar. Pylance ayrıca arama yollarına otomatik olarak src ekler; CLI eklemez. Düzenleyiciniz ve CI arasında tutarlı davranış için tüm seçenekleri açıkça pyproject.toml içinde ayarlayın.

"Griye dönen kod" olgusu. Pylance, tür analizine göre erişilemeyen kodu griye boyar. Kod beklenmedik şekilde gri görünürse hemen öncesinde çağrılan işlevi kontrol edin. NoReturn döndüğü yazılan bir işlev, sonrasındaki her şeyin erişilemez görünmesine neden olur.

Pyright vs. Mypy: Hangisini Ne Zaman Kullanmalı?

Şunu merak ediyor olabilirsiniz: Pyright mı kullanmalıyım yoksa Mypy ile mi devam etmeliyim? Her iki araç da üretime hazırdır ve seçiminiz iş akışınıza ve gereksinimlerinize bağlıdır. Temel farkları özetleyeyim.

Hız ve tepki verme

Pyright, tam proje taramalarında yaklaşık 3-5 kat daha hızlıdır ve artımlı denetimlerde neredeyse anlıktır. Bu, en çok anlık geri bildirim istediğiniz geliştirme sırasında önemlidir.

Mypy'nin performansı iyileştiren bir arka plan modu (dmypy) vardır, ancak yine de daha yavaştır ve bazen yeniden başlatma gerektiren önbellekleme sorunları yaşar.

Tür çıkarımı farkları

İşler burada ilginçleşiyor. Araçlar türleri farklı çıkarır. Şu koda bakın:

coordinates = (10, 20)Altyapı:

Pyright, demetler değişmez olduğu için tuple[Literal[10], Literal[20]] şeklinde, tam değerleri koruyarak çıkarım yapar. Mypy ise tuple[int, int] çıkarır ve genel tiplere genişletir.

Pyright'ın yaklaşımı daha fazla hatayı yakalar ancak bazen işlevler genel tipler beklediğinde sürtüşme yaratır. Bu pratikte nadiren önemlidir çünkü Literal[10] , int'in geçerli bir alt türüdür.

Açıklamasız kod analizi

Bu, en büyük pratik fark ve eski kod tabanları için oyunun kurallarını değiştirir. Mypy, varsayılan olarak tür açıklaması olmayan işlevleri atlar. Pyright ise yine de analiz eder ve tür ipuçları olmadan bile bariz hataları yakalar.

Tür açıklamaları seyrek olan eski kod tabanlarında Pyright, tanımsız değişkenleri ve imkânsız metot çağrılarını yakalayan güçlü bir linter gibi davranır. Mypy bu işlevleri "dinamik" kabul eder ve yok sayar.

Eklenti desteği

Mypy, Django ve SQLAlchemy gibi çerçeveler için eklentileri destekler. Bu eklentiler ORM sihrini anlar ve dinamik olarak üretilen öznitelikler için doğru türler sağlar.

Pyright'ın bir eklenti sistemi yoktur. Tamamen tür kütüklerine dayanır. 2026'da çoğu büyük kütüphanenin yüksek kaliteli kütükleri olduğundan bu, eskisi kadar önemli değil. Ancak ağır metaprogramlama kullanan bir çerçeve kullanıyorsanız Pyright'a taahhüt edmeden önce iyi kütükler olup olmadığını kontrol edin.

Geliştirme sırasında anlık geri bildirim için Pylance (Pyright) kullanın ve projeniz çerçeve eklentileri kullanıyorsa CI'da hem Pyright hem de Mypy çalıştırmayı düşünün.

Pyright Kullanırken Yaygın Sorunlar

Pyright beklenmedik hatalar raporladığında, neden genellikle şu sorunlardan biridir.

Eksik tür kütükleri

Bu hatayı gördünüz mü? Pyright, bir paket için tür bilgisi bulamadığında şikayet eder:

Import "requests" could not be resolved (reportMissingImports)Altyapı:

Eksik kütükler içe aktarma uyarı hatalarını tetikler. Görsel: Yazar.

Önce paketin sanal ortamınıza kurulu olduğundan ve Pyright'ın onu nerede bulacağını bildiğinden emin olun (venvPath ve venv ayarlarını daha önce ele almıştık).

Paket kurulu ama tür bilgisi yoksa topluluk kütüklerini kurun:

pip install types-requests types-PyYAML types-redisAltyapı:

Kütüğü olmayan paketler için iki seçeneğiniz var. Yapılandırmanızda "reportMissingTypeStubs": "none" ile uyarıyı kapatabilir veya kendiniz taslak kütük üretebilirsiniz:

pyright --createstub some_packageAltyapı:

Bu, kullandığınız yöntemlerle doldurabileceğiniz bir iskelet .pyi dosyası oluşturur.

Pre-commit kanca hataları

Pyright yerelde çalışıyor da pre-commit kancalarında mı başarısız oluyor? Sorun genellikle ortam izolasyonudur. Pre-commit, proje paketlerinizi göremeyen izole ortamlarda kancaları çalıştırır.

Bunu kancayı sanal ortamınıza işaret ederek düzeltin:

repos:
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.408
    hooks:
      - id: pyright
        args: ["--venvpath", ".", "--venv", ".venv"]Altyapı:

Beklenmeyen strict mod hataları

Strict modu etkinleştirdiniz ve birdenbire binlerce hata mı görüyorsunuz? Panik yapmayın. Bu normaldir. Strict mod eksiksiz tür açıklamaları ister. Basic veya standard modla başlayın, açıklamaları kademeli olarak ekleyin ve strict'i yalnızca tamamen yazımlanmış modüllerde etkinleştirin.

Eski kodu esnek bir modda tutmak için dosya başına yorumları kullanın:

# pyright: basicAltyapı:

Bu, yeni kodda sıkı denetimi zorunlu kılarken eski kodu kademeli olarak taşımanıza olanak tanır.

Sorun gidermenin ötesinde, baştan itibaren Pyright deneyiminizi daha sorunsuz hale getirecek bazı stratejiler burada.

Pyright Kullanımı için En İyi Uygulamalar

Farklı projelerde Pyright ile çalıştıktan sonra benimsemeyi kolaylaştıran birkaç şey öğrendim. Bu kodlama en iyi uygulamalarını benimsemek, tür denetiminin engel değil yardımcı olarak kalmasını sağlar.

Standard modla başlayın. Daha önce tartıştığımız gibi, eksiksiz açıklamalar gerektirmeden gerçek hataları yakalar. Kuralları her zaman daha sonra sıkılaştırabilirsiniz.

Pyright sürümünüzü sabitleyin. Pyright sık sürüm çıkarır ve yeni sürümler bazen daha önce geçen kodu işaretler. CI'da sabitlenmemiş bir pip install pyright, hafta sonu sürümlerinden pazartesi sabahı derleme hatalarına neden olabilir. Başıma geldi. Hoş değil.

[tool.pyright]
# In pyproject.toml
pythonVersion = "3.12"Altyapı:

# In requirements-dev.txt
pyright==1.1.408Altyapı:

Hataları kademeli olarak düzeltin. 10.000 hatayı bir anda yok etmeye çalışmayın. strict dizisini yalnızca belirli dizinlerde sıkı denetimi zorlamak için kullanın:

{
  "typeCheckingMode": "standard",
  "strict": ["src/core", "src/api"]
}Altyapı:

Yapılandırma dosyalarını erken kullanın. Küçük projeler için bile açık yapılandırma sürprizleri önler. Python sürümünüzü, sanal ortam yolunuzu ve seçtiğiniz sıkılık düzeyini belgelemek için beş dakikanızı ayırın. Gelecekteki siz size teşekkür edecek.

Hemen mükemmelliği hedeflemeyin. İlk etapta # pyright: ignore'ı cömertçe kullanın. Bu, teknik borcu görünür biçimde işaretler; böylece ilerlemeyi engellemek yerine zamanla temizleyebilirsiniz. Yeni araçları benimserken mükemmel, iyinin düşmanıdır.