pyproject.toml

Setiap package Python butuh metadata: siapa pembuatnya, berapa versinya, dependency apa saja yang dibutuhkan. Selama dua dekade metadata itu ditulis di setup.py — file berisi kode Python yang benar-benar dieksekusi saat membangun package, sehingga tool lain harus menjalankan kode sembarangan hanya untuk membaca nama package. pyproject.toml menggantikan pendekatan itu dengan satu file konfigurasi terstruktur yang aman dibaca semua tool. Pada chapter ini kita bedah anatomi file tersebut.

Format TOML dalam Dua Menit #

TOML (Tom’s Obvious, Minimal Language) adalah format konfigurasi berbasis pasangan kunci-nilai dengan tiga aturan inti:

• kunci = "nilai" untuk mengikat satu nilai; string memakai tanda kutip, sedangkan angka dan true/false ditulis langsung.
• Bagian ditulis dalam tanda kurung siku: [project], [build-system]. Seluruh kunci di bawahnya milik bagian tersebut.
• Array ditulis dalam kurung siku; array panjang boleh dipecah beberapa baris dengan koma di akhir tiap baris.

Chapter tomllib pada Section Modern Python membahas cara membaca file TOML dari kode Python; kita cukup memakai sintaksnya di sini.

Tabel build-system dan project #

File pyproject.toml minimal memuat dua tabel. Berikut file asli yang dipakai untuk package contoh konverter-suhu pada chapter-chapter selanjutnya:

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

[project]
name = "konverter-suhu"
version = "0.1.0"
description = "Contoh package Python untuk mengonversi suhu"
readme = "README.md"
license = "MIT"
authors = [
    { name = "Budi Santoso", email = "[email protected]" },
]
requires-python = ">=3.10"
dependencies = []

Mari kita bedah tabel per tabel:

1. [build-system]: menentukan alat yang membangun package. requires mendata build tool beserta versi minimum yang harus disiapkan; build-backend menunjuk titik masuk backend — di sini setuptools, backend paling lazim.
2. [project]: metadata inti package sesuai standar PEP 621. Tabel inilah yang dibaca pip saat menyelesaikan dependency dan ditampilkan PyPI di halaman package.

Kunci-kunci tabel [project] yang paling sering kita tulis:

Array dependencies berisi string dengan format yang persis seperti argumen pip install, misalnya "requests>=2.31". Nilai kosong seperti di atas sah: package contoh kita memang tidak butuh dependency.

Membaca pyproject.toml dari Kode Python #

Interpreter Python bisa membaca file TOML tanpa package tambahan sejak Python 3.11 melalui module tomllib. Simpan contoh berikut sebagai contoh-pyproject.toml lalu jalankan script pembacanya:

[project]
name = "aplikasi-penjualan"
version = "1.2.0"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31",
    "rich>=13.0",
]

import tomllib

with open("contoh-pyproject.toml", "rb") as f:
    data = tomllib.load(f)

print(data["project"]["name"])
print(data["project"]["version"])
print(data["project"]["dependencies"])

Output yang Dihasilkan:

aplikasi-penjualan
1.2.0
['requests>=2.31', 'rich>=13.0']

1. Baris 3 (with open(..., "rb") as f): tomllib hanya membaca berkas biner, jadi mode "rb" wajib.
2. Baris 4 (tomllib.load(f)): menghasilkan dictionary bersarang — setiap tabel TOML menjadi key di level atas.
3. Baris 6-8 (print(...)): nilai dependencies berupa list berisi string, siap diolah program.

pyproject.toml versus setup.py #

Kedua file pernah (dan masih) melayani kebutuhan yang sama. Perbedaan fundamentalnya: