Panduan Pyright: Pemeriksaan Tipe Statis Cepat untuk Kode Python

Type hint membuat kode Python lebih mudah dipahami dan dipelihara. Namun ada satu hal: hint saja tidak menangkap kesalahan. Anda memerlukan pemeriksa tipe untuk memverifikasi bahwa kode Anda benar-benar mengikuti tipe yang telah Anda deklarasikan.

Saya pernah menggunakan Mypy dan Pyright di produksi. Keunggulan kecepatan Pyright paling terasa saat pengembangan. Kesalahan tipe muncul saat Anda mengetik, bukan setelah menyimpan. Di codebase besar, siklus umpan balik yang lebih cepat ini benar-benar berdampak.

Tutorial ini mencakup semua yang Anda butuhkan untuk mulai menggunakan Pyright secara efektif. Saya akan menunjukkan cara memasangnya, mengonfigurasinya untuk proyek Anda, dan mengintegrasikannya dengan VS Code. Saya juga akan menguraikan perbedaan antara Pyright dan Mypy.

Apa Itu Pyright?

Pyright adalah pemeriksa tipe statis untuk Python yang dikembangkan oleh Microsoft. Ia membaca kode Anda, menganalisis anotasi tipe, dan melaporkan kesalahan saat tipe tidak cocok. Berbeda dari pemeriksaan runtime yang menangkap kesalahan ketika kode dijalankan, analisis statis menangkapnya sebelum Anda menjalankan apa pun.

Walau sebagian besar alat Python ditulis dengan Python, Pyright ditulis dengan TypeScript dan berjalan di Node.js. Pilihan yang aneh untuk alat Python, bukan? Namun inilah alasan Pyright sangat cepat. Mesin JavaScript V8 dieksekusi jauh lebih cepat daripada CPython.

Anda akan menjumpai Pyright dalam dua cara. Anda bisa menjalankannya sebagai alat baris perintah di pipeline CI/CD untuk menangkap kesalahan tipe sebelum melakukan merge. Atau Anda mungkin sudah menggunakannya tanpa sadar. Ia menjadi mesin Pylance, ekstensi Python Microsoft untuk VS Code. Garis merah bergelombang di bawah kesalahan tipe? Itu Pyright yang bekerja di balik layar.

Alat ini dikirimkan bersama type stub untuk pustaka standar Python dan paket umum. Anda tidak perlu memasang apa pun tambahan untuk memeriksa kode yang menggunakan os, json, atau typing. Untuk paket pihak ketiga, Pyright menggunakan stub yang dipelihara komunitas dari typeshed atau stub spesifik paket yang Anda pasang terpisah.

Cara Memasang Pyright

Sekarang mari jalankan Pyright di sistem Anda. Ada dua opsi pemasangan: npm (pendekatan native) atau pip (pembungkus Python).

Memasang Pyright dengan npm

Pemasangan yang direkomendasikan menggunakan npm karena Pyright berjalan di Node.js. Anda memerlukan Node.js versi 14.0.0 atau lebih tinggi.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyrightDidukung oleh

Saya menggunakan pemasangan global untuk pemeriksaan cepat dan pemasangan lokal untuk proyek yang ingin saya kunci versinya. Pendekatan npx berguna untuk sekali jalan tanpa menambah paket global Anda.

Memasang Pyright melalui pembungkus Python

Jika tim Anda bekerja sepenuhnya di Python dan tidak ingin Node.js di toolchain, ada pembungkus PyPI:

# Standard installation
pip install pyright

# Recommended: includes Node.js automatically
pip install pyright[nodejs]Didukung oleh

Pembungkus akan memeriksa Node.js di sistem Anda. Jika tidak ada, pembungkus akan mengunduh versi mandiri secara otomatis. Ekstra [nodejs] menggunakan metode unduh yang lebih andal daripada default.

Perlu diingat ada kompromi. Jalan pertama kali lebih lama saat dependensi diunduh. Lingkungan CI dengan akses jaringan terbatas bisa gagal. Dan versi PyPI kadang tertinggal beberapa hari dari rilis npm.

Untuk sebagian besar tim Python, pembungkus ini bekerja baik. Namun jika Anda menemui masalah, kembali ke pemasangan via npm. Itu lebih andal.

Menjalankan Pyright pada Proyek Python

Setelah terpasang, menjalankan Pyright itu sederhana. Arahkan ke direktori proyek Anda dan jalankan:

pyrightDidukung oleh

Selesai, betul. Pyright memindai berkas Python, menganalisisnya, dan melaporkan kesalahan tipe yang ditemukan. Tidak perlu penyiapan rumit.

Apa yang diperiksa Pyright secara default

Apa yang dicari Pyright? Tanpa konfigurasi apa pun, ia melakukan beberapa pemeriksaan. Ia memvalidasi anotasi tipe yang sesuai dengan penggunaan aktual. Ia menangkap variabel yang tidak terdefinisi dan kode yang tidak dapat dijangkau. Ia memverifikasi impor dengan benar. Ia menandai ketidaksesuaian tipe yang jelas seperti mengoper string saat yang diharapkan integer.

Berikut keluaran contoh dari proyek yang memiliki kesalahan:

/src/utils.py:12:15 - error: Argument of type "str" cannot be assigned 
   to parameter "count" of type "int" in function "process_items"
   "str" is not assignable to "int" (reportArgumentType)
/src/main.py:45:9 - error: "user" is possibly unbound (reportPossiblyUnbound)
2 errors, 0 warnings, 0 informationsDidukung oleh

Setiap kesalahan menampilkan path berkas, nomor baris, kolom, dan deskripsi. Nama aturan dalam tanda kurung (seperti reportArgumentType) memberi tahu Anda tepatnya pemeriksaan mana yang memicu kesalahan. Ini penting saat Anda ingin menonaktifkan aturan tertentu. Kita akan bahas sebentar lagi.

Memahami kode keluar

Pyright mengembalikan kode keluar yang berbeda bergantung pada hasilnya:

Dalam pipeline CI, Anda biasanya ingin build gagal pada kode keluar 1. Kode keluar 2–4 menunjukkan ada yang salah dengan alatnya, bukan kode Anda.

Mengonfigurasi Pyright

Walau Pyright langsung berfungsi, proyek nyata memerlukan penyesuaian. Anda perlu menentukan berkas mana yang diperiksa, versi Python yang ditargetkan, dan seberapa ketat analisisnya. Mari lihat opsi konfigurasi kunci.

Mode pemeriksaan tipe

Pyright menawarkan empat tingkat keketatan. Mode yang Anda pilih menentukan berapa banyak aturan yang diaktifkan.

Mode mana yang harus Anda pilih? Untuk proyek baru, mulailah dengan mode standard. Ia menangkap bug nyata tanpa membanjiri Anda dengan kesalahan. Bekerja dengan kode lama? Mode Basic lebih cocok saat Anda mengadopsi typing secara bertahap. Simpan mode strict untuk pustaka dan infrastruktur kritis di mana Anda menginginkan keamanan maksimum.

Peringatan jujur: lompatan dari standard ke strict itu signifikan. Mode strict mengaktifkan sekitar 30 aturan tambahan, termasuk kewajiban anotasi tipe pada semua parameter fungsi dan nilai kembali. Harapkan peningkatan 10x pada kesalahan yang dilaporkan saat beralih. Saya belajar ini dengan cara yang sulit.

Mode strict membutuhkan anotasi tipe lengkap. Gambar oleh Penulis

Berkas konfigurasi

Pyright membaca konfigurasi dari pyrightconfig.json atau pyproject.toml. Jika keduanya ada, pyrightconfig.json memiliki prioritas.

Berikut pyrightconfig.json minimal:

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.venv"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}Didukung oleh

Padanannya di pyproject.toml:

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", "**/.venv"]
pythonVersion = "3.12"
typeCheckingMode = "standard"Didukung oleh

Berkas konfigurasi mengendalikan perilaku Pyright. Gambar oleh Penulis.

Detail krusial yang sering menjebak banyak orang: jika Anda mendefinisikan exclude secara manual, itu mengganti seluruh default. Selalu sertakan node_modules, __pycache__, dan lingkungan virtual Anda dalam pola exclude kustom. Jika tidak, Pyright mencoba menganalisis dependensi Anda, menyebabkan perlambatan besar. Percayalah, Anda tidak ingin menunggu 10 menit untuk pemeriksaan tipe.

Konfigurasi lingkungan virtual

Bagaimana Pyright menemukan paket terpasang Anda? Anda perlu memberi tahu di mana harus mencari. Konfigurasikan dengan venvPath dan venv:

{
  "venvPath": ".",
  "venv": ".venv"
}Didukung oleh

Ini memberi tahu Pyright untuk mencari paket di ./.venv. Jika Anda menggunakan lokasi lingkungan virtual yang berbeda, sesuaikan sesuai kebutuhan. Tanpa ini, Pyright tidak bisa menemukan dependensi terpasang Anda dan melaporkan kesalahan impor hilang untuk semuanya.

Menekan diagnostik

Terkadang Pyright secara teknis benar tetapi Anda tetap perlu membungkam kesalahan tertentu. Mungkin Anda bekerja dengan kode lama, atau Anda tahu lebih baik daripada pemeriksa tipe dalam kasus tertentu. Anda bisa menekan kesalahan pada tiga tingkat.

Penekanan tingkat konfigurasi

Nonaktifkan aturan secara global:

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}Didukung oleh

Penekanan tingkat berkas

Tambahkan komentar di bagian atas berkas:

# pyright: basic
# pyright: reportPrivateUsage=falseDidukung oleh

Penekanan tingkat baris

Tekan satu baris saja:

x: int = "hello"  # type: ignore
x: int = "hello"  # pyright: ignore
x: int = "hello"  # pyright: ignore[reportAssignmentType]Didukung oleh

Sintaks aturan spesifik ([reportAssignmentType]) berguna saat Anda ingin membungkam satu pemeriksaan tanpa menonaktifkan yang lain pada baris yang sama.

Dengan konfigurasi telah dibahas, mari lihat bagaimana Pyright terintegrasi dengan lingkungan pengembangan Anda.

Pyright di VS Code dan IDE

Jika Anda seperti kebanyakan pengembang Python, Anda akan merasakan Pyright melalui Pylance alih-alih baris perintah. Memahami hubungan ini membantu Anda mengonfigurasi editor dengan benar dan menghindari kendala umum.

Pyright vs. Pylance

Pylance adalah ekstensi VS Code dari Microsoft yang membundel mesin pemeriksaan tipe Pyright. Saat Anda memasang Pylance, Anda otomatis mendapatkan Pyright. Namun Pylance menambahkan fitur yang tidak ada di Pyright open-source:

• Penyorotan semantik: variabel diberi warna berdasarkan tipenya
• Auto-import lanjutan: saran impor yang lebih cerdas
• Navigasi kode: "Find All References" di seluruh workspace Anda

Fitur-fitur ini bersifat tertutup dan hanya tersedia di VS Code. Jika Anda menggunakan Neovim, Emacs, atau editor lain, Anda mendapatkan fungsi inti Pyright tanpa ekstra ini.

Pylance menyorot kesalahan tipe di editor. Gambar oleh Penulis.

Pengaturan penting VS Code

Konfigurasikan Pylance melalui pengaturan VS Code:

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "standard",
  "python.analysis.diagnosticMode": "openFilesOnly"
}Didukung oleh

Pengaturan diagnosticMode memengaruhi performa. "openFilesOnly" hanya menganalisis berkas yang Anda buka. "workspace" menganalisis semuanya namun menggunakan lebih banyak memori dan CPU.

Jebakan konfigurasi umum

Pemilihan interpreter itu penting. Pylance menggunakan interpreter Python yang Anda pilih untuk menemukan paket terpasang. Jika tiba-tiba muncul kesalahan untuk paket yang Anda tahu sudah terpasang, periksa apakah interpreter yang benar dipilih di bilah status VS Code.

Pemilihan interpreter memengaruhi jalur penemuan paket. Gambar oleh Penulis.

Default CLI dan Pylance berbeda. Pylance menetapkan typeCheckingMode ke "off" sementara CLI menetapkan ke "standard". Pylance juga otomatis menambahkan src ke jalur pencarian; CLI tidak. Untuk perilaku yang konsisten antara editor dan CI, tetapkan semua opsi secara eksplisit di pyproject.toml.

Fenomena "kode berwarna abu-abu". Pylance mengabukan kode yang tidak dapat dijangkau berdasarkan analisis tipe. Jika kode tampak abu-abu secara tak terduga, periksa fungsi yang dipanggil tepat sebelumnya. Fungsi yang diketik mengembalikan NoReturn menyebabkan segala yang ada setelahnya dianggap tidak dapat dijangkau.

Pyright vs. Mypy: Kapan Menggunakan Masing-Masing

Anda mungkin bertanya-tanya: harus menggunakan Pyright atau tetap dengan Mypy? Keduanya siap produksi, dan pilihan Anda bergantung pada alur kerja dan kebutuhan. Berikut perbedaan kunci.

Kecepatan dan respons

Pyright kira-kira 3–5x lebih cepat daripada Mypy untuk pemindaian proyek penuh dan nyaris instan untuk pemeriksaan inkremental. Ini paling berdampak saat pengembangan ketika Anda menginginkan umpan balik segera.

Mypy memiliki mode daemon (dmypy) yang meningkatkan performa, tetapi tetap lebih lambat dan sesekali mengalami masalah cache yang memerlukan restart.

Perbedaan inferensi tipe

Di sinilah menariknya. Kedua alat menginferensikan tipe secara berbeda. Pertimbangkan kode ini:

coordinates = (10, 20)Didukung oleh

Pyright menginferensikan tuple[Literal[10], Literal[20]], mempertahankan nilai persis karena tuple bersifat imut. Mypy menginferensikan tuple[int, int], melebarkannya ke tipe umum.

Pendekatan Pyright menangkap lebih banyak kesalahan tetapi kadang menimbulkan friksi saat fungsi mengharapkan tipe umum. Ini jarang menjadi masalah dalam praktik karena Literal[10] adalah subtype yang valid dari int.

Analisis kode tanpa anotasi

Ini adalah perbedaan praktis terbesar, dan menjadi pengubah permainan untuk codebase lama. Mypy melewati fungsi tanpa anotasi secara default. Pyright tetap menganalisisnya, menangkap kesalahan jelas bahkan tanpa hint tipe.

Untuk codebase lama dengan anotasi yang jarang, Pyright bertindak sebagai linter yang kuat yang menangkap variabel tak terdefinisi dan pemanggilan metode yang mustahil. Mypy memperlakukan fungsi-fungsi tersebut sebagai "dinamis" dan mengabaikannya.

Dukungan plugin

Mypy mendukung plugin untuk kerangka kerja seperti Django dan SQLAlchemy. Plugin ini memahami sihir ORM dan menyediakan tipe yang akurat untuk atribut yang dihasilkan secara dinamis.

Pyright tidak memiliki sistem plugin. Ia sepenuhnya mengandalkan type stub. Pada 2026, sebagian besar pustaka besar memiliki stub berkualitas tinggi, jadi ini kurang penting dibanding dulu. Namun jika Anda menggunakan kerangka kerja dengan metaprogramming berat, periksa apakah stub yang baik tersedia sebelum berkomit ke Pyright.

Gunakan Pylance (Pyright) saat pengembangan untuk umpan balik instan, dan pertimbangkan menjalankan Pyright dan Mypy di CI jika proyek Anda menggunakan plugin kerangka kerja.

Masalah Umum Saat Menggunakan Pyright

Saat Pyright melaporkan kesalahan yang tidak terduga, penyebabnya biasanya salah satu dari masalah berikut.

Type stub hilang

Pernah melihat kesalahan ini? Pyright mengeluh saat tidak bisa menemukan informasi tipe untuk suatu paket:

Import "requests" could not be resolved (reportMissingImports)Didukung oleh

Stub yang hilang memicu peringatan kesalahan impor. Gambar oleh Penulis.

Pertama, periksa bahwa paket terpasang di lingkungan virtual Anda dan bahwa Pyright tahu di mana menemukannya (menggunakan pengaturan venvPath dan venv yang dibahas sebelumnya).

Jika paket terpasang tetapi tidak memiliki informasi tipe, pasang stub komunitas:

pip install types-requests types-PyYAML types-redisDidukung oleh

Untuk paket yang tidak memiliki stub tersedia, Anda punya dua opsi. Anda bisa menonaktifkan peringatan dengan "reportMissingTypeStubs": "none" di konfigurasi Anda. Atau buat stub draf sendiri:

pyright --createstub some_packageDidukung oleh

Ini membuat berkas kerangka .pyi yang bisa Anda isi dengan metode yang benar-benar Anda gunakan.

Kegagalan pre-commit hook

Apakah Pyright bekerja secara lokal tetapi gagal di pre-commit hook? Masalahnya biasanya isolasi lingkungan. Pre-commit menjalankan hook di lingkungan terisolasi yang tidak dapat melihat paket terpasang proyek Anda.

Perbaiki dengan mengarahkan hook ke lingkungan virtual Anda:

repos:
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.408
    hooks:
      - id: pyright
        args: ["--venvpath", ".", "--venv", ".venv"]Didukung oleh

Kesalahan mode strict yang tidak terduga

Mengaktifkan mode strict dan tiba-tiba melihat ribuan kesalahan? Jangan panik. Ini normal. Mode strict mengharuskan anotasi tipe lengkap. Mulailah dengan mode basic atau standard, tambahkan anotasi secara bertahap, dan hanya aktifkan strict pada modul yang sudah sepenuhnya diberi tipe.

Gunakan komentar per berkas untuk menjaga kode lama pada mode longgar:

# pyright: basicDidukung oleh

Ini memungkinkan Anda menegakkan pemeriksaan ketat pada kode baru sambil bermigrasi bertahap pada kode lama.

Di luar pemecahan masalah, berikut beberapa strategi yang akan membuat pengalaman Pyright Anda lebih mulus sejak awal.

Praktik Terbaik Menggunakan Pyright

Setelah bekerja dengan Pyright di berbagai proyek, saya mempelajari beberapa hal yang membuat adopsi lebih mulus. Menerapkan praktik pengkodean terbaik ini memastikan pemeriksaan tipe Anda tetap membantu, bukan menghambat.

Mulai dengan mode standard. Seperti dibahas sebelumnya, ini menangkap bug nyata tanpa membutuhkan anotasi lengkap. Anda selalu bisa memperketat aturan nanti.

Kunci versi Pyright Anda. Pyright sering merilis versi baru, dan versi baru terkadang menandai kode yang sebelumnya lolos. Di CI, pip install pyright tanpa penguncian dapat menyebabkan kegagalan build Senin pagi karena rilis akhir pekan. Saya pernah mengalaminya. Tidak menyenangkan.

[tool.pyright]
# In pyproject.toml
pythonVersion = "3.12"Didukung oleh

# In requirements-dev.txt
pyright==1.1.408Didukung oleh

Perbaiki kesalahan secara bertahap. Jangan mencoba menghilangkan 10.000 kesalahan sekaligus. Gunakan array strict untuk menegakkan pemeriksaan ketat hanya pada direktori tertentu:

{
  "typeCheckingMode": "standard",
  "strict": ["src/core", "src/api"]
}Didukung oleh

Gunakan berkas konfigurasi sejak awal. Bahkan untuk proyek kecil, konfigurasi eksplisit mencegah kejutan. Luangkan lima menit untuk mendokumentasikan versi Python, jalur lingkungan virtual, dan tingkat keketatan yang dipilih. Diri Anda di masa depan akan berterima kasih.

Jangan menargetkan kesempurnaan seketika. Gunakan # pyright: ignore secara longgar pada awalnya. Ini menandai utang teknis secara terlihat sehingga Anda bisa membersihkannya seiring waktu alih-alih menghambat progres. Sempurna adalah musuh kebaikan, terutama saat mengadopsi alat baru.