Type checking dalam praktik

Anotasi type hint hanyalah data bagi Python, sehingga type checking perlu dikerjakan alat terpisah sebelum program dijalankan. Topik ini membahas dua pemeriksa statis yang paling umum, yaitu mypy dan pyright, tingkat keketatan masing-masing, konfigurasinya pada pyproject.toml, serta pola kode dari modul typing yang menopang kerja keduanya. Setelah membacanya, pemeriksaan tipe dapat diaktifkan secara bertahap pada proyek yang sudah berjalan.

Dua pemeriksa yang umum digunakan#

mypy adalah pemeriksa statis yang ditulis dengan Python dan dipasang melalui pip. Alat ini membaca anotasi pada seluruh berkas proyek, lalu melaporkan ketidakcocokan beserta berkas dan barisnya tanpa menjalankan program. Satu pemanggilan mypy . cukup untuk memeriksa seluruh proyek, dan pesannya berformat berkas:baris: error: penjelasan yang diakhiri kode error dalam kurung siku, misalnya [arg-type] untuk argumen yang bertipe salah.

pyright menempuh jalur berbeda karena ditulis dengan TypeScript dan berjalan pada Node.js. Kecepatannya pada basis kode besar menjadi keunggulan utamanya, dan alat ini juga menjadi mesin di balik ekstensi Pylance pada Visual Studio Code. Konfigurasinya diletakkan pada berkas pyrightconfig.json atau bagian [tool.pyright] di pyproject.toml. Untuk kode yang sama, kedua alat umumnya melaporkan kesalahan yang serupa, sehingga pilihan sering ditentukan oleh ekosistem editor dan kecepatan yang dibutuhkan.

Kedua alat memperlakukan kode yang belum dianotasi secara longgar. Fungsi tanpa anotasi lolos secara diam-diam pada mode bawaan, sehingga proyek lama tetap diperiksa tanpa menimbulkan ratusan temuan sekaligus.

def proses(data):
    return data

Pemeriksaan yang ketat baru aktif setelah tingkat keketatannya dinaikkan, dan berkas berikut menunjukkan jenis kode yang akan dilaporkan.

# tidak-dijalankan
# berkas gaji.py yang diperiksa mypy atau pyright di luar sandbox
def hitung_gaji(jam_kerja: int, tarif_per_jam: int) -> int:
    return jam_kerja * tarif_per_jam

hitung_gaji("40", 150000)

Pada berkas tersebut, pemanggilan dengan argumen string dilaporkan pada baris pemanggilnya oleh kedua alat, lengkap dengan penjelasan bahwa str tidak cocok dengan anotasi int. mypy menambahkan kode [arg-type] pada pesannya, sedangkan pyright menampilkannya sebagai saran langsung di editor. Perintah pemeriksaannya adalah sebagai berikut.

# tidak-dijalankan
# memeriksa seluruh proyek dengan tingkat ketat penuh
pip install mypy
mypy --strict .

Tingkat keketatan#

Mode bawaan membiarkan fungsi tanpa anotasi lolos, sehingga pemeriksaan baru terasa ketat setelah tingkatnya dinaikkan. Pada mypy, flag --strict mengaktifkan sekumpulan opsi sekaligus, seperti kewajiban menganotasi setiap fungsi dan peringatan untuk nilai kembalian bertipe Any. Pada pyright, tingkat keketatan dipilih melalui satu mode, yaitu off, basic, standard, atau strict, dengan standard sebagai pilihan tengah yang lazim pada proyek aktif.

Kenaikan yang dilakukan sekaligus pada proyek besar biasanya menghasilkan ratusan temuan, sehingga adopsi bertahap lebih praktis. Strateginya adalah menaikkan tingkat keketatan per folder atau per modul, dimulai dari kode yang paling sering berubah. mypy dan pyright sama-sama menyediakan mekanisme override per modul pada konfigurasinya, sehingga bagian yang sudah bersih dijaga ketat, sedangkan bagian lama tetap dapat diperiksa pada tingkat longgar.

Pembagian semacam ini dituliskan satu kali pada berkas konfigurasi, bukan sebagai perintah terpisah setiap kali memeriksa. Subbagian berikut menempatkannya pada pyproject.toml.

Konfigurasi pada pyproject.toml#

Berkas berikut menetapkan tingkat ketat penuh untuk seluruh proyek, kemudian melonggarkannya khusus untuk modul lama pada folder gaji_legacy. Opsi python_version menyatakan versi Python terendah yang ditargetkan, sehingga fitur dari versi yang lebih baru dilaporkan sebagai kesalahan.

[tool.mypy]
python_version = "3.12"
strict = true

[[tool.mypy.overrides]]
module = "gaji_legacy.*"
strict = false

Bentuk override inilah yang menjadikan adopsi bertahap sebagai konfigurasi, bukan sebagai keputusan ad hoc setiap pemeriksaan. Setiap kali satu modul lama selesai dianotasi, namanya dipindahkan keluar dari daftar override, sehingga cakupan pemeriksaan ketat tumbuh mengikuti kemajuan proyek. Konfigurasi yang sama juga dibaca alat di lingkungan lain, termasuk CI, sehingga ketegasannya konsisten untuk seluruh anggota tim.

Pola kode yang membantu pemeriksa#

Modul typing menyediakan beberapa pola yang mempermudah pemeriksaan tanpa mengubah perilaku program. Pola pertama adalah TYPE_CHECKING, yaitu konstanta yang bernilai False saat program berjalan dan True menurut pemeriksa statis. Blok di bawah kendalinya hanya dibaca alat pemeriksa, sehingga tempat itu tepat untuk mengimpor modul berat yang hanya dibutuhkan anotasinya.

from typing import TYPE_CHECKING

print(TYPE_CHECKING)

if TYPE_CHECKING:
    print("baris ini hanya dibaca pemeriksa statis")

False

Keluarannya hanya berisi satu baris karena TYPE_CHECKING bernilai False pada waktu berjalan, sehingga pemanggilan print di dalam blok tidak pernah dieksekusi. Pemeriksa statis memperlakukan konstanta yang sama sebagai True, sehingga impor dan anotasi di dalam blok tetap dibaca. Pola ini juga menjadi pemecah impor melingkar yang disebabkan anotasi.

Pola kedua adalah cast, yang menyatakan kepada pemeriksa bahwa sebuah nilai harus diperlakukan sebagai tipe tertentu. Fungsinya tidak mengubah apa pun pada waktu berjalan, sebagaimana ditunjukkan contoh berikut.

from typing import cast

nilai = cast(int, "teks biasa")
print(nilai)
print(type(nilai).__name__)

teks biasa
str

Pola ketiga adalah reveal_type, alat untuk bertanya kepada pemeriksa tentang tipe yang disimpulkannya pada satu titik. Saat dipanggil tanpa pemeriksa, fungsi ini hanya mencetak tipe waktu berjalannya.

from typing import reveal_type

reveal_type(10)

Runtime type is 'int'

Ketika mypy atau pyright memeriksa baris yang sama, keduanya melaporkan tipe yang disimpulkannya beserta jalur lengkapnya di editor atau terminal. Baris reveal_type adalah alat pengembangan yang dihapus setelah pertanyaannya terjawab, sehingga tidak layak ditinggalkan pada kode akhir.

Kesalahan umum#

Kesalahan pertama adalah mengaktifkan tingkat ketat untuk seluruh proyek sekaligus pada langkah pertama. Mode ketat pada proyek besar membanjiri terminal dengan temuan, sehingga pemeriksaan sering dimatikan lagi dan hasilnya hilang seluruhnya. Adopsi bertahap melalui override per modul menjaga pemeriksaan tetap menyala pada bagian yang sudah bersih, dan cakupannya tumbuh perlahan tanpa menunda pekerjaan lain.

Kesalahan kedua adalah mengimpor modul berat di bagian atas berkas hanya karena anotasinya membutuhkan. Impor semacam itu tetap dieksekusi setiap kali program berjalan, padahal blok TYPE_CHECKING menyelesaikan kebutuhan yang sama tanpa biaya waktu berjalan. Kebiasaan ini biasanya muncul saat mengikuti saran perbaikan editor tanpa membaca polanya, sehingga penambahan anotasi justru memperlambat program.

Kesalahan ketiga adalah membungkam setiap temuan dengan komentar # type: ignore. Komentar itu menonaktifkan pemeriksaan pada barisnya tanpa menjelaskan alasannya, sehingga kesalahan sungguhan ikut lolos. Pemakaiannya sebaiknya dijaga pada kasus yang memang di luar jangkauan pemeriksa dan disertai penjelasan singkat, sedangkan temuan lainnya diperbaiki.

Ringkasan#

• mypy dan pyright memeriksa anotasi secara statis dengan perbedaan pada implementasi, pemasangan, dan berkas konfigurasinya.
• Tingkat keketatan diatur melalui flag --strict pada mypy atau mode off, basic, standard, dan strict pada pyright.
• Bagian [tool.mypy] pada pyproject.toml menyimpan konfigurasi proyek, termasuk override per modul untuk adopsi bertahap.
• TYPE_CHECKING, cast, dan reveal_type adalah pola modul typing yang menopang kerja pemeriksa tanpa mengubah perilaku program.

Referensi#

• mypy documentation — mypy — Dokumentasi resmi mypy, termasuk tingkat keketatan dan konfigurasi per modul.
• Pyright documentation — Microsoft — Dokumentasi resmi pyright, termasuk mode keketatan dan berkas konfigurasinya.
• typing — Support for type hints — Python Software Foundation — Referensi modul typing untuk TYPE_CHECKING, cast, dan reveal_type.