pyproject.toml и точки входа: бэкенды сборки, src-раскладка и шимы консольных скриптов

pyproject.toml: один файл, два контракта

Прежде чем трогать бэкенд сборки или разбираться, почему pip install делает именно это, задайте себе вопрос: какую из двух принципиально разных задач решает этот файл прямо сейчас? Ответ меняет то, какую таблицу редактировать и какой инструмент винить, когда что-то идёт не так.

В pyproject.toml два разделимых контракта. Таблица [project] — метаданные: имя, версия, dependencies (диапазоны версий — это декларация библиотеки, а не лок-файл) и optional-dependencies (экстры вроде mytool[postgres], которые потребители включают сами). Таблица [build-system] отвечает на другой вопрос: кто превращает это дерево исходников в устанавливаемый артефакт. Названный бэкенд сборки — hatchling, setuptools, flit-core — это библиотека со стандартизованными хуками (build_wheel, build_sdist); фронтенды — pip, uv, python -m build — вызывают эти хуки в изолированном окружении с установленным requires. В этом разделении вся современная упаковка: pip не умеет собирать ваш проект, он умеет лишь спросить бэкенд. Бэкенды различаются конфигурацией и дефолтами, а не природой артефакта: у hatchling строгий, предсказуемый отбор файлов; setuptools несёт два десятилетия совместимости (и то самое автообнаружение, упаковавшее tests/ из Хука); flit-core минимален для чистого Python. Один по-настоящему сеньорский рычаг: dynamic = ["version"] плюс VCS-плагин (hatch-vcs, setuptools-scm) выводит версию из git-тега при сборке — один источник истины, никакого релизного коммита, бампающего строку в двух файлах и промахивающегося в одном.

src-раскладка: тестируйте то, что поставляете

Плоская раскладка кладёт импортируемый пакет в корень репозитория. Ловушка — арифметика sys.path из урока про импорты: запустите тесты из корня — и локальный каталог mytool/ выиграет каждый импорт, то есть тесты гоняют дерево исходников и никогда — собранный артефакт. Wheel без сабпакета, потерянный отбором файлов файл данных, протухшая точка входа — всё невидимо, потому что артефакт ни разу не на скамье подсудимых. Раскладка src/ уносит пакет в src/mytool/, которого нет на sys.path, — теперь import mytool может разрешиться только в установленный пакет, и прогон тестов проверяет ровно то, что произвёл pip install. Это и есть защита от «локально тесты зелёные, поехал сломанный wheel», и именно такую раскладку uv создаёт по умолчанию. Честная цена: перед тестами нужно ставить пакет (editable-установка делает это одноразовым шагом), а быстрые эксперименты python -c "import mytool" из корня репозитория перестают работать — что и требовалось.

Editable-установка: .pth-редирект и его пределы

pip install -e . (или установка, которую uv sync выполняет для проекта воркспейса) не копирует ваш код. Бэкенд пишет в site-packages редирект — классически файл .pth (специальный файл-путь, который Python читает при старте и автоматически добавляет указанные пути к sys.path), добавляющий ваш src/ в sys.path, либо маленький импорт-хук для более тонкого контроля. Результат: окружение импортирует ваше рабочее дерево вживую; правка, перезапуск, без переустановки. Пределы прямо следуют из того, что не передиректили: метаданные — это снимок. Зависимости, точки входа, консольные скрипты — всё записано в момент установки. Добавьте новую запись в [project.scripts] или зависимость — editable-установка не узнает об этом до переустановки. Симптом всегда одной формы: «я добавил команду, а её нет на PATH» — код живой, метаданные заморожены.

Точки входа: консольные скрипты и обнаружение плагинов

[project.scripts] mycli = "mytool.cli:main" — метаданные, и действует по ним установщик: в момент установки он генерирует маленький исполняемый шим в каталоге bin/ окружения — на PATH, пока venv активен, — вся работа которого: from mytool.cli import main; sys.exit(main()). Ваш исходный файл никогда не попадает на PATH, ему не нужны ни chmod +x, ни шебанг; шим заодно объясняет, зачем была дисциплина -m из прошлого урока — шим импортирует ваш модуль с полным пакетным контекстом, а не исполняет файл. Возврат main становится кодом выхода.

Тот же механизм метаданных обобщается в плагинные системы. Любой дистрибутив может объявить точки входа под произвольным именем группы; любая программа может спросить importlib.metadata.entry_points(group="pytest11") и получить регистрации всех установленных дистрибутивов — чтение установленных метаданных, без сканирования файлов, без реестра, без конфигурации. Ровно так pytest находит плагины: поставьте pytest-cov — он появится в группе pytest11, pytest подгрузит его на старте; удалите — исчезнет. Две продакшен-заметки: стоимость обнаружения растёт с числом установленных дистрибутивов (дёшево, но не бесплатно в толстых окружениях), а загрузка точки входа импортирует модуль плагина — плагин с сайд-эффектами времени импорта наследует все режимы отказа прошлого урока, теперь срабатывающие на чужом старте.

Экстры против групп зависимостей

Если видите pytest в install_requires библиотеки — или экстру dev, тянущую линтеры в окружение каждого потребителя, — это именно та путаница, от которой существует этот раздел.

Два механизма, две аудитории, путают регулярно. Экстры (optional-dependencies) — публикуемые метаданные: mytool[postgres] — фича-флаг, который ставят ваши потребители; зависимости экстры едут в метаданных wheel на весь мир. Группы зависимостей ([dependency-groups], PEP 735) — сторона разработки: тест-раннеры, линтеры, тайп-чекеры — их разрешает ваш тулинг (uv по умолчанию ставит группу dev в воркспейс), и они никогда не публикуются в wheel. Отсюда дисциплина: pytest не место в экстре — экстра mytool[test] повезёт ваш тестовый стек каждому любопытному потребителю и загрязнит его разрешение версий; фичи живут в экстрах, рабочие процессы — в группах. Легаси-проекты имитируют группы экстрой dev, потому что старый тулинг старше PEP 735, — узнавайте в этом обходной манёвр, а не паттерн для копирования.