Пакетирование и деплоймент

Что умеет pip install:

1. Скачать исходники, собрать и установить их
   • Нужны сборочные зависимости

   • В случае модулей на Си это может быть очень непросто

     • ⇒ часто встречаются прихаканные в исходниках бинарники (например, скомпилированные переводы, а то и прямо исполняемые файлы, как в cmake)

2. Скачать готовый пакет
   • Под разные архитектуры и разные версии Python
   • В случае модулей на Си — ещё и под разные ОС

   • ⇒ универсальный формат Wheel (pep-0427)

Публиковать нужно и то, и то (лицензия, вопросы доработки и т. п.), а вот рассчитывать на сборку «на месте» не стоит.

Сборка

Setuptools

• pyproject.toml vs. setup.cfg vs. setup.py

• Tom's Obvious Minimal Language: tomli (⩽ 3.10), tomllib (⩾ 3.11)

  • also, tomli-w (write-only)

pyproject.toml

• Общие параметры

  • Нужны почти все)

• Параметры setuptools

Особенность TOML: однострочный и секционированный форматы представления одних и тех же данных (отсюда и далее

Особенность pyproject.toml: простой и сложный варианты описания:

• Например, [tool.setuptools.packages] vs [tool.setuptools.package-dir]

Reference implementation: build

В репозитории с примером

Что должно входить в wheel / sdist?

• Для того, чтобы вместе с модулем упаковать какие-то дополнительные файлы, например, скомпилированные переводы, необходимо:

  • Чтобы после сборки эти файлы (неважно, генераты или нет) оказались в каталоге с модулем

  • Проблема: после изобретения Namespace packages любой каталог системы может считаться таковым; это приводит к ошибкам

  • Вариант 1: убирать пакеты в ./src

  • Вариант 2: использовать [tool.setuptools.package-dir]

• Для того, чтобы упаковать в исходный дистрибутив дополнительные файлы (переводы, тесты и т. п.), их надо перечислить в заготовке файла-манифеста MANIFEST.in. Некоторые файлы включаются автоматически.

  • Имеет смысл проследить за тем, чтобы в исходном дистрибутиве было всё, что лежит в репозитории

Более простой пример, в котором:

• Генерируются и упаковываются в wheel переводы
• Различные нужные файлы упаковываются в архив исходников

• Babel и doit не указаны в devel-зависимостях pyproject.toml (сам setuptools мим не пользуется), но есть Pipfile

TODO: Научиться запускать doit прямо из setuptools

Пакетные зависимости

Эксплуатационные зависимости

Набор модулей, необходимых для эксплуатации приложения

• Обязательные и предполагаемые
• Включённые в python-инфраструктуру и все остальные (с этим проблема)

Сборочные зависимости

Набор модулей и ПО, необходимый для разработки

• + Средства сборки

• + Средства тестирования

• - Возможно, часть эксплуатационных зависимостей замещена квазиобъектами

Отслеживание зависимостей

∃ Более сложный инструмент ­— poetry, но он предписывает определённый workflow и скрывает многие действия под капотом, попробуем разобраться на нижнем уровне.

0. Скопировать в чистое окружение и тупо запускать и добавлять в зависимости всё, из-за отсутствия чего падает)

1. Сделать pip freeze и угадать, что из этого всего понадобится при запуске

2. Соблюдать дисциплину с помощью pipenv:

   • Для установки чего не попадя — pip install что ни попадя

   • Для установки эксплуатационных зависимостей — pipenv install эксплуатационные зависимости

     • записывается в секцию [packages] файла Pipfile

     • pipenv install пакет обновляет Pipfile, даже если до этого был сделан pip install пакет

   • Для установки сборочных зависимостей — pipenv install -d сборочные зависимости)

     • Обновляет секцию [dev-packages] в Pipfile

При формировании дистрибутива / архива исходников

1. Эксплуатационные зависимости

   • Хранятся в pyproject.toml

   • можно отследить по наличию import-ов в модуле.
     • В т. ч. автоматически, но

     • Есть прорва инструментов, ни одного годного

     • Часть из них импортит внутренности pip, что запрещено ☹ (пример: pip-check-reqs, оно пока работает)

   • Самый адекватный — поисковик python3 зависимостей в сборочнице ALT Linux Team

     • Запуск find project -name \*.py | python3 /usr/lib/rpm/python3.req.py

     • Ждём релиза в качестве независимого модуля!

2. Сборочные зависимости

   • Хранятся в pyproject.toml, потому что определяют инструменты сборки

   • Можно отследить путём трассировки import-ов.

   • Но инструмента такого, похоже, нет!

Прототип инструмента, отслеживающего сборочные заивсимости

Пример такого инструмента: pip запускается из командной строки. Выдаёт довольно адекватную информацию, как минимум про репозиторий с примером

1. Составить словарь: какому из установленных пакетов какой файл принадлежит ( эта задача почему-то ещё не решена)

   • Учитывать только пакеты, установленные непосредственно, а не по зависимостям (например, с помощью pip list --not-required)

2. Запустить все инструменты сборки и тестирования с трассировкой (PYTHONVERBOSE=import python … или python -v …)

3. Проанализировать журнал трассировки на предмет использования файлов, принадлежащих пакетам из локального окружения

Возможны ситуации, когда для сборки требуется инструмент, который был поставлен автоматом по зависимости, а то, что его требовало, для сборки не нужно.

Строгие VS нестрогие зависимости на версии

• Для публикации: скорее всего, нестрогие
• Для разработки (особенно совместной) — лучше строгие

Pipfile vs requirements.txt

• Сам pip умеет в requirements.txt: pip install -r

  • Сборочные зависимости можно положить просто в отдельный файл (requirements-dev.txt, например)

• pip freeze не умеет отличать «мусор» (левые пакеты) и пакеты установленные только по зависимостям от собственно зависимостей

  • сборочные зависимсоти от эксплуатационных он тоже не отличает
  • Приходится всё это отслеживать вручную

• Pipfile нестандартен

  • нормально с ним работает только pipenv

  • отличает все четыре вида установленных пакетов (см. выше)
  • не умеет напрямую работать с «мусором»

    • только pipenv lock; pipenv --rm; pipenv sync (пересоздание окружения)

• pipenv умеет отчитываться в формате requirements:

  • pipenv lock -r и

  • pipenv lock -r --dev-only

Точки входа

• Для запуска python -m модуль в нём должен присутствовать __main__.py

• Для создания стартового сценария в pyproject.toml необходимо описать точки входа

Д/З

Обеспечить в семестровом проекте:

• Сборку wheel
• Установку проекта в чистом окружении из этого wheel (должны притягиваться нужные зависимости)

• TODO не сейчас? Сборку архива с исходниками

  • В архиве должны присутствовать все нужные файлы и некоторые полезные генераты (например, requirements-dev.txt)

• Запуск и полноценную работу проекта после установки в чистое окружение:
  • проверить наличие зависимостей
  • Проверить наличие непрогарммных файлов
  • Проверить работу переводов

Это весь семестровый проект, готовый к сдаче!