Рубрики
Без рубрики

Миграция проекта к поэзии

Поэзия – это инструмент, решающий проблему упаковки Python. Это было начато еще в феврале 2018 года на … Помечено Python, упаковка, поэзия.

Поэзия это инструмент, решение проблемы упаковки Python. Он был запущен в феврале 2018 года от Sébastien Eustace (также автор маятник ). У этого есть красивый сайт и амбициозный заголовок:

Управление упаковкой Python и зависимость от

Это было на моем радаре на некоторое время, но я никогда не давал ему правильного ухода. Я был счастливо, используя Pip-Tools , который решал мое основное использование случая, будучи намного более легким и имел в виду, что я мог бы продолжать работать с PIP, так как его выход – старый добрый требования .txt Отказ Я слышал об этом несколько раз онлайн, часто рядом с Пипнв С Но недавно это выглядит как поэзия, получила немного больше тяги.

Наличие немного времени на моих руках, несколько недель назад я решил взять правильный взгляд на него и, возможно, мигрирует один из моих проектов, Deezer Python Отказ

Отправная точка

Перед миграцией вот как упаковка была удалена:

  • Метаданные проекта были в setup.cfg , используя SetUptools декларативный конфиг Отказ
  • Разработка (и документация) зависимости управляемых по Pip-Tools Отказ
  • Документация, размещенная на чтении документов (RTD).
  • Релизы автоматизированы с Python Semantic Release (PSR) на Действия GitHub.
  • Инструменты разработки настроены в setup.cfg (черный, изортированный, pyupgrade, flake8).
  • Использование Tox чтобы помочь местным тестированию.
  • Использование действий GitHub для CI.

Это пару особенностей, которые были затронуты миграцией на поэзию, и я думаю, что стоит упомянуть их для контекста. Так как поэзия использует pyproject.toml , Я также надеялся переместить все свои инструменты Config с setup.cfg к этому файлу.

Миграция

Установка поэзии

Первый шаг – получить CLI. Я изначально установил его через доме, но позже понял, что поэзия устанавливала некоторые значения по умолчанию на основе версии Python, его установка использует. Поскольку доместитель Python может быть обновлен без уведомления, я понял, что это не лучший вариант здесь, поэтому я позже переустановил его через Pipx Использование установки Python управляемой PENV, которая не будет вытираться без моих знаний:

pipx install \
 --python ~/.pyenv/versions/3.8.6/bin/python \
 poetry

Метаданные проекта

Первый шаг состоял в том, чтобы перенести метаданные проекта из setup.cfg к pyproject.toml Отказ Поэзия поставляется с удобной интерактивной командой Поэзия init который создаст минимальный pyproject.toml для тебя. Я уже заметил несколько приятных сюрпризов:

  • CLI было очень приятно взаимодействовать с
  • Автор и aper_email от setup.cfg были объединены в массив авторы каждый с форматом Полное имя Отказ

Затем я продолжал преобразовать больше настроек в новый формат вручную, и процесс был довольно безболезненным. Многие настройки имеют одинаковое имя и значения, и когда они отличаются, это в основном для упрощения вещей. Я предполагаю, что это то, что библиотека, как SetUptools, не может легко позволить себе сделать из-за обратной совместимости, но что может быть новым инструментом для поэзии.

Зависимости

Добавление зависимостей и зависимости разработки было довольно простым, мне просто нужно было запускать Поэзия Добавить [-D] ... со списком пакетов в конце.

В этом процессе я обнаружил, что одна из зависимостей развития Pyupgrade не совместим с Python 3.6.0 : Поэзия не позволила бы мне поставить свой собственный питон на ^ 3.6. . Я изначально изменил свою минимальную версию в ^ 3.6.1 Позже я понял, что позже я повлиял на классификаторы Throve My Package, те, которые генерируются поэзии: мой пакет не был перечислен в виде совместимого Python 3.6. Поскольку это только для зависимости развития, есть лучший способ! Исправление состоит в том, чтобы указать зависимость условную версию Python:

[tool.poetry.dependencies]
python = "^3.6"
...

[tool.poetry.dev-dependencies]
...
pyupgrade = { version = "^2.7.3", python = "^3.6.1" }

С этим минимальная версия Python моя пакет и его классификаторы верны.

Дополнительные зависимости

Этот пакет имел «дополнительную требующую» зависимость. Есть хорошая Пример в документации Эти зависимости должны быть указаны в том же разделе, что и нормальные зависимости, а как необязательно :

[tool.poetry.dependencies]
...
tornado = {version = "^6.0.4", optional = true}

И преданный pyproject.toml Секция отображает дополнения к массиву дополнительных зависимостей:

[tool.poetry.extras]
tornado = ["tornado"]

Первоначально я запутался, потому что я думал, что это сделано через Поэзия Добавить ... -Е ... команда. Тем не менее, это делает что-то другое, это за дополнительную зависимость, а не дополнительный из моей собственной библиотеки, зависимость должна подпадать.

Например, Django имеет 2 возможных дополнения На данный момент, поэтому каждый будет запустить следующие команды для их использования:

poetry add Django -E argon2

Это означает «Установить Django с Argon2 Extra». Я думал, что это значит «установить Django и положить его под Argon2 Extra».

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

Зависимости создания документов были указаны в требования .txt в Документы/ Папка и RTD были настроены, чтобы выбрать это. Я изначально подумал, что не смогу удалить этот файл, но оказывается Можно сделать это работать Отказ

Благодаря PEP 517 , который Поэзия соответствует Вы можете сделать Установка PIP. в поэзированном пакете. Это было в PIP с 19,0, а PIP работает на RTD, новее, чем это. Однако этот метод не установит ваши зависимости разработки, поэтому ваши зависимости документов не могут быть указаны как таковые. Это работает, если вы укажете Документы Дополнительный, хотя:

# pyproject.toml
[tool.poetry.dependencies]
...
myst-parser = {version = "^0.12", optional = true}
sphinx = {version = "^3", optional = true}
sphinx-autobuild = {version = "^2020.9.1", optional = true}
sphinx-rtd-theme = {version = "^0.5", optional = true}

[tool.poetry.extras]
...
docs = [
    "myst-parser",
    "sphinx",
    "sphinx-autobuild",
    "sphinx-rtd-theme",
]

# readthedocs.yml
version: 2
python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

Нижняя часть этого, состоит в том, что дополнительный является частью вашей пакеты, поэтому не идеально.

Релизы

Недавно я переместил автоматизацию релизов до Python Semantic Release Что хорошо работал для меня, и это было бы блокатором, если бы не сработало. Это куски, которые мне нужны:

  • Переместите его конфигурацию, чтобы поступить из pyproject.toml Отказ
  • Указана версия пакета в pyproject.toml а также в __init__.py Отказ
  • Обновите команду сборки для использования поэзии вместо SetUpeWoodools.

Вот конфигурация PSR в pyproject.toml Для достижения этого:

[tool.semantic_release]
version_variable = [
    "deezer/ __init__.py: __version__",
    "pyproject.toml:version"
]
build_command = "pip install poetry && poetry build"

Я ожидал, что придется изменить больше, но все это работало из коробки только с этим.

Форматирование льмина и кода

Все инструменты, которые я использую для форматирования льмина и кода, были настроены через setup.cfg и в идеале я хотел бы заменить его по pyproject.toml. . Это было возможно для почти всего, кроме Flake8, который имеет Открытая проблема для этого.

Я решил двигаться как можно больше вещей, чтобы я мог pyproject.toml и переместите Flake8 Config в .flake8 Отказ

Со всеми вышесказанными, я смог удалить setup.cfg Как и все файлы PIP-Tools для зависимостей.

Код покрытия

Уштист имел и Неожиданный раздел конфина для pyproject.toml. Я не обратил много внимания на это изначально и поставил свой конфигурацию под [Инструмент. Pytest] , пока раздел должен быть [Tool.Pytest.ini_options] Отказ

Следствием этого было то, что мой конфиг был игнорирован, и я не запустил тесты с включенным покрытием, что загадывает еще одну ошибку в разделе покрытия Tool.Coverage.run , где источник должен быть массивом:

[tool.pytest.ini_options]
addopts = "-v -Wdefault --cov=deezer"

[tool.coverage.run]
branch = true
source = ["deezer"]

С этим Pytest работал с охватом, но по какой-то причине Кодеков не поднимал доклад правильно. Я заметил, что раньше нашел XML Файл, когда он работал, поэтому я отредактировал команду на CI, чтобы сгенерировать его с помощью - VCOV-отчет = XML :

poetry run pytest --cov-report=xml

С этими изменениями я в конечном итоге получил свой код охвата кода, но это то, что я пропустил в оригинальной миграции. Не связан напрямую с поэзией, но интересно, что Pytest решил пойти с этим разделом именем.

Токс

Поэзия красиво работает с токс, я последовал за раздел в их задачах И вот обзор изменений:

[tox]
isolated_build = true
envlist = py36,py37,py38,py39,pypy3,docs,lint,bandit

[testenv]
whitelist_externals = poetry
commands =
    poetry install
    poetry run pytest
...

Я заменил Депс раздел в каждом Testenv от Поэзия устанавливает В список команд для запуска и префиксировал все команды для запуска в изолированной среде по пробег поэзии .

Действия GitHub

Поэзия не установлена из коробки на действиях GitHub, можно либо установить его простым Беги шаг или использовать Выделенное действие для этого. Я решил выделенное действие, думая, что зависимость может держать его в курсе для меня.

Остальные изменения довольно просты, это вопрос или замена PIP Установить по Поэзия Установить -e ... и префикс всех команд по Поэзия бежит Отказ Мои документы были проверены, и я менял каталог с компакт диск Я взял эту возможность вместо этого использовать Рабочий каталог ключ к шагу действий GitHub.

Вердикт

Поэзия доставила свою амбициозную татуру? Я так думаю, я был действительно впечатлен опытом разработчика поэзии, его CLI действительно хорош, и я ударил небольшие вопросы на пути. В целом миграция была не слишком сложной, вы можете проверить потянуть запрос на Github. Я чувствую, что есть довольно много функций, которые я просто поцарапал поверхность (как многоуровневые).

Я собираюсь ждать немного, чтобы посмотреть, как это работает в дольше беги, но я думаю, что в ближайшее время я мигрирую свои другие проекты.

Оригинал: “https://dev.to/browniebroke/migrating-a-project-to-poetry-3nm”

Читайте ещё по теме: