Type hint di Python: anotasi untuk fungsi, list, dict, dan lainnya

Anotasi yang menjelaskan, bukan memaksa

Type hint adalah catatan yang kamu tempelkan ke sebuah nama, biasanya parameter fungsi, yang berkata "ini seharusnya int", "ini mengembalikan list berisi string", dan sebagainya. Python tidak memeriksanya saat program berjalan. Memberikan string di tempat yang kamu anotasi sebagai int tidak memunculkan error. Editormu dan alat eksternal (mypy, pyright, Pylance di VS Code yang memakai Pyright) membaca hint itu dan memperingatkanmu sebelum kodenya dijalankan.

Kasus paling sederhana:

def greet(name: str) -> str:
    return f"Hello, {name}"

print(greet("Rosa"))
print(greet(42))

name: str memberi anotasi pada parameter. -> str memberi anotasi pada nilai kembalian. Kedua pemanggilan berjalan. Yang kedua salah, dan type checker statis akan menandainya, tapi Python sendiri tetap memprosesnya dengan senang hati karena 42 kebetulan mendukung interpolasi f"{...}".

Itulah model berpikir yang terpenting: hint adalah dokumentasi yang bisa dibaca mesin. Hint tidak mengubah perilaku saat program berjalan.

Kenapa repot-repot?

Tiga keuntungan nyata, diurutkan dari yang paling cepat terasa:

1. Editormu jadi lebih pintar. Autocomplete menampilkan method yang tepat, rename menyebar dengan benar, dan mengarahkan kursor ke sebuah variabel memberitahumu tipenya.
2. Signature fungsi menjelaskan dirinya sendiri. def fetch(url: str, timeout: float = 5.0) -> dict: memberi tahu pembaca persis apa yang harus diberikan dan apa yang akan didapat, tanpa perlu membaca isi fungsinya.
3. Type checker menangkap kesalahan sebelum kodenya dijalankan. Menjalankan mypy . pada sebuah proyek memunculkan jenis bug yang sering lolos dari unit test: None dikembalikan padahal kamu mengharapkan nilai, dict dipakai di tempat yang seharusnya list.

Untuk skrip satu file yang hanya untukmu dan hanya untuk hari ini, lewati saja hint-nya. Untuk apa pun yang akan kamu buka lagi atau bagikan, lima belas detik untuk menulisnya akan terbayar dalam satu jam.

Tipe bawaan dasar

Kamu tidak perlu import untuk tipe-tipe ini:

name: str = "Rosa"
age: int = 30
price: float = 19.99
is_admin: bool = False
nothing: None = None

def add(a: int, b: int) -> int:
    return a + b

print(add(2, 3))

Anotasi variabel (name: str = "Rosa") jarang diperlukan, karena Python menyimpulkan tipenya dari sisi kanan. Simpan anotasi untuk parameter, tipe kembalian, dan sesekali kasus ketika tipe hasil penyimpulan ambigu.

Fungsi yang tidak mengembalikan apa-apa memakai -> None:

def log_message(message: str) -> None:
    print(f"[log] {message}")

log_message("service started")

List, dict, tuple, dan set

Container butuh satu informasi tambahan, yaitu apa isinya. Python modern memungkinkan kamu menulis subscript langsung pada tipe bawaan:

def average(scores: list[float]) -> float:
    return sum(scores) / len(scores)

def first_seen(events: dict[str, int]) -> int:
    return min(events.values())

def bounds(points: list[tuple[float, float]]) -> tuple[float, float]:
    xs = [p[0] for p in points]
    return min(xs), max(xs)

print(average([1.0, 2.0, 3.0]))
print(first_seen({"login": 10, "logout": 25}))
print(bounds([(0, 0), (1, 1), (-1, 2)]))

Cara membacanya:

• list[float]: list berisi float.
• dict[str, int]: dict dengan key string dan nilai int.
• tuple[float, float]: tuple berisi tepat dua float.
• set[str]: set berisi string.

Sintaks subscript list[...], dict[...] bekerja di Python 3.9 dan setelahnya. Di kode lama kamu akan melihat List, Dict, Tuple yang di-import dari typing: artinya sama, cara penulisannya lebih lama.

Nilai opsional

"Mungkin None" adalah kasus yang umum. Ada dua cara penulisan yang setara; keduanya boleh, tapi yang lebih baru lebih enak dibaca:

def find_user(user_id: int) -> str | None:
    users = {1: "Rosa", 2: "Boris"}
    return users.get(user_id)

# Older spelling, still valid - requires `from typing import Optional`.
# def find_user(user_id: int) -> Optional[str]: ...

print(find_user(1))
print(find_user(99))

str | None berarti "sebuah string, atau None". Sintaks | bekerja di Python 3.10+. Di kode lama kamu akan melihat Optional[str] dari module typing, yang artinya sama.

Pemanggil yang melihat -> str | None tahu bahwa ia harus memeriksa None sebelum memakai hasilnya. Itulah inti dari anotasi tersebut.

Union type: ini atau itu

Saat sebuah nilai bisa berupa salah satu dari beberapa tipe, pakai |:

def parse_id(value: int | str) -> int:
    if isinstance(value, str):
        return int(value)
    return value

print(parse_id(42))
print(parse_id("42"))

Kamu bisa menggabungkan lebih dari dua tipe. int | str | float berarti "salah satu dari ketiganya".

Anotasi variabel di dalam fungsi

Hampir selalu Python bisa mengetahui tipe variabel lokal dari nilai awalnya. Kamu hanya butuh anotasi ketika:

from typing import Any

results: list[str] = []
seen: set[int] = set()
config: dict[str, Any] = {}

results.append("first")
seen.add(42)
config["theme"] = "dark"

print(results, seen, config)

• Container-nya awalnya kosong dan type checker tidak bisa menebak isinya.
• Nilainya bisa berupa beberapa tipe dan kamu ingin memastikan satu.
• Kamu ingin mendokumentasikan maksudnya untuk pembaca manusia.

typing.Any adalah jalan keluarnya: "aku tidak mau memberi anotasi ini secara persis". Pakai seperlunya. Terlalu sering memakai Any membuat type hint-mu yang lain tidak ada gunanya.

Anotasi pada class

Atribut class dan signature method diberi anotasi dengan cara yang sama seperti fungsi lainnya:

from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int
    email: str | None = None

    def greeting(self) -> str:
        return f"Hi, I'm {self.name}"

rosa = User("Rosa", 30)
print(rosa.greeting())
print(User("Boris", 45, email="boris@example.com"))

Dataclass justru mewajibkan anotasi tipe: decorator @dataclass membacanya untuk membuat __init__ dan __repr__. Itulah satu-satunya tempat anotasi benar-benar memengaruhi perilaku saat program berjalan.

Tuple dan kasus "panjang berapa saja"

tuple[...] punya dua bentuk yang membingungkan pemula:

def first_point(points: tuple[float, float]) -> float:
    return points[0]

def sum_all(values: tuple[int, ...]) -> int:
    return sum(values)

print(first_point((1.5, 2.5)))
print(sum_all((1, 2, 3, 4, 5)))

• tuple[float, float]: tepat dua float.
• tuple[int, ...]: int sebanyak berapa pun. ... (elemen sintaks sungguhan di sistem tipe) berarti "dan seterusnya".

Callable dan type alias

Saat sebuah fungsi menerima atau mengembalikan fungsi lain, pakai Callable:

from typing import Callable

def apply_twice(func: Callable[[int], int], value: int) -> int:
    return func(func(value))

def add_one(n: int) -> int:
    return n + 1

print(apply_twice(add_one, 5))

Callable[[int], int] berarti "fungsi yang menerima satu int dan mengembalikan int".

Saat sebuah anotasi jadi berulang-ulang, beri nama:

Coordinate = tuple[float, float]
Coordinates = list[Coordinate]

def total_distance(points: Coordinates) -> float:
    return float(len(points) - 1)

print(total_distance([(0, 0), (1, 1), (2, 2)]))

Alias hanyalah penugasan Python biasa. Di mana pun kamu memakai bentuk panjangnya, nama pendeknya juga bisa dipakai.

Menjalankan type checker

Interpreter Python sendiri mengabaikan type hint. Untuk benar-benar memeriksanya, install sebuah type checker. mypy adalah yang pertama; pyright (dipakai oleh Pylance di VS Code) lebih cepat.

pip install mypy
mypy your_project/

Proses pertama akan memunculkan error di tempat yang tidak kamu sangka. Selesaikan sedikit demi sedikit: # type: ignore membungkam satu baris saat kamu perlu lanjut.

IDE modern menjalankan pemeriksaan tipe terus-menerus selama kamu mengedit, jadi kebanyakan umpan balik sudah muncul sebelum kamu menyimpan.

Saat type hint tidak cocok

• Skrip eksplorasi singkat. Anotasi menambah hambatan pada kode yang hanya hidup satu jam.
• Kode yang sangat dinamis. Metaprogramming, sistem plugin, dan pola sejenis sering melampaui apa yang bisa digambarkan sistem tipe. Beri anotasi pada API luarnya dan biarkan bagian dalamnya longgar.
• Library pihak ketiga tanpa tipe. Kalau library yang kamu import tidak punya info tipe, Any bocor ke kodemu. Tidak masalah, itu bukan kodemu yang harus diberi anotasi.

Untuk semua yang ada di antaranya, type hint adalah kebiasaan kecil dengan manfaat besar. Biayanya beberapa ketukan tombol tambahan per signature fungsi. Hasilnya lebih sedikit bug, refactor yang lebih mudah, dan kode yang mendokumentasikan dirinya sendiri.

Berikutnya: module dan import

Sekarang kamu sudah punya semua perkakas di level fungsi: argumen, decorator, type hint. Berikutnya kita akan melihat cara Python mengatur kode di beberapa file: module, package, dan sistem import.