Untuk mengonfigurasi package discovery bagi proyek Python yang menggunakan tata letak src di macOS, arahkan setuptools ke src di pyproject.toml, lalu atur filter nama paket hanya jika Anda perlu mengontrol paket mana yang akan didistribusikan. Untuk proyek konvensional, setuptools sering kali dapat mendeteksi tata letak secara otomatis; pengaturan penemuan eksplisit berguna ketika Anda menginginkan penyertaan atau pengecualian yang dapat diprediksi. Petunjuk ini berlaku untuk setuptools, bukan setiap build backend Python.

Periksa struktur proyek dan build backend

Dari Terminal, berpindahlah ke root proyek—folder yang berisi pyproject.toml—dan periksa file menggunakan shell default macOS, zsh, atau dengan bash jika itu adalah shell yang Anda konfigurasikan:

cd '/path/to/project'
find src -maxdepth 3 -type f -print

Ganti jalur dalam tanda kutip dengan lokasi proyek yang sebenarnya. Tanda kutip tunggal mencegah spasi dan karakter meta shell dalam jalur agar tidak terinterpretasi. Paket tipikal mungkin berada di src/my_package/__init__.py, dengan subpaket di direktori bawahnya. Nama impornya adalah my_package; direktori bernama src hanyalah sebuah wadah dan bukan bagian dari nama tersebut.

Periksa apakah pyproject.toml memilih setuptools di bawah [build-system], misalnya dengan requires = ["setuptools>=61"] dan build-backend = "setuptools.build_meta". Dokumentasi setuptools menjelaskan penemuan otomatis untuk tata letak umum, termasuk src, ketika daftar paket dan modul tidak disediakan secara eksplisit. Backend lain memiliki konfigurasinya sendiri, jadi jangan menyalin pengaturan setuptools ke dalam tabel konfigurasi backend lain. Setuptools: Configuring setuptools using pyproject.toml files

Konfigurasikan penemuan eksplisit di pyproject.toml

Jika Anda menginginkan penemuan yang berakar secara khusus di src, tambahkan konfigurasi setuptools berikut ke file yang sudah ada:

[tool.setuptools.packages.find]
where = ["src"]

Ini memberi tahu setuptools tempat mencari paket. Ini tidak mengubah nama proyek atau nama impor paket. Jika Anda sudah memiliki tabel [tool.setuptools.packages.find], edit tabel tersebut alih-alih menambahkan yang kedua. File TOML tidak boleh berisi definisi duplikat dari tabel yang sama.

Untuk membatasi penemuan pada satu paket dan subpaketnya, tambahkan pola include yang cocok dengan nama paket bertitik lengkap:

[tool.setuptools.packages.find]
where = ["src"]
include = ["my_package*"]

Ganti my_package dengan nama paket impor yang sebenarnya. Tanda * memungkinkan pola tersebut mencocokkan subpaket seperti my_package.tools; pola dicocokkan dengan nama paket lengkap. Anda juga dapat mengecualikan paket tertentu, misalnya exclude = ["my_package.tests*"]. Setuptools mendokumentasikan pola include dan exclude ini, serta where, dalam panduan package discovery miliknya.

Pilih cara penemuan menangani paket namespace

Secara default, penemuan pyproject.toml milik setuptools memindai paket namespace implisit: direktori dapat diperlakukan sebagai paket bahkan ketika tidak berisi __init__.py. Pertahankan pengaturan default ini jika paket Anda sengaja menggunakan paket namespace PEP 420. Jika setiap paket harus memiliki __init__.py, Anda dapat menonaktifkan pemindaian namespace:

[tool.setuptools.packages.find]
where = ["src"]
namespaces = false

Dengan pengaturan ini, direktori tanpa __init__.py tidak akan ditemukan sebagai paket. Oleh karena itu, paket yang hilang dalam distribusi yang dibangun dapat dijelaskan oleh lokasi pencarian, pola include atau exclude, atau pengaturan namespace. Panduan pengemasan membahas perilaku ini dan menunjukkan bagaimana penemuan dapat dibatasi pada paket namespace tertentu. Python Packaging User Guide: Packaging namespace packages

Ketahui kapan penemuan otomatis sudah cukup

Untuk proyek src/my_package yang sederhana, Anda mungkin tidak memerlukan tabel penemuan sama sekali. Setuptools dapat mengenali tata letak umum ketika packages dan py-modules dibiarkan tidak ditentukan. Tambahkan konfigurasi eksplisit saat Anda perlu mempersempit pemilihan paket, menangani struktur pohon yang kurang konvensional, atau memperjelas direktori sumber tanpa ambigu. Hindari membuat daftar paket secara terpisah dalam kode (hard-coding) kecuali Anda berniat untuk memeliharanya saat struktur pohon paket berubah; daftar eksplisit dapat membuat subpaket yang baru ditambahkan mudah terlewatkan.

Tata letak src juga berarti bahwa menjalankan Python dari root repositori tidak otomatis menempatkan paket pada jalur impor (import path). Hal itu sudah diduga: dokumentasi setuptools mencatat bahwa penginstalan editable (editable install) diperlukan untuk menggunakan paket dari checkout sumber dengan cara ini. Konfigurasi penemuan mengontrol apa yang disertakan dalam distribusi; ini bukan pengganti untuk menginstal proyek ke dalam lingkungan Python yang Anda gunakan untuk pengembangan. Setuptools: Package Discovery and Namespace Packages

Sumber