Файл pyproject.toml хранит метаданные проекта и настройки инструментов в одном стандартном формате. Для устанавливаемого пакета нужны две части: описание проекта и выбор backend, который выполнит сборку.

Минимальный пример

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

[project]
name = "sample-package"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "requests>=2.32,<3",
]

Имя проекта относится к дистрибутиву, а не обязательно к импортируемому модулю. Значение requires-python сообщает установщику, с какими версиями интерпретатора совместим выпуск.

Зачем нужен build-system

pip не должен угадывать, как превратить исходники в wheel. Таблица указывает backend и зависимости, необходимые для изолированной сборки. Вместо setuptools можно выбрать Hatchling, Flit, PDM backend или другой совместимый инструмент. PyPA разбирает поля в руководстве Writing your pyproject.toml.

Где хранить исходный код

Для библиотеки удобна структура src/sample_package/. Она не дает тестам случайно импортировать код прямо из корня репозитория. После этого выполните editable install и проверьте импорт из виртуального окружения.

Следующая проверка

Соберите wheel и sdist в чистой среде, затем установите wheel в новое окружение. Пошаговый процесс описан в статье про сборку и TestPyPI. Конфигурация считается рабочей только после установки полученного артефакта, а не после успешного чтения TOML-файла редактором.