Публикация и CI

TODO

план

Немного про написание модулей с помощью Python API

• Учебник

• Докментация

• Пример проекта

Особенности:

• Инструмент сборки проекта на Си?

  • make/setuptools

    • Пока не поддерживается pep-517, надо писать setup.py

  • autotools/?

  • cmake/scikit-build

  • meson/ninja
  • …
• Соблюдение строгой дисциплины программирования
• Зависимость от платформы
  • Wheel может включать в себя несколько платформо-зависимых бинарников

  • ⇒ адские инструменты кросс-сборки типа scikit-build

  • всевозможные приспособления на стороне CI типа cibuildwheel

• Linux: pep-513

  • Необходимо модифицировать собранную библиотеку для соответствия требованиям

Совсем немного про CI

Непрерывная_интеграция:

• получение исходного кода из репозитория;
• сборка проекта;
• выполнение тестов;
• развёртывание готового проекта;
• отправка отчетов.

Обратите внимание: сборка проекта. Как следствие, инструменты сборки утекли с локальной машины на CI-платформу:

• Возможность собирать под любую платформу

• Возможность проводить полноценный деплоймент

Как следствие, «умные» инструменты автоматизации сборки типа Make уступили место простым очередям заданий

• https://travis-ci.com

• https://github.com/features/actions

• https://docs.gitlab.com/ee/ci/

  • В GitLab начали задумываться над графом зависимостей, но как-то очень путано

• https://man.sr.ht/builds.sr.ht/

• … (тысячи их)

Пример проекта

Обвязка для библиотеки libpasswdqc

• Используется builds.sr.ht
• Сценарий (т. н. manifest):

  # В какой ОС собирать
  image: debian/testing
  # какие пакеты устанавливать в сборочную среду
  packages:
    - python3-dev
    - python3-setuptools
    - gcc
    - python3-wheel
    - twine
    - python3-pip
    - unzip
    - patchelf
    - zsh
  # UUID секретных ключей, который должны оказаться в сборочной среде    
  secrets:
    - 7838f337-2952-4fb1-a333-6a7f1af6c9f2
  # Откуда брать исходники    
  sources:
    - https://git.sr.ht/~frbrgeorge/PasswdqcPython
  # Очередь заданий
  tasks:
    # Настройка окружения
    - setup: |
          pip install auditwheel
    # Сборка модуля        
    - build: |
          cd PasswdqcPython
          python3 setup.py build
    # Сборка бинарного дистибутива
    - wheel: |
          cd PasswdqcPython
          python3 setup.py bdist_wheel
          python3 -m auditwheel repair -w dist --plat manylinux2014_x86_64 dist/*linux_x86_64*.whl
          rm dist/*linux_x86_64*.whl
    # Сборка исходного дистрибутива
    - sdist: |
          cd PasswdqcPython
          python3 setup.py sdist
    # Автоматическая публикация (правда, не тестовом Pypi :)
    - publish: |
          cd PasswdqcPython
          set +x
          twine upload -u __token__ -p "`cat ~/.test-pypi`" --repository testpypi dist/*
          set -x 

  • Действия — это просто примитивные shell-сценарии

  • audtwheel не входит в пакетную базу Debian, поэтому доставлять его пришлось pip-ом

  • audtwheel нужен для модификации собранной библиотеки в соответствии с требованиями pep-513 (исходный wheel удаляется)

  • В файле ~/.test-pypi лежит секретный ключ для публикации (а как ещё?), set +x выключает протоколирование выполнения shell-сценария, чтобы не засветить ключ в журнале, set -x включает его обратно

    • Более умный CI-системы умеют распознавать и замазывать секретные ключи прямо в журналах

Конкретно в данном проекте учтено, что в системе может не быть библиотеки libpasswdqc:

• В setup.py добавлена проверка, есть ли библиотека в системе

  • (в действительности не проверяется, есть ли сборочная версия библиотеки, то, что называется libpasswdqc-devel, так что если библиотека есть, а -devel` нет, сборка упадёт)

• Исходники самой библиотеки оформлены как подмодуль git, и если её в системе нет, необходимое подмножество берётся оттуда

манифест может активизироваться вручную или по событию (например, просто ри каждом push, на каждый новый тег, только на подписанный тег и т. п.).

Публикация на PyPi

В действительности ничего свыше методички на PyPA не требуется:

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

  • на сегодня (2021-05-17) в методичке описан файл README.md, в то время как формат по умолчанию для PyPI — не markdown, а ReST, это управляется параметром long_description_content_type setup.cfg

• Публикация происходит с помощью специального инструмента — twine

  • Вместо логина надо указывать слово __tiken__, вместо пароля — выданный вам ключ. Этот же ключ могут использовать и роботы CI

• Немедленно после успешной публикации модуль можно устанавливать!

• на PyPI нельзя выкладывать файл с одним и тем же именем повторно, даже если вы вообще удалили и завели заново соответствующий проект. Если хоть что-то поменяли — поднимайте номер версии.

• README.rst из дистрибутива можно использовать в качестве описания проекта, а вот другие файлы (например, картинки) — нет. Однако можно сослаться на картинки в репозитории, если хостинг поддерживает их показ.

Публикация на readthedocs.org

Тут всё ещё проще! Достаточно, чтобы в вашем проекте выгонялась документация с помощью sphinx.

• Залогиниться и указать репозиторий, из которого будет произведён экспорт
• Документация будет пересоздана создана автоматически на база исходного репозитория (самому генерировать её не надо)
• Если код написан так, что при выгонке документации требуется импортировать внешние модули, возможны ошибки (это вам не CI, никто не будет ставить, допустим, matplotlib).

  • Пример того, как в проекте Pymunk на скорую руку понаделали мокеров вместо соответствующих модулей прямо в конфигурационном файле sphinx

• Такую публикацию можно тоже подключить в CI