Автоматизация сборки

TODO Лекция слишком большая, надо распиливать. Видимо, какая-то сборка sdist/wheel останется тут, а вот что должно быть в них для деплоймента — уезжает на следующий раз; там же публикация в PyPI и публикация в Readthedocs…

Этапы формирования дистрибутива

• Разработка
  • Сборка генератов
  • Тестирование
• Сборка дистрибутивов
• Публикация исходников
• Публикация дистрибутивов
Генерат
файл, получающийся в процессе сборки дистрибутива
• Целевой генерат: генерат, входящий в дистрибутив
• Промежуточный генерат: генерат, не входящий ни в какой дистрибутив

Генераты не хранятся в репозитории, однако некоторые из них (например, документация, скомпилированные переводы и т. п.) используются при публикации.

Автоматизация сборки

Репозиторий с примером

Как понятие «сборка» стало «оркестрацией»

• Интерпретируемые ЯП ⇒ нет понятия сборки

• Малые проекты: всё вручную
• Большие проекты: всё на CI-сервере
  • Документация
  • Тесты
  • Проверка синтаксиса

Как следствие: использование инструментов не по назначению:

• Tox (автоматизация тестирования)

  • Сборку генератов можно представить как test suit-ы
  • НО вообще-то tox не для этого
• Git hooks
  • одноуровневая (?) схема «стимул-реакция»
  • на чём писать? некроссплатформенно!
• Github actions
  • Достоинство и оно же недостаток: на машину разработчика даже инструментальные зависимости ставить не надо
  • ⇒ работа превращается в магические пляски над чёрным ящиком
  • некроссплатформенность не имеет (?) значения (модно писать 10050 скриптов для 100500 ОС то на шелле, то на cmd)

Универсальный инструмент сборки

• Классический вариант: Make (его даже использует Sphinx).
  • off-python зависимость
  • некроссплатформенно

• Вариант, рекомендуемый Tox: Invoke

  • Достоинство и оно же недостаток: описание действий на самом Python (синтаксически шумно)

  • Я увидел такую конструкцию в примере: c.run("rm -rf target") — off-python некроссплатформенная зависимость?

• …
• (Задача на самом деле сложная)

На примере DoIt

Сайт DoIt

• Архитектура:
  • Задания
    • Действия
    • Обновление генератов (зависимость на файлы)
      • Есть возможность определять, что такое «новое»
    • Составные задания (зависимость на задания)
• Позволяет запускать задания на языке командной строки
• Часто используемые примитивы на python

• Синтаксис Python (это и есть программа на Python)

В нашем случае нуждается в автоматизации:

• Сборка документации
• Обновление и компиляция переводов
• Запуск тестов (в т. ч. проверка стиля)
• Сборка исходного дистрибутива
• Сборка бинарного дистрибутива (собственно модуля)
• (ещё не сделано, но тоже нужно) Публикация:
  • Бинарного дистрибутива
  • Исходного дистрибутива
  • Документации

Пример dodo.py

В целом те же проблемы: шумно из-за python вместо декларативного синтаксиса, внешние команды и т. п.), но

• Развесистый workflow
• python-активности, в т. ч. уже готовые (типа того же rm)

Сборка

Главная ссылка

Немного истории:

0. Античность

1. Distutils — встроенный в Python инструмент

2. Появление Python Packaging Authority

   • Setuptools — развитие Distutils

     • a. k. a. setup.py

   • Другие проекты PyPA

3. Появление других инструментов сборки: Poetry, pip-tools, PyBuilder и т. п.

   • ⇒ Введение нового уровня косвенности: pep-0517/pep-0518

     • Актуальная документация

     • Задание инструментов сборки
     • Декларативный синтаксис описания проекта

     • Метасборщик build

     • a. k. a. pyproject.toml/setup.cfg

     • Всё это в процессе разработки

Сборка бинарных и исходных дистрибутивов

Что умеет pip install:

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

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

    • ⇒ часто встречаются прихаканные в исходниках бинарники (например, скомпилированные переводы)
• Скачать готовый пакет
  • Под разные архитектуры и разные версии Python
  • В случае модулей на Си — ещё и под разные ОС

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

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

Пример: python -m build и что он создаёт

• sdist
• wheel

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

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

  • В секции options.package_data файла setup.cfg описать, какие файлы какому пакету принадлежат

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

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

Пример

Модельный семестровый проект

Д/З

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

• Автоматизацию выгонки целевых генератов (документация, перевод, иное)
• Сборку wheel
• Сборку архива с исходниками