Untuk menguji wheel yang benar-benar dibangun oleh proyek Anda, buat lingkungan virtual macOS baru, instal file wheel dari dist/, dan periksa apakah metadata serta perilaku impornya sudah benar. Jalankan perintah di bawah ini dari direktori proyek Anda di Terminal. Langkah ini menguji instalasi untuk versi Python dan arsitektur Mac yang Anda gunakan; ini tidak memastikan kompatibilitas dengan setiap versi Python atau Mac yang didukung.

1. Bangun wheel dari proyek Anda

Gunakan interpreter Python yang ingin Anda uji. Di macOS, python3 adalah perintah umum untuk Python 3; jika Anda menggunakan pengelola versi, pilih interpreter yang diinginkan terlebih dahulu. Dari direktori yang berisi pyproject.toml, bangun wheel dengan alat build milik Python Packaging Authority: Packaging Python Projects mendokumentasikan langkah pembuatan ini dan direktori dist/ yang dihasilkan.

python3 -m pip install --upgrade build
python3 -m build --wheel

Perintah build membuat file .whl di dist/. Membangun dari root proyek membuat artefak tersebut tersedia untuk pengujian instalasi di bawah ini. Wheel adalah distribusi bawaan yang ingin Anda uji; menginstal direktori proyek atau menggunakan mode yang dapat diedit (editable mode) akan menguji jalur instalasi yang berbeda. Lihat The Packaging Flow untuk perbedaan antara pohon sumber (source tree), artefak build, dan instalasi.

2. Buat lingkungan virtual baru

Buat lingkungan tersebut di direktori proyek, tetapi pisahkan hasil build darinya. Jika .venv-wheel-test sudah ada dan Anda menginginkan eksekusi yang bersih, hapus terlebih dahulu; perintah ini menghapus direktori tertentu tersebut beserta isinya secara permanen, jadi pastikan jalurnya sudah benar sebelum menjalankannya.

rm -rf .venv-wheel-test
python3 -m venv .venv-wheel-test
source .venv-wheel-test/bin/activate
python -m pip --version

Jalur pip yang dilaporkan harus memuat .venv-wheel-test. venv Python membuat lingkungan terisolasi berdasarkan interpreter yang digunakan untuk membuatnya, dengan paket terinstalnya sendiri; zsh default Terminal macOS mendukung perintah aktivasi source yang ditunjukkan di sini. Dokumentasi venv Python menjelaskan isolasi dan aktivasi. Untuk menghindari ketergantungan pada aktivasi atau pada python mana yang ada di jalur shell Anda, gunakan .venv-wheel-test/bin/python sebagai pengganti python pada perintah selanjutnya.

3. Instal file wheel, bukan direktori sumber

Daftar file wheel agar Anda dapat mengidentifikasi artefak pasti yang akan diuji:

ls dist/*.whl

Salin nama file yang diinginkan dari output ke perintah di bawah ini. Pertahankan tanda kutip, dan ganti nama file contoh dengan nama file yang sebenarnya. Nama file dengan tanda hubung yang ditampilkan hanyalah ilustrasi; nama wheel mencakup nama distribusi, versi, dan tag kompatibilitas, jadi nama Anda akan berbeda.

python -m pip install "dist/my_package-1.2.3-py3-none-any.whl"

Ini menginstal wheel lokal dan menyelesaikan dependensi yang dideklarasikan dari indeks paket yang dikonfigurasi jika diperlukan. Ini tidak menginstal direktori sumber Anda. pip mendukung instalasi arsip distribusi lokal secara langsung, seperti yang dijelaskan dalam Install packages in a virtual environment using pip and venv. Jika pengujian harus berjalan tanpa akses jaringan, sediakan juga dependensi wheel secara lokal; jika tidak, resolusi dependensi dapat gagal. Jika Anda menggunakan --no-deps, pip melewati instalasi dependensi, sehingga impor yang memerlukan paket-paket tersebut dapat gagal bahkan ketika wheel itu sendiri berhasil diinstal dengan benar.

4. Periksa instalasi dan perilaku impor

Periksa metadata distribusi yang diinstal dan apakah dependensi yang dideklarasikan sudah konsisten:

python -m pip show my-package
python -m pip check

Gunakan nama distribusi yang ditunjukkan dalam nama file wheel atau metadata proyek untuk pip show; namanya dapat berbeda dari nama impor Python. Kemudian uji impor menggunakan nama modul yang didokumentasikan oleh paket Anda. Misalnya, jika modulnya adalah my_package, jalankan:

python -c 'import my_package; print(my_package.__file__)'

Impor yang berhasil dengan jalur file yang mengarah ke dalam .venv-wheel-test membuktikan bahwa paket yang diinstal sedang diimpor dari lingkungan pengujian. Pengujian impor saja tidak menguji setiap fungsi atau titik masuk: jalankan pengujian relevan dari proyek Anda terhadap lingkungan ini jika Anda memerlukan cakupan perilaku.

Saat wheel gagal diinstal

Kesalahan tentang wheel yang tidak kompatibel biasanya berarti tag kompatibilitasnya tidak cocok dengan Python yang aktif, macOS, atau arsitektur CPU. Wheel yang berisi ekstensi yang dikompilasi bisa bersifat spesifik platform; wheel Python murni (pure-Python) dapat digunakan secara lebih luas. Spesifikasi tag kompatibilitas platform menjelaskan bagaimana penginstal menggunakan tag tersebut. Bangun atau dapatkan wheel yang kompatibel untuk interpreter dan arsitektur Mac yang ingin Anda dukung, lalu ulangi pengujian di lingkungan yang baru dibuat.

Jika instalasi berhasil tetapi impor gagal, periksa apakah nama impor sudah benar dan dependensi runtime yang diperlukan telah dideklarasikan oleh proyek. Jika wheel terinstal tetapi melewatkan modul atau file data, periksa konten wheel dan perbaiki konfigurasi pemaketan proyek sebelum membangun kembali. Lingkungan yang bersih membantu mengekspos dependensi yang tidak dideklarasikan dan file paket yang hilang, yang mungkin tersamarkan oleh paket atau file sumber di lingkungan pengembang.

Instalasi yang berhasil, pemeriksaan dependensi, dan impor terarah mengonfirmasi bagian-bagian berguna dari perilaku wheel di Mac dan versi Python ini. Langkah-langkah tersebut tidak memverifikasi platform atau versi Python lainnya; uji platform tersebut secara terpisah dengan interpreter yang cocok dan build wheel yang kompatibel.

Sumber