Преамбула

Когда вы опубликовали десятки пакетов, вы знаете, как ответить на эти вопросы в соответствии с вашими рабочими процессами и вкусом. Но ответить на эти вопросы в первый раз может быть довольно сложно, отнять много времени и разочаровать!

Вот почему я провел дни, изучая способы выполнения этих действий, которые затем опубликовал в виде статьи в блоге под названием Как создать пакет Python в 2022 году.

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

Обзор

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

Отказ от ответственности: существуют другие альтернативные инструменты (обычно), и большинство шагов здесь не являются обязательными.

• Используйте Поэзия для управления зависимостями
• Используйте Гитхаб для размещения кода
• Используйте предварительная фиксация, чтобы убедиться, что зафиксированный код проверен и правильно отформатирован.
• Используйте Тест PyPI для проверки загрузки вашего пакета (что сделает его доступным для установки с помощью pip)
• Используйте Скрив для управления журналом изменений
• Загрузить на настоящий PyPI
• Используйте питест для проверки кода Python.
• Используйте отравить для автоматизации линтинга, форматирования и тестирования версий Python.
  • черный
  • изосортировать
  • столб
  • хлопья8 с маккейб
• Добавьте покрытие кода с помощью покрытие.py
• Настройка CI/CD с помощью GitHub Actions
  • запускать линтеры и тесты
  • автоматически срабатывать при запросах на вытягивание и коммитах
  • интегрировать с кодек для отчетов о покрытии
  • публиковать в PyPI автоматически
• Добавьте классные значки README
• немного прибраться
  • установить tox для использования предварительной фиксации
  • удалить дублирующую работу между хуками tox и pre-commit
  • удалить некоторую избыточность в CI/CD

Шаги

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

• Используйте Поэзия для управления зависимостями.

  • poetry init инициализирует проект в каталоге или poetry new dirname создает для вас новую структуру каталогов
  • сделайте poetry install, чтобы установить все ваши зависимости
  • poetry add packagename можно использовать для добавления packagename в качестве зависимости, используйте -D, если это зависимость разработки (т. е. она нужна вам при разработке пакета, но пользователям пакета она не понадобится. Например, black — хороший пример разработки зависимость)

• Настройте репозиторий на Гитхаб для размещения вашего кода.

• Настройте хуки перед фиксацией, чтобы убедиться, что ваш код всегда правильно отформатирован и проходит линтинг. Это продолжается .pre-commit-config.yaml. Например, приведенный ниже YAML проверяет файлы TOML и YAML, гарантирует, что все файлы заканчиваются символом новой строки, обеспечивает согласованность маркера конца строки во всех файлах, а затем запускает черный и изосортировать в вашем коде.

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.0.1
    hooks:
      - id: check-toml
      - id: check-yaml
      - id: end-of-file-fixer
      - id: mixed-line-ending
  - repo: https://github.com/psf/black
    rev: 22.3.0
    hooks:
      - id: black
  - repo: https://github.com/PyCQA/isort
    rev: 5.10.1
    hooks:
      - id: isort
        args: ["--profile", "black"]

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

  • Расскажите Поэзия о тестировании PyPI с помощью poetry config repositories.testpypi https://test.pypi.org/legacy/
  • Войдите в Test PyPI, получите токен API и скажите Poetry использовать его с poetry config http-basic.testpypi __token__ pypi-your-api-token-here (__token__ является литералом и не должен заменяться, после этого идет ваш токен).
  • Создайте poetry build и загрузите свой пакет poetry publish -r testpypi

• Управляйте своим CHANGELOG с помощью Скрив

  • запустите scriv create перед любой существенной фиксацией и отредактируйте всплывающий файл
  • запустить scriv collect перед любым релизом, чтобы собрать все фрагменты в один чейнджлог

• Настройте Poetry для использования PyPI

  • войдите в PyPI и получите токен API
  • расскажи об этом Поэзии с poetry config pypi-token.pypi pypi-your-token-here
  • создайте и опубликуйте свой пакет одним махом с помощью poetry publish --build

• Пройди круг почета: попробуй pip install yourpackagename убедиться, что все идет хорошо ;)

• Опубликуйте выпуск GH, который соответствует тому, что вы загрузили в PyPI.

• Пишите тесты. Есть варианты много. Питест прост, универсален и не слишком многословен.

  • писать тесты в директорию tests/
  • запускать тестовые файлы с помощью test_...
  • настоящие тесты — это функции с именем, начинающимся с test_...
  • используйте утверждения (assert) для проверки вещей (тесты терпят неудачу, когда утверждают что-то Falsy); обратите внимание, что иногда вам даже не нужно импортировать pytest в ваши тестовые файлы; например.:

# In tests/test_basic_example.py

def this_test_would_definitely_fail():
    assert 5 > 10

def this_test_would_definitely_pass():
    assert 5 > 0

• запустить тесты командой pytest

• Автоматизируйте тестирование, анализ и форматирование с помощью отравить.

  • tox создает виртуальные среды для отдельных версий Python и может выполнять практически то, что вы ему скажете. Конфигурация идет в tox.ini. Вы также можете встроить его в файл pyproject.toml, но на момент написания это поддерживается только в том случае, если вы добавите строку, которая фактически представляет конфигурацию .ini, что некрасиво. Пример tox.ini:

[tox]
isolated_build = True
envlist = py38,py39,py310

[testenv]
deps =
    black
    pytest
commands =
    black --check extendedjson
    pytest .

Среды с py38 по py310 автоматически понимаются отравить как представляющие разные версии Python (вы сами догадываетесь, какие именно). Заголовок [testenv] определяет конфигурации для всех тех сред, о которых знает отравить. Мы устанавливаем зависимости, перечисленные в deps = ..., а затем запускаем команды, перечисленные в commands = ....

• запустите tox с помощью tox для всех сред или tox -e py39 для выбора конкретной среды

• Добавьте покрытие кода с помощью покрытие.py

  • запустить тесты и проверить покрытие с помощью coverage run --source=yourpackage --branch -m pytest .
  • создайте хороший HTML-отчет с помощью coverage html
  • добавить это в токсик

• Создайте действие GitHub, которое запускает анализ и тестирование коммитов и запросов на вытягивание.

  • GH Actions — это просто файлы YAML в .github/workflows
  • этот пример действия GH запускает tox на нескольких версиях Python

# .github/workflows/build.yaml
name: Your amazing CI name

# Run automatically on...
on:
  push:  # pushes...
    branches: [ main ]  # to the main branch... and
  pull_request:  # on pull requests...
    branches: [ main ]  # against the main branch.

# What jobs does this workflow run?
jobs:
  build:  # There's a job called “build” which
    runs-on: ubuntu-latest  # runs on an Ubuntu machine
    strategy:
      matrix:  # that goes through
        python-version: ["3.8", "3.9", "3.10"]  # these Python versions.

    steps:  # The job “build” has multiple steps:
      - name: Checkout sources
        uses: actions/checkout@v2  # Checkout the repository into the runner,

      - name: Setup Python
        uses: actions/setup-python@v2  # then set up Python,
        with:
          python-version: ${{ matrix.python-version }}  # with the version that is currently “selected”...

      - name: Install dependencies
        run: |  # Then run these commands
          python -m pip install --upgrade pip
          python -m pip install tox tox-gh-actions  # install two dependencies...

      - name: Run tox
        run: tox  # and finally run tox.

Обратите внимание, что выше мы установили tox а также плагин под названием tox-gh-actions. Этот плагин сообщит tox о версии Python, установленной в средстве запуска действий GH, что позволит нам указать, в каких средах tox будет работать в этом случае. Нам просто нужно установить соответствие в файле tox.ini:

# tox.ini
# ...
[gh-actions]
python =
    3.8: py38
    3.9: py39
    3.10: py310

• Интегрируйтесь с кодек для получения хороших отчетов о покрытии в запросах на вытягивание.
  • войдите в Codecov с GitHub и дайте разрешения
  • добавить действие Codecov в YAML до запуска после tox (это tox генерирует данные локального отчета о покрытии) и добавить/изменить команду покрытия для создания отчета xml (это формат, который Codecov понимает)

# ...
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v2
        with:
            fail_ci_if_error: true

• Добавьте действие GH для автоматической публикации в PyPI.
  • просто настройте файл YAML, который выполняет ваши ручные шаги по созданию и публикации с помощью Poetry когда, новый выпуск сделан
  • создать токен PyPI для использования GitHub
  • добавьте его как секрет в свой репозиторий
  • настроить Poetry в действии, чтобы использовать этот секрет

name: Publish to PyPI

on:
  release:
    types: [ published ]
    branches: [ main ]
  workflow_dispatch:

jobs:
  build-and-publish:
    runs-on: ubuntu-latest

    steps:
      # Checkout and set up Python

      - name: Install poetry and dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install poetry

      - name: Configure poetry
        env:
          pypi_token: ${{ secrets.PyPI_TOKEN }}  # You set this manually as a secret in your repository
        run: poetry config pypi-token.pypi $pypi_token

      - name: Build and publish
        run: poetry publish --build

• Добавьте крутые значки в свой файл README, например

• немного прибраться

  • запустите linting через tox на pre-commit для дедупликации усилий и запустите ваши предпочтительные версии linters/formatters/...
  • отделить линтинг/форматирование от тестирования в tox как отдельную среду
  • проверить покрытие только один раз как отдельную токсичную среду