Build System dan Package Metadata

Tabel [project] pada pyproject.toml menjawab pertanyaan “apa yang dibangun”. Pertanyaan “bagaimana membangunnya” dijawab oleh tabel [build-system]. Keduanya bekerja sebagai pasangan: tool seperti pip membaca [build-system] untuk menyiapkan mesin build, lalu mesin tersebut membaca [project] dan menghasilkan metadata. Pada chapter ini kita menelusuri perjalanan metadata — dari baris TOML sampai berkas METADATA di dalam wheel — dan melihat buktinya dari build sungguhan.

Tabel [build-system] #

Deklarasi standar untuk backend setuptools:

toml
[build-system]
requires = ["setuptools>=77"]
build-backend = "setuptools.build_meta"

Mari kita telaah arti kedua baris tersebut:

requires: daftar paket yang harus dipasang di environment build terisolasi sebelum proses build berjalan. Front-end seperti pip atau build membuat virtual environment sementara khusus untuk ini, terpisah dari venv project kita.
build-backend: nama objek Python yang menyediakan hook build — fungsi seperti build_wheel() dan build_sdist(). Nilai setuptools.build_meta berarti “pergunakan setuptools sebagai backend”.

PEP 517 dan PEP 660 dalam Satu Paragraf #

Dahulu pip harus menjalankan setup.py di direktori project untuk membangun package — pendekatan yang lambat dan tidak aman karena mengeksekusi kode bebas saat instalasi. PEP 517 menggantinya dengan antarmuka standar: front-end (pip, build) memanggil hook dari backend yang dideklarasikan build-backend, semuanya di environment terisolasi. PEP 660 memperluas antarmuka ini dengan hook build_editable() yang membuat editable install (Chapter Editable Install) tetap berjalan melalui jalur standar alih-alih trik path.

Backend Alternatif #

setuptools bukan satu-satunya pilihan:

Backend	Ciri khas
`setuptools.build_meta`	paling umum, warisan de facto, cocok untuk hampir semua project
`hatchling`	modern dan cepat, konfigurasi ringkas, default dari tool `hatch`
`flit_core`	paling sederhana, untuk package Python murni tanpa ekstensi
`uv_build`	backend muda dari tool `uv`, ditujukan untuk project sederhana

Front-end tidak peduli backend mana yang dipakai selama hook standarnya tersedia — itulah manfaat PEP 517. Migrasi dari setuptools ke hatchling, misalnya, tidak mengubah cara pengguna memasang package kita.

Ke Mana Metadata Pergi #

Untuk melihat hasil akhir metadata, kita perlu package sungguhan. Chapter berikutnya membangun package demo-pkg langkah demi langkah; di sini kita langsung membedah hasil build-nya. Wheel adalah arsip ZIP, jadi berkas METADATA bisa dibaca tanpa mengekstrak:

bash

unzip -p dist/demo_pkg-0.1.0-py3-none-any.whl demo_pkg-0.1.0.dist-info/METADATA

Output yang Dihasilkan:

text
Metadata-Version: 2.4
Name: demo-pkg
Version: 0.1.0
Summary: Contoh package kecil untuk belajar build
Author-email: Budi Santoso <[email protected]>
License-Expression: MIT
Project-URL: Homepage, https://example.com/demo-pkg
Keywords: demo,tutorial
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# demo-pkg

Package kecil untuk mempelajari build wheel dan sdist.

Perhatikan pemetaannya: kunci name menjadi header Name:, description menjadi Summary:, requires-python menjadi Requires-Python:, dan setiap classifiers menjadi satu baris Classifier:. Format ini disebut core metadata — format yang dibaca pip saat memeriksa apakah sebuah package cocok dengan interpreter pengguna. Baris kosong di tengah menandai batas antara header dan long description, yaitu isi README.md yang di-render PyPI sebagai halaman package.

README dan Classifiers di PyPI #

Ketika package diunggah (Chapter Mendistribusikan Python Package), PyPI merender Description-Content-Type: text/markdown sebagai halaman depan — itulah mengapa readme = "README.md" perlu dideklarasikan. Sementara itu, classifiers mempermudah penemuan: Programming Language :: Python :: 3 menyatakan dukungan Python modern, Operating System :: OS Independent menyatakan package berjalan lintas platform. Daftar lengkap classifier resmi ada di situs PyPI; gunakan yang relevan saja, karena classifier yang salah menyesatkan pencarian.

Dengan memahami siapa yang membangun apa, kita siap menjalankan proses buildnya sendiri dan melihat dua artefaknya: wheel dan sdist.