Python Tip İpuçları: Fonksiyonlar, Listeler, Sözlükler ve Daha Fazlası İçin Annotation'lar

Tanımlayan, Dayatmayan Annotation'lar

Bir tip ipucu, bir ada — genellikle bir fonksiyon parametresine — iliştirdiğin bir nottur; "bu bir int olmalı," "bu string'lerden oluşan bir liste döndürür" vb. der. Python onları çalışma zamanında kontrol etmez. Bir int annote ettiğin yere string geçmek hata fırlatmaz. Editörün ve harici araçlar (mypy, pyright, VS Code'un Pylance'i üzerinden Pyright) ipuçlarını okur ve kod çalışmadan önce seni uyarır.

Mümkün olan en basit durum:

name: str, parametreyi annote eder. -> str, dönüş değerini annote eder. Her iki çağrı da çalışır. İkincisi yanlış — statik bir tip denetleyicisi bunu işaretlerdi — ama Python'un kendisi onu memnuniyetle işler çünkü 42 tesadüfen f"{...}" interpolasyonunu destekler.

Kritik zihinsel model bu: ipuçları, bir makinenin okuyabileceği belgelemedir. Çalışma zamanını değiştirmezler.

Neden Uğraşmalı?

Ne kadar hızlı kendilerini amorti ettiklerine göre sıralanmış üç somut kazanç:

1. Editörün akıllanır. Autocomplete doğru metotları gösterir, yeniden adlandırmalar doğru yayılır ve bir değişkenin üstüne gelmek tipini söyler.
2. Fonksiyon imzaları kendini anlatır hale gelir. def fetch(url: str, timeout: float = 5.0) -> dict:, okuyana tam olarak neyi geçireceğini ve ne alacağını söyler — gövdeyi okumaya gerek yok.
3. Tip denetleyicileri, kodu çalıştırmadan önce hataları yakalar. Bir projede mypy . çalıştırmak, birim testlerin sıkça kaçırdığı hataları yüzeye çıkarır — değer beklerken None dönmesi, liste beklerken dict kullanılması.

Bugün, yalnızca senin için, tek dosyalık bir script için ipuçlarını atla. Geri döneceğin ya da paylaşacağın her şey için, yazmaları için harcanan on beş saniye bir saat içinde kendini amorti eder.

Temel Yerleşik Tipler

Bunlar için import'a ihtiyacın yok:

Değişken annotation'ları (name: str = "Rosa") nadiren gereklidir — Python tipi sağ taraftan çıkarır. Bunları parametreler, dönüş tipleri ve çıkarılan tipin belirsiz olduğu ara sıra durumlar için sakla.

Hiçbir şey döndürmeyen fonksiyonlar -> None kullanır:

Listeler, Dict'ler, Tuple'lar ve Set'ler

Container'lar ikinci bir bilgiye ihtiyaç duyar — içerdikleri şey. Modern Python, yerleşik tipleri doğrudan subscript etmene izin verir:

Yüksek sesle okumak:

• list[float] — float'lardan oluşan bir liste.
• dict[str, int] — string anahtarları ve int değerleri olan bir dict.
• tuple[float, float] — tam olarak iki float'tan oluşan bir tuple.
• set[str] — string'lerden oluşan bir set.

list[...], dict[...] subscript söz dizimi Python 3.9 ve sonrasında çalışır. Daha eski kodda typing'den import edilen List, Dict, Tuple görürsün — aynı anlam, eski yazım.

Opsiyonel Değerler

"None olabilir" yaygındır. İki eşdeğer yazımı var — ikisi de uygun ama yenisi daha iyi okunur:

str | None, "bir string ya da None" anlamına gelir. | söz dizimi Python 3.10+'da çalışır. Eski kodda typing modülünden Optional[str] görürsün, aynı şeyi ifade eder.

-> str | None gören bir çağıran, sonucu kullanmadan önce None kontrolü yapması gerektiğini bilir — annotation'ın bütün amacı budur.

Union Tipleri: Bu Ya Da Şu

Bir değer birkaç tipten biri olabiliyorsa, | kullan:

İkiden fazla tip birleştirebilirsin. int | str | float, "bunların üçünden herhangi biri" anlamına gelir.

Fonksiyonların İçindeki Değişkenleri Annote Etmek

Çoğu zaman Python, yerel değişkenin tipini başlatıcısından çıkarır. Yalnızca şu durumlarda annotation'a ihtiyacın vardır:

• Container boş başlar ve tip denetleyicisi içeriğini tahmin edemez.
• Değer birkaç tip olabilir ve birine karar vermek istersin.
• İnsan bir okuyucuya niyeti belgelemek istersin.

typing.Any, kaçış kapısıdır — "bunu tam olarak annote etmek istemiyorum." Onu idareli kullan. Any suistimali, kalan tip ipuçlarını değersiz kılar.

Sınıfları Annote Etmek

Sınıf öznitelikleri ve metot imzaları, diğer fonksiyonlarla aynı şekilde annote edilir:

Dataclass'lar aslında tip annotation'ı gerektirir — @dataclass dekoratörü bunları __init__ ve __repr__ üretmek için okur. Annotation'ların çalışma zamanı davranışını etkilediği tek yer burasıdır.

Tuple'lar ve "Herhangi Uzunluk" Durumu

tuple[...]'ın yeni başlayanların kafasını karıştıran iki şekli var:

• tuple[float, float] — tam olarak iki float.
• tuple[int, ...] — herhangi sayıda int. ... (tip sisteminde gerçek bir söz dizimi öğesi) "ve sair" anlamına gelir.

Callable'lar ve Tip Takma Adları

Bir fonksiyon başka bir fonksiyon alıyor ya da döndürüyorsa, Callable kullan:

Callable[[int], int], "bir int alan ve bir int döndüren bir fonksiyon" anlamına gelir.

Bir annotation tekrar eder hale geldiğinde ona bir isim ver:

Takma ad sadece düz bir Python atamasıdır. Uzun formu kullanacağın her yerde, kısa ad iş görür.

Bir Tip Denetleyicisi Çalıştırmak

Python'un kendi yorumlayıcısı tip ipuçlarını yok sayar. Onları gerçekten denetlemek için bir tip denetleyicisi kur. mypy orijinalidir; pyright (VS Code'un Pylance'inin kullandığı) daha hızlıdır.

pip install mypy
mypy your_project/

İlk çalıştırma, fark etmediğin yerlerdeki hataları yüzeye çıkaracak. Bunları kademeli olarak çöz — ilerlemek için bir satırı sessizleştirmek gerektiğinde # type: ignore bunu yapar.

Modern IDE'ler sen düzenlerken tip kontrolünü sürekli yapar, yani çoğu geri bildirim sen kaydetmeden önce gelir.

Tip İpuçlarının Uymadığı Yerler

• Hızlı keşif script'leri. Annotation'lar, bir saat ömrü olan koda sürtünme ekler.
• Yoğun dinamik kod. Metaprogramlama, eklenti sistemleri ve benzeri kalıplar, tip sisteminin tanımlayabileceğini genelde aşar. Dış API'yi annote et, içerdekini gevşek bırak.
• Tipi olmayan üçüncü parti kütüphaneler. İçe aktardığın bir kütüphanenin tip bilgisi yoksa, Any senin kodunu da etkiler. Uygun — annote etmen gereken senin kodun değil.

Aradaki her şey için tip ipuçları, büyük getirisi olan küçük bir alışkanlıktır. Maliyeti her fonksiyon imzası için birkaç ekstra tuş. Getirisi daha az hata, daha kolay refactor ve kendini belgeleyen kod.

Sırada: Modüller ve Import'lar

Artık fonksiyon düzeyindeki tüm araçlara sahipsin — argümanlar, dekoratörler, tip ipuçları. Sırada Python'un kodu dosyalar arasında nasıl düzenlediğine bakacağız: modüller, paketler ve import sistemi.