Fase 2 · Type Hints & Pydantic

typing — Support for type hints

Peta isi modul typing: mana yang benar-benar dipakai, mana yang sudah usang, dan mana yang bisa diabaikan.

Sumber asli docs.python.org Resmi Rangkuman ~5 menit baca

Intisari

Halaman referensi, bukan tutorial. Buka saat kamu butuh satu nama tertentu.
Sebagian besar isinya sudah usang — digantikan sintaks bawaan (list[str], str | None).
Yang masih aktif dipakai: Any, Literal, Final, Protocol, TypedDict, cast, Annotated.
Tipe koleksi abstrak sekarang diimpor dari collections.abc, bukan typing.
Annotated adalah dasar dari Field() Pydantic dan Depends() FastAPI.

Cara memakai halaman ini

Dokumentasi typing panjang dan berisi banyak hal historis. Jangan dibaca dari atas ke bawah. Tabel di bawah ini adalah peta: mana yang masih hidup, mana yang sudah tergantikan.

Yang masih aktif dipakai

Nama	Fungsinya	Contoh
`Any`	Matikan pengecekan	`dict[str, Any]`
`Literal`	Nilai terbatas	`Literal["a", "b"]`
`Final`	Tidak boleh diubah	`MAX: Final = 10`
`Protocol`	Duck typing struktural	Lihat di bawah
`TypedDict`	Dict dengan bentuk tetap	Lihat di bawah
`cast`	Paksa mypy percaya	`cast(Doc, x)`
`Annotated`	Tempel metadata pada tipe	Dasar Pydantic & FastAPI
`NamedTuple`	Tuple bernama, punya tipe	Alternatif ringan dataclass
`NoReturn`	Fungsi selalu melempar	`-> NoReturn`
`Self`	Kembalikan tipe class sendiri	Pola builder
`overload`	Beberapa tanda tangan	Jarang, tapi ada

Yang sudah tergantikan

Usang	Ganti dengan	Sejak
`List`, `Dict`, `Set`, `Tuple`, `Type`	`list`, `dict`, `set`, `tuple`, `type`	3.9
`Optional[X]`	`X \| None`	3.10
`Union[A, B]`	`A \| B`	3.10
`Callable`, `Iterable`, `Sequence`, `Mapping`, `Iterator`	Impor dari `collections.abc`	3.9
`TypeVar` eksplisit	Sintaks `def f[T](...)`	3.12

`Annotated` — kenapa ini penting

Annotated[Tipe, metadata] menempelkan informasi tambahan ke sebuah tipe. Type checker mengabaikan metadata-nya; library yang membacanya bisa memanfaatkannya. Ini fondasi dari dua hal yang akan kamu pakai terus:

from typing import Annotated
from pydantic import Field

class Tiket(BaseModel):
    judul: Annotated[str, Field(min_length=1, max_length=200)]
    prioritas: Annotated[int, Field(ge=1, le=5)]

from fastapi import Depends

@app.post("/chat")
async def chat(
    req: ChatRequest,
    client: Annotated[AsyncAnthropic, Depends(get_client)],
) -> ChatResponse: ...

Bagi mypy, Annotated[str, Field(...)] hanyalah str. Bagi Pydantic, bagian Field(...) adalah aturan validasi. Bagi FastAPI, Depends(...) adalah instruksi dependency injection. Satu sintaks, tiga pembaca berbeda.

`Protocol` — cocok untuk testing

from typing import Protocol

class VectorStore(Protocol):
    def cari(self, embedding: list[float], top_k: int) -> list[str]: ...
    def simpan(self, id: str, embedding: list[float]) -> None: ...


def bangun_rag(store: VectorStore) -> None: ...

# Kedua class ini diterima, tanpa mewarisi apa pun:
class ChromaStore:
    def cari(self, embedding: list[float], top_k: int) -> list[str]: ...
    def simpan(self, id: str, embedding: list[float]) -> None: ...

class StorePalsu:      # untuk unit test
    def cari(self, embedding: list[float], top_k: int) -> list[str]:
        return ["chunk-1"]
    def simpan(self, id: str, embedding: list[float]) -> None:
        pass

`TypedDict`

from typing import TypedDict, NotRequired

class Pesan(TypedDict):
    role: str
    content: str
    name: NotRequired[str]        # opsional

riwayat: list[Pesan] = [
    {"role": "user", "content": "halo"},
]

Bedanya dengan Pydantic: TypedDict hanya memberi tahu mypy bentuk dict-nya. Tidak ada validasi runtime, tidak ada parsing, tidak ada JSON Schema. Pakai untuk bentuk dict yang memang harus tetap dict — misalnya array messages yang dikirim ke API LLM.

`Self`

from typing import Self

class Query:
    def filter(self, **kw) -> Self:
        ...
        return self

    def limit(self, n: int) -> Self:
        ...
        return self

Query().filter(x=1).limit(10)     # tipe tetap benar di subclass

Yang boleh diabaikan sepenuhnya

ParamSpec, TypeVarTuple, Concatenate, Unpack, TypeGuard, assert_type, dataclass_transform — semua ini untuk penulis library dan dekorator generik. Tidak akan kamu butuhkan di kode aplikasi.

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