Membangun Wheel dan sdist

Chapter Membangun Python Package memperlihatkan hasil akhir build dalam beberapa baris. Kali ini kita masuk lebih dalam: menjalankan build pada package nyata, membuka isi kedua artefaknya, dan memahami apa yang dipilih pip ketika keduanya tersedia. Pemahaman ini penting saat build gagal, saat berkas hilang dari wheel, atau saat kita perlu memutuskan artefak mana yang didistribusikan.

Package Demo #

Kita bekerja pada package kecil demo-pkg dengan src layout:

text
demo-pkg/
├── LICENSE
├── README.md
├── pyproject.toml
└── src/
    └── demo_pkg/
        ├── __init__.py
        └── cli.py

Berkas pyproject.toml berisi metadata dari chapter sebelumnya, plus satu deklarasi sapa-demo = "demo_pkg.cli:main" di [project.scripts] (dibahas tuntas pada Chapter Membuat Command-Line Entry Points). Dari dalam folder demo-pkg, jalankan:

bash

python -m build

Output yang Dihasilkan:

text
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - setuptools>=77
* Getting build dependencies for sdist...
* Installed build dependency versions:
  - setuptools==84.0.0
* Building sdist...
* Building wheel from sdist
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - setuptools>=77
* Installed build dependency versions:
  - setuptools==84.0.0
* Building wheel...
Successfully built demo_pkg-0.1.0.tar.gz and demo_pkg-0.1.0-py3-none-any.whl

Baris-baris * pada transkrip di atas diringkas; baris running egg_info dan kawan-kawannya menampilkan pekerjaan internal setuptools. Perhatikan urutannya: front-end build membangun sdist lebih dulu, lalu membangun wheel dari sdist tersebut — bukan dari folder kerja. Strategi ini membuktikan bahwa sdist kita memuat segala yang dibutuhkan untuk membangun wheel; kalau ada berkas penting yang tertinggal, build gagal di sini, bukan di komputer pengguna. Hasilnya tersimpan di folder dist/:

text
dist/
├── demo_pkg-0.1.0-py3-none-any.whl
└── demo_pkg-0.1.0.tar.gz

Melongok Isi Wheel #

Wheel adalah arsip ZIP dengan tata letak khusus. Daftar isinya bisa dilihat tanpa mengekstrak:

bash

unzip -l dist/demo_pkg-0.1.0-py3-none-any.whl

Output yang Dihasilkan:

text
Archive:  dist/demo_pkg-0.1.0-py3-none-any.whl
  Length      Date    Time    Name
---------  ---------- -----   ----
      138  2026-10-12 23:01   demo_pkg/__init__.py
      139  2026-10-12 23:01   demo_pkg/cli.py
       12  2026-10-12 23:02   demo_pkg-0.1.0.dist-info/licenses/LICENSE
      519  2026-10-12 23:02   demo_pkg-0.1.0.dist-info/METADATA
       91  2026-10-12 23:02   demo_pkg-0.1.0.dist-info/WHEEL
       48  2026-10-12 23:02   demo_pkg-0.1.0.dist-info/entry_points.txt
        9  2026-10-12 23:02   demo_pkg-0.1.0.dist-info/top_level.txt
      639  2026-10-12 23:02   demo_pkg-0.1.0.dist-info/RECORD
---------                     -------
     1595                     8 files

Folder demo_pkg/ berisi kode yang dipasang ke site-packages pengguna — perhatikan folder src/ sudah tidak ada; setuptools memindahkannya saat build. Folder dist-info/ (disingkat dari distribution info) berisi kaki tangan pip:

Berkas	Peran
`METADATA`	hasil render tabel `[project]` (dibedah pada chapter sebelumnya)
`WHEEL`	versi format wheel dan generator yang membangunnya
`entry_points.txt`	perintah CLI yang harus dibuatkan wrapper
`top_level.txt`	nama package tingkat atas
`RECORD`	daftar semua berkas beserta hash-nya — dipakai pip untuk uninstall bersih

Melongok Isi sdist #

sdist adalah arsip tar.gz berisi kode sumber lengkap:

bash

tar -tzf dist/demo_pkg-0.1.0.tar.gz

Output yang Dihasilkan:

text
demo_pkg-0.1.0/
demo_pkg-0.1.0/LICENSE
demo_pkg-0.1.0/PKG-INFO
demo_pkg-0.1.0/README.md
demo_pkg-0.1.0/pyproject.toml
demo_pkg-0.1.0/setup.cfg
demo_pkg-0.1.0/src/
demo_pkg-0.1.0/src/demo_pkg/
demo_pkg-0.1.0/src/demo_pkg/__init__.py
demo_pkg-0.1.0/src/demo_pkg/cli.py
demo_pkg-0.1.0/src/demo_pkg.egg-info/
demo_pkg-0.1.0/src/demo_pkg.egg-info/PKG-INFO
demo_pkg-0.1.0/src/demo_pkg.egg-info/SOURCES.txt
demo_pkg-0.1.0/src/demo_pkg.egg-info/dependency_links.txt
demo_pkg-0.1.0/src/demo_pkg.egg-info/entry_points.txt
demo_pkg-0.1.0/src/demo_pkg.egg-info/top_level.txt

Perhatikan perbedaan penting dibanding wheel: sdist memuat pyproject.toml, README.md, dan LICENSE — berkas build yang dibutuhkan untuk membangun ulang package — sedangkan wheel tidak, karena wheel adalah hasil akhir yang tinggal diekstrak. Berkas PKG-INFO adalah salinan metadata (format yang sama dengan METADATA), dan setup.cfg dihasilkan otomatis setuptools.

Wheel atau sdist, Kapan Dipakai #

Aspek	sdist (`.tar.gz`)	wheel (`.whl`)
Jenis	kode sumber	artefak siap pasang
Dipasang pip	dibangun dulu di mesin pengguna	diekstrak langsung, tanpa build
Menjalankan kode build	ya — mengeksekusi `build_backend`	tidak
Situasi khas	package tanpa wheel terbit, atau pengguna perlu memodifikasi	jalur normal instalasi sehari-hari

pip selalu memilih wheel bila tersedia dan kompatibel; sdist menjadi cadangan. Kedua artefak lazim diunggah bersama agar pengguna tetap bisa membangun dari sumber.

Memeriksa Artefak dengan twine #

Sebelum mengunggah ke PyPI, tool resmi twine memeriksa metadata dan rendering README:

bash

twine check dist/*

Output yang Dihasilkan (ilustratif — twine tidak terpasang di lingkungan pengujian materi ini):

text

Checking dist/demo_pkg-0.1.0-py3-none-any.whl: PASSED
Checking dist/demo_pkg-0.1.0.tar.gz: PASSED

Dengan artefak yang terbukti sehat, langkah berikutnya adalah memberi pengguna sebuah perintah: entry points.