Глава 23 · Часть III · Создаём Python-проект

pyproject.toml и установка проекта

src/safesort импортируется, pyproject.toml описывает Проект, а editable install связывает его с текущим окружением.

Здесь легко смешать четыре разных объекта. Импортируемый пакет src/safesort/ содержит __init__.py и модули, которые Python загружает командой import safesort. Проект (project) — библиотека или приложение, предназначенное для упаковки; исходное дерево проекта (project source tree) — его файлы на диске: pyproject.toml, src/, tests/ и документация. Дистрибутивный пакет (distribution package) — устанавливаемый выпуск проекта; когда речь идёт о конкретном файле, это архив дистрибутива: wheel или sdist. Установленный проект — то, что появляется в окружении Python после установки: файлы импортируемого пакета плюс метаданные, по которым инструменты вроде pip и importlib.metadata узнают о нём.

При src-layout запуск Python из корня репозитория сам по себе не добавляет src/ в sys.path. Поэтому до установки import safesort обычно завершится ModuleNotFoundError. Это ожидаемое свойство раскладки, а не признак того, что __init__.py «не сработал».

[project]
name = "safesort"
version = "0.1.0"
description = "A safe, non-destructive command-line file organizer."
dependencies = []

[project.scripts]
safesort = "safesort.cli:main"

Поле version обязательно идентифицирует текущую версию пакета. Пока просто запишем 0.1.0 как номер первой учебной версии. Как устроены номера версий и почему здесь три числа, разберём ближе к завершению проекта.

Строка safesort = "safesort.cli:main" говорит инструменту установки: после установки создай в окружении команду safesort, которая вызывает функцию main() из модуля safesort.cli. Этого модуля пока не существует; мы напишем его на следующей странице.

Устанавливаем проект в редактируемом режиме

Редактируемая установка (editable install) связывает окружение Python с исходным кодом проекта напрямую: изменения в файлах src/safesort/ становятся видны сразу, без повторной установки.

python -m pip install -e ".[dev]"
python -c "import safesort; print(safesort.__file__)"
safesort --help