Fase 2 · Type Hints & Pydantic

Python Typing Documentation

Konsep dasar sistem tipe Python: apa yang dilakukan type hint, apa yang tidak, dan bagaimana cara membacanya.

Sumber asli typing.python.org Resmi Rangkuman ~6 menit baca

Intisari

Type hint adalah anotasi, bukan pemaksaan. Python mengabaikannya saat runtime; type checker yang membacanya.
Yang penting bukan “semua harus dianotasi”, tapi batas fungsi publik harus dianotasi.
Sistem tipe Python bersifat gradual — kamu boleh mengetikkan sebagian kode saja.
Any mematikan pengecekan. Pakai sesedikit mungkin; itu lubang di jaring pengaman.
Semua ekosistem AI Python (FastAPI, SDK Anthropic, Pydantic) dibangun di atas type hint — ini bukan opsional lagi.

Apa yang sebenarnya dilakukan type hint

def cari(query: str, top_k: int = 5) -> list[Dokumen]: ...

Anotasi itu memberi tiga hal, dan tidak memberi satu hal:

Memberi	Tidak memberi
Pengecekan statis (mypy menemukan bug sebelum kode jalan)	Pengecekan saat runtime. `cari(42)` tetap jalan sampai meledak sendiri di dalam.
Autocomplete dan refactor yang aman di editor
Dokumentasi yang tidak bisa basi

Yang memvalidasi saat runtime adalah Pydantic. Type hint memberi skema; Pydantic memakai skema itu untuk benar-benar memeriksa data. Itulah kenapa dua topik ini ada di fase yang sama.

Gradual typing

Kamu tidak harus mengetikkan seluruh codebase sekaligus. Python memakai gradual typing: bagian yang punya anotasi diperiksa, bagian yang tidak dianggap Any dan dilewatkan. Strategi yang masuk akal:

Anotasi semua fungsi publik — yang dipanggil dari modul lain
Anotasi model data (Pydantic, dataclass)
Fungsi pembantu internal — belakangan, atau tidak sama sekali
Naikkan ketat mypy setelah langkah 1–2 stabil

Sintaks yang perlu kamu kenali

Tipe dasar

nama: str = "budi"
umur: int = 30
skor: float = 0.87
aktif: bool = True
data: bytes = b"\x00"

Koleksi (sintaks modern, Python 3.9+)

daftar: list[str]
kamus: dict[str, int]
himpunan: set[str]
pasangan: tuple[str, int]              # tepat dua elemen, tipe berbeda
banyak: tuple[str, ...]                # berapa pun, semua str

Boleh kosong / beberapa kemungkinan

hasil: str | None                      # Python 3.10+
nilai: int | str                       # salah satu dari dua

Nilai yang terbatas

from typing import Literal

mode: Literal["fast", "accurate"]
status: Literal["open", "closed", "pending"]

Literal sangat berguna: mypy akan menolak nilai di luar daftar, dan Pydantic akan mengubahnya jadi enum di JSON Schema — yang berarti LLM juga tahu pilihan yang sah.

Fungsi sebagai nilai

from collections.abc import Callable

callback: Callable[[str], None]              # terima str, kembalikan None
transform: Callable[[str, int], list[str]]
apa_saja: Callable[..., str]                 # argumen bebas, kembalikan str

`Any` — pintu keluar darurat

from typing import Any

def proses(data: dict[str, Any]) -> None: ...

Any mematikan semua pengecekan pada nilai itu. Kadang memang perlu — misalnya JSON dengan bentuk yang benar-benar tidak diketahui. Tapi setiap Any adalah lubang di jaring pengaman. Kalau bentuknya sebenarnya bisa diketahui, deklarasikan dengan model Pydantic.

Kesalahan sintaks yang umum di tutorial lama

Jangan tulis (usang)	Tulis (modern)
`List[str]`	`list[str]`
`Dict[str, int]`	`dict[str, int]`
`Tuple[int, ...]`	`tuple[int, ...]`
`Optional[str]`	`str \| None`
`Union[int, str]`	`int \| str`
`from typing import Sequence`	`from collections.abc import Sequence`

Ruff aturan UP memperbaiki semua ini secara otomatis dengan --fix.

Terima yang longgar, kembalikan yang tepat

from collections.abc import Sequence, Iterable

# ✅ parameter: pakai tipe abstrak yang paling longgar
def hitung(items: Sequence[str]) -> int: ...      # list, tuple, apa pun boleh
def proses(items: Iterable[str]) -> None: ...     # bahkan generator boleh

# ✅ nilai kembali: pakai tipe konkret supaya pemanggil tahu apa yang didapat
def ambil() -> list[str]: ...

Prinsipnya: jangan memaksa pemanggil mengonversi tuple jadi list hanya supaya cocok dengan anotasimu. Terima yang selonggar mungkin di parameter; janjikan yang setepat mungkin di nilai kembali.

Bagian dokumentasi yang layak dibaca

Type System Guides → Typing Cheat Sheet — ringkasan satu halaman
Guides → Static Typing with Python — pengantar konseptual
Reference → Type System Concepts — kalau ingin paham dasar teorinya
Spesifikasi lengkap — lewati; itu untuk penulis type checker

Rangkuman ini sengaja dipangkas ke bagian yang dipakai di roadmap. Buka sumber aslinya saat kamu butuh detail lengkap atau referensi parameter.