typeshed
1.0.0
Typeshed berisi anotasi tipe eksternal untuk pustaka standar Python dan bawaan Python, serta paket pihak ketiga yang disumbangkan oleh orang-orang di luar proyek tersebut.
Data ini misalnya dapat digunakan untuk analisis statis, pengecekan tipe, inferensi tipe, dan pelengkapan otomatis.
Untuk informasi tentang cara menggunakan typeshed, baca di bawah. Informasi untuk kontributor dapat ditemukan di CONTRIBUTING.md. Harap membacanya sebelum mengirimkan permintaan penarikan; jangan laporkan masalah dengan anotasi pada proyek yang menjadi tujuan stub tersebut, namun laporkan di sini untuk diketik.
Dokumentasi lebih lanjut mengenai file rintisan, pengetikan, dan sistem pengetikan Python secara umum, juga dapat ditemukan di https://typing.readthedocs.io/en/latest/.
Typeshed mendukung Python versi 3.8 hingga 3.13.
Jika Anda hanya menggunakan pemeriksa tipe (mypy, pyright, pytype, PyCharm, ...), dibandingkan mengembangkannya, Anda tidak perlu berinteraksi dengan repo yang diketik sama sekali: salinan bagian perpustakaan standar dari typeshed dibundel dengan pemeriksa tipe. Dan ketik stub untuk paket dan modul pihak ketiga yang Anda gunakan dapat diinstal dari PyPI. Misalnya, jika Anda menggunakan html5lib dan requests , Anda dapat menginstal tipe stubs menggunakan
$ pip install types-html5lib types-requestsPaket PyPI ini mengikuti PEP 561 dan dirilis secara otomatis (hingga sekali sehari) oleh mesin internal yang diketik.
Pemeriksa tipe harus dapat menggunakan paket rintisan ini ketika diinstal. Untuk detail selengkapnya, lihat dokumentasi untuk pemeriksa tipe Anda.
Nomor versi paket rintisan pihak ketiga terdiri dari setidaknya empat bagian. Semua bagian dari versi stub, kecuali bagian terakhir, sesuai dengan versi paket runtime yang di-stub. Misalnya, jika paket types-foo memiliki versi 1.2.0.20240309 , ini menjamin bahwa paket types-foo berisi stub yang ditargetkan terhadap foo==1.2.* dan diuji terhadap versi terbaru foo yang cocok dengan penentu tersebut. Dalam contoh ini, elemen terakhir nomor versi (20240309) menunjukkan bahwa paket stub dikirimkan pada tanggal 9 Maret 2024.
Saat mengetik, kami mencoba meminimalkan perubahan. Namun, karena sifat dari stub, perubahan versi apa pun dapat menyebabkan perubahan yang mungkin membuat kode Anda gagal untuk diketik.
Ada beberapa strategi yang tersedia untuk menentukan versi paket stub yang Anda gunakan, masing-masing memiliki konsekuensinya sendiri:
Gunakan batas yang sama dengan yang Anda gunakan untuk paket yang di-stub. Misalnya, jika Anda menggunakan requests>=2.30.0,<2.32 , Anda dapat menggunakan types-requests>=2.30.0,<2.32 . Hal ini memastikan bahwa stub tersebut kompatibel dengan paket yang Anda gunakan, namun ada risiko kecil kerusakan pemeriksaan tipe karena perubahan pada stub.
Risiko lain dari strategi ini adalah bahwa stub sering kali tertinggal dari paket yang di-stub. Anda mungkin ingin memaksa paket yang di-stub ke versi minimum tertentu karena ini memperbaiki bug kritis, namun jika stub yang diperbarui belum dirilis, hasil pemeriksaan tipe Anda mungkin tidak sepenuhnya akurat.
Sematkan stub ke versi yang diketahui baik dan perbarui pin dari waktu ke waktu (baik secara manual, atau menggunakan alat seperti dependabot atau renovate).
Misalnya, jika Anda menggunakan types-requests==2.31.0.1 , Anda dapat yakin bahwa peningkatan dependensi tidak akan merusak pemeriksaan tipe. Namun, Anda akan kehilangan perbaikan pada stub yang berpotensi meningkatkan pemeriksaan tipe sampai Anda memperbarui pin. Strategi ini juga memiliki risiko bahwa stub yang Anda gunakan mungkin menjadi tidak kompatibel dengan paket yang di-stub.
Jangan sematkan potongannya. Ini adalah opsi yang paling sedikit menuntut pekerjaan Anda ketika harus memperbarui pin versi, dan memiliki keuntungan bahwa Anda secara otomatis akan mendapat manfaat dari stub yang ditingkatkan setiap kali versi baru dari paket stubs dirilis. Namun, hal ini mempunyai risiko bahwa stub tersebut menjadi tidak kompatibel dengan paket yang di-stub.
Misalnya, jika versi utama baru dari paket dirilis, ada kemungkinan stub tersebut diperbarui untuk mencerminkan versi baru dari paket runtime sebelum Anda memperbarui paket yang di-stub.
Anda juga dapat beralih di antara berbagai strategi sesuai kebutuhan. Misalnya, Anda dapat menggunakan strategi (1) secara default, namun kembali ke strategi (2) ketika muncul masalah yang tidak dapat diperbaiki dengan mudah.
_typeshed typeshed menyertakan paket _typeshed sebagai bagian dari perpustakaan standar. Paket ini dan submodulnya berisi tipe utilitas, tetapi tidak tersedia saat runtime. Untuk informasi lebih lanjut tentang cara menggunakan paket ini, lihat direktori stdlib/_typeshed .
Jika Anda mengalami perilaku di pemeriksa tipe yang menyarankan stub tipe untuk perpustakaan tertentu salah atau tidak lengkap, kami ingin mendengar pendapat Anda!
Forum diskusi utama kami adalah pelacak isu GitHub proyek tersebut. Ini adalah tempat yang tepat untuk memulai diskusi tentang salah satu topik di atas atau topik lainnya mengenai proyek.
Jika Anda memiliki pertanyaan umum tentang mengetik dengan Python, atau Anda perlu meninjau anotasi tipe atau stub di luar tipe yang diketik, kunjungi forum diskusi kami. Untuk diskusi yang tidak terlalu formal, cobalah ruang obrolan mengetik di gitter.im. Beberapa pengelola typeshed hampir selalu ada; jangan ragu untuk menemukan kami di sana dan kami senang mengobrol. Pembahasan teknis subtantif akan diarahkan ke issue tracking.
