Python Type Hints ve mypy

Giriş

Python dinamik tipli bir dildir; ancak PEP 484 ile gelen type hints, geliştirme sürecinde hata yakalama ve kod okunabilirliği için güçlü bir araç haline geldi. mypy, pyright ve pyre gibi statik analiz araçları, çalışma zamanına girmeden tip uyumsuzluklarını raporlar.

Bu rehberde temel annotation sözdizimi, collections.abc tipleri, Protocol ile yapısal alt tipleme, Generic container'lar ve mypy yapılandırmasını inceliyoruz. Tip ipuçları çalışma zamanında zorlanmaz; isteğe bağlı olarak pydantic veya beartype ile runtime doğrulama eklenebilir.

Temel Type Hints

Fonksiyon parametreleri ve dönüş değerleri annotate edilir: def greet(name: str) -> str:. Değişken annotation'ı x: int = 0 şeklindedir. Python 3.10+ ile list[str], dict[str, int] yerleşik generic sözdizimi kullanılır; eski kodda List, Dict from typing import edilir.

Optional[str] ve str | None (3.10+) nullable tipleri ifade eder. Union[int, str] birden fazla tip kabul eder. Any tip kontrolünü devre dışı bırakır; mümkün olduğunca kaçınılmalıdır.

from typing import Optional

def find_user(user_id: int) -> Optional[dict[str, str]]:
    if user_id < 0:
        return None
    return {"id": str(user_id), "name": "Ali"}

Protocol ve Yapısal Alt Tipleme

Protocol, duck typing'i statik analize taşır: belirli metodlara sahip herhangi bir sınıf protokolü karşılar, kalıtım gerekmez. Bu, testlerde sahte nesne üretmeyi ve gevşek bağlı tasarımı kolaylaştırır.

@runtime_checkable ile isinstance(obj, Readable) çalışma zamanında kontrol edilebilir. Protocol'ler ABC'ye göre daha esnektir; üçüncü parti kütüphane sınıflarını wrap etmeden tip güvenliği sağlar.

from typing import Protocol

class Readable(Protocol):
    def read(self, n: int = -1) -> bytes: ...

def load(source: Readable) -> bytes:
    return source.read()

Generic ve TypeVar

Generic sınıflar ve fonksiyonlar tip parametresi taşır: class Stack[T]: ... TypeVar ile kısıtlama yapılabilir: T = TypeVar('T', bound=Comparable). ParamSpec ve TypeVarTuple (3.11+) decorator ve callback tiplerini daha doğru ifade eder.

mypy generic kullanımda invariant container kurallarını uygular: list[Dog] list[Animal]'a atanamaz. Covariance gerekiyorsa Sequence[Animal] tercih edilir. Bu ayrım, koleksiyon API'lerinde sık karşılaşılan tip hatalarının kaynağıdır.

list[T], dict[K, V]: generic koleksiyonlar
TypeVar: tip parametresi ve bound
Protocol: yapısal arayüz
TypedDict: sözlük şekli tanımı

mypy Yapılandırması

pyproject.toml veya mypy.ini içinde strictness ayarları tanımlanır. disallow_untyped_defs tüm fonksiyonlarda tip zorunlu kılar. ignore_missing_imports üçüncü parti stubs eksikliğinde geçici çözümdür; types-requests gibi stubs paketleri tercih edilir.

mypy --strict en katı moddur; mevcut kod tabanına kademeli geçiş için modül modül # mypy: disable-error-code veya per-file overrides kullanılır. pre-commit hook ile her commit'te mypy çalıştırmak regresyonu önler.

# pyproject.toml
[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
disallow_untyped_defs = true

TypedDict, Literal ve overload

TypedDict sabit anahtarlı sözlüklerin şeklini tanımlar; API yanıt modelleri için hafif alternatiftir. Literal['GET', 'POST'] sabit string değer kümelerini ifade eder. @overload ile aynı fonksiyonun farklı imzaları statik analize bildirilir.

Final ve ClassVar sınıf ve modül düzeyinde değişmezlik belirtir. NewType ile marka tipi oluşturulur: UserId = NewType('UserId', int) ile int ile karışması önlenir.

from typing import TypedDict, Literal

class UserDict(TypedDict):
    id: int
    name: str

def request(method: Literal["GET", "POST"], url: str) -> bytes: ...

Pratik Entegrasyon

FastAPI ve Pydantic runtime'da tip doğrulaması yapar; mypy ile çift katmanlı güvenlik sağlanır. SQLAlchemy 2.0 Mapped[T] ile ORM modelleri tip güvenli hale gelir. pytest ile mypy plugin'i tip hatalarını test süitine dahil eder.

Kademeli adoption: önce public API'leri tipleyin, sonra iç modüllere yayın. types-* stubs eksik paketlerde py.typed işaretli kütüphaneler mypy uyumluluğunu artırır. Ruff'un ANN kuralları eksik annotation'ları lint eder.

Public API'den başlayarak tipleme yayın
mypy'yi CI ve pre-commit'e ekleyin
types-* stubs paketlerini kullanın
Protocol ile test double'ları kolaylaştırın

Sonuç

Type hints Python'u yavaşlatmaz; IDE otomatik tamamlama, refactor güveni ve erken hata tespiti sağlar. mypy ile birlikte kullanıldığında dinamik dilin esnekliği ile statik dilin güvenliği arasında denge kurulur.

Protocol ve Generic gibi ileri özellikler, büyük kod tabanlarında sürdürülebilirliği artırır. Tip sistemini takım standardı haline getirmek, onboarding süresini kısaltır ve production bug oranını düşürür.

Veri Kullanimi Bildirimi