Создание и тестирование Python

Введение

В этом руководстве показано, как создать, протестировать и опубликовать пакет на Python.

Раннеры, размещённые на GitHub, имеют кэш инструментов с предустановленным программным обеспечением, включающим Python и PyPy. Вам ничего устанавливать не нужно. Полный список программного обеспечения up-to-date и предустановленные версии Python и PyPy см. Средства выполнения тестов, размещенные в GitHub.

Необходимые компоненты

Вы должны быть знакомы с YAML и синтаксисом для GitHub Actions. Дополнительные сведения см. в разделе Написание рабочих процессов.

Рекомендуем иметь базовое понимание Python и pip. Дополнительные сведения см. в разделе:

• Начинаю с Python
• Диспетчер пакетов pip

Использование локальных средств выполнения тестов для GitHub Enterprise Server

При использовании действий установки (таких как actions/setup-LANGUAGE) в GitHub Enterprise Server с использованием локальных средств выполнения тестов может потребоваться настроить в них кэш инструментов, у которых отсутствует доступ к Интернету. Дополнительные сведения см. в разделе Настройка кэша инструментов для локально размещенных средств выполнения без доступа к Интернету.

Использование шаблона рабочего процесса на Python

Чтобы быстро приступить к работе, добавьте шаблон рабочего процесса в .github/workflows каталог репозитория.

GitHub предоставляет шаблон рабочего процесса для Python, который должен работать, если в вашем репозитории уже есть хотя бы один файл .py. В последующих разделах этого руководства приведены примеры настройки этого шаблона рабочего процесса.

1. На GitHubперейдите на главную страницу репозитория.

2. Под именем репозитория щелкните Actions.

   

3. Если в вашем репозитории уже используется рабочий процесс, нажмите кнопку Создать рабочий процесс.

4. На странице "Выбор рабочего процесса" показан выбор рекомендуемых шаблонов рабочих процессов. Поискайте «Python application».

5. В рабочем процессе "Python application" нажмите Configure.

   Если вы не нашли шаблон рабочего процесса "Python application", скопируйте следующий код рабочего процесса в новый файл под названием python-app.yml в каталоге .github/workflows вашего репозитория.

   YAML

   name: Python application
   
   on:
     push:
       branches: [ "main" ]
     pull_request:
       branches: [ "main" ]
   
   permissions:
     contents: read
   
   jobs:
     build:
       runs-on: ubuntu-latest
   
       steps:
       - uses: actions/checkout@v6
       - name: Set up Python 3.13
         uses: actions/setup-python@v5
         with:
           python-version: "3.13"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install ruff pytest
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
       - name: Lint and format Python code with ruff
         run: |
          # Lint with the default set of ruff rules with GitHub Annotations
          ruff check --format=github --target-version=py39
          # Verify the code is properly formatted
          ruff format --diff --target-version=py39
       - name: Test with pytest
         run: |
           pytest
   

6. Измените рабочий процесс по мере необходимости. Например, измените версию Python.

7. Щелкните Зафиксировать изменения.

Определение версии на Python

Чтобы использовать предустановленную версию Python или PyPy на раннере с GitHub, используйте действие setup-python. Это действие находит определённую версию Python или PyPy из кэша инструментов на каждом раннере и добавляет необходимые бинарные файлы в PATH, который сохраняется на протяжении всей работы. Если конкретная версия Python не предустановлена в кэше инструментов, действие setup-python скачает и настроит соответствующую версию из репозитория python-versions.

Рекомендуется использовать действие setup-python с Python с GitHub Actions, поскольку оно обеспечивает единообразное поведение между разными бегущими и разными версиями Python. Если вы используете самостоятельный раннер, обязательно установить Python и добавить его в PATH. Дополнительные сведения см. в описании действия setup-python.

В таблице ниже описаны расположения кэша инструментов в каждом GitHub-hosted runner.

Если вы используете локальное средство выполнения, его можно настроить для управления зависимостями с помощью действия setup-python. Дополнительные сведения см. в разделе об использовании setup-python с локальным средством выполнения в файле сведений setup-python.

GitHub поддерживает синтаксис семантического версионирования. Дополнительные сведения см. в разделе "Использование семантического управления версиями " и спецификации семантического управления версиями.

Использование нескольких версий Python

В следующем примере используется матрица для задания для настройки нескольких версий Python. Дополнительные сведения см. в разделе Выполнение вариантов заданий в рабочем процессе.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["pypy3.10", "3.9", "3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v6
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      # You can test your matrix by printing the current Python version
      - name: Display Python version
        run: python -c "import sys; print(sys.version)"

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["pypy3.10", "3.9", "3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v6
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      # You can test your matrix by printing the current Python version
      - name: Display Python version
        run: python -c "import sys; print(sys.version)"

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

Вы можете настроить определённую версию Python. Например, 3.12. Кроме того, можно использовать синтаксис семантической версии, чтобы получить последний дополнительный выпуск. В этом примере используется последняя небольшая версия Python 3.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v5
        with:
          # Semantic version range syntax or exact version of a Python version
          python-version: '3.x'
          # Optional - x64 or x86 architecture, defaults to x64
          architecture: 'x64'
      # You can test your matrix by printing the current Python version
      - name: Display Python version
        run: python -c "import sys; print(sys.version)"

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v5
        with:
          # Semantic version range syntax or exact version of a Python version
          python-version: '3.x'
          # Optional - x64 or x86 architecture, defaults to x64
          architecture: 'x64'
      # You can test your matrix by printing the current Python version
      - name: Display Python version
        run: python -c "import sys; print(sys.version)"

Исключение версии

Если указать версию Python, которая недоступна, setup-python выходит из строя с ошибкой, например: ##[error]Version 3.7 with arch x64 not found. Сообщение об ошибке содержит доступные версии.

Вы также можете использовать ключевое слово exclude в вашем рабочем процессе, если есть конфигурация Python, которую вы не хотите запускать. Дополнительные сведения см. в разделе Синтаксис рабочего процесса для GitHub Actions.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.9", "3.11", "3.13", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.11"
          - os: windows-latest
            python-version: "3.11"

name: Python package

on: [push]

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.9", "3.11", "3.13", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.11"
          - os: windows-latest
            python-version: "3.11"

Использование стандартной версии Python

Рекомендуем использовать setup-python для настройки версии Python в ваших рабочих процессах, так как это помогает сделать зависимости явными. Если вы не используете setup-python, то стандартная версия Python, установленная в PATH, используется в любой оболочке, когда вы вызываете python. Стандартная версия Python варьируется между раннерами GitHub, что может вызвать неожиданные изменения или использовать более старую версию, чем ожидалось.

Установка зависимостей

GitHub-размещённые бегущие имеют установленный менеджер пакетов PIP. Вы можете использовать pip для установки зависимостей из реестра пакетов PyPI перед созданием и тестированием кода. Например, приведенный ниже код YAML устанавливает или обновляет установщик пакетов pip и пакеты setuptools и wheel.

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

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install dependencies
  run: python -m pip install --upgrade pip setuptools wheel

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install dependencies
  run: python -m pip install --upgrade pip setuptools wheel

Файл требований

После обновления pipтипичный следующий шаг — установить зависимости из requirements.txt. Дополнительные сведения см. в описании pip.

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

Кэширование зависимостей

Можно кэшировать и восстанавливать зависимости с помощью setup-pythonдействия.

В следующем примере кэшируются зависимости для pip.

steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
- run: pip install -r requirements.txt
- run: pip test

steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: 'pip'
- run: pip install -r requirements.txt
- run: pip test

По умолчанию действие setup-python ищет файл зависимостей (requirements.txt для pip, Pipfile.lock для pipenv или poetry.lock для poetry) во всем репозитории. Дополнительные сведения см. в разделе о зависимостях пакетов кэширования в setup-python README.

Если у вас есть особые требования или вам нужно управлять кэшированием более детально, можно использовать действие cache. Pip кэширует зависимости в разных расположениях в зависимости от операционной системы средства выполнения. Путь, по которому требуется выполнить кэширование, может отличаться от приведенного выше примера Ubuntu в зависимости от используемой операционной системы. Для получения дополнительной информации см. Python примеры кэширования в репозитории действий cache.

Тестирование кода

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

Тестирование с помощью pytest и pytest-cov

В этом примере устанавливаются или обновляются pytest и pytest-cov. Затем выполняются тесты, выходные данные выводятся в формате JUnit, а результаты по объему протестированного кода выводятся в Cobertura. Дополнительные сведения см. в описании JUnit и Cobertura.

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- name: Test with pytest
  run: |
    pip install pytest pytest-cov
    pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- name: Test with pytest
  run: |
    pip install pytest pytest-cov
    pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

Использование Ruff для написания кода и (или) форматирования

В следующем примере выполняется установка или обновление ruff и его использование для анализа кода всех файлов. Дополнительные сведения см. в статье Ruff.

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install the code linting and formatting tool Ruff
  run: pipx install ruff
- name: Lint code with Ruff
  run: ruff check --output-format=github --target-version=py39
- name: Check code formatting with Ruff
  run: ruff format --diff --target-version=py39
  continue-on-error: true

steps:
- uses: actions/checkout@v6
- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.x'
- name: Install the code linting and formatting tool Ruff
  run: pipx install ruff
- name: Lint code with Ruff
  run: ruff check --output-format=github --target-version=py39
- name: Check code formatting with Ruff
  run: ruff format --diff --target-version=py39
  continue-on-error: true

Для шага continue-on-error: true форматирования задано значение. Это приведет к сбою рабочего процесса, если шаг форматирования не выполнен. После устранения всех ошибок форматирования можно удалить этот параметр, чтобы рабочий процесс перехватал новые проблемы.

Выполнение тестов с помощью tox

С GitHub Actionsпомощью , можно проводить тесты с токсикологическими методами и распределять работу между несколькими работами. Вам нужно вызвать токсикологию с помощью опции -e py, чтобы выбрать версию Python в вашем PATH, вместо указания конкретной версии. Дополнительные сведения см. в описании tox.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.9", "3.11", "3.13"]

    steps:
      - uses: actions/checkout@v6
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
      - name: Install tox and any other packages
        run: pip install tox
      - name: Run tox
        # Run tox using the version of Python in `PATH`
        run: tox -e py

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.9", "3.11", "3.13"]

    steps:
      - uses: actions/checkout@v6
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}
      - name: Install tox and any other packages
        run: pip install tox
      - name: Run tox
        # Run tox using the version of Python in `PATH`
        run: tox -e py

Упаковка данных рабочего процесса в виде артефактов

Вы можете отправить артефакты для просмотра после завершения рабочего процесса. Например, может потребоваться сохранить файлы журналов, основные дампы, результаты теста или снимки экрана. Дополнительные сведения см. в разделе Хранение и предоставление общего доступа к данным с артефактами рабочего процесса.

В следующем примере показано, как использовать действие upload-artifact для архивации результатов теста при выполнении pytest. Дополнительные сведения см. в описании действия upload-artifact.

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v6
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      # Install pip and pytest
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install pytest
      - name: Test with pytest
        run: pytest tests.py --doctest-modules --junitxml=junit/test-results-${{ matrix.python-version }}.xml
      - name: Upload pytest test results
        uses: actions/upload-artifact@v3
        with:
          name: pytest-results-${{ matrix.python-version }}
          path: junit/test-results-${{ matrix.python-version }}.xml
        # Use always() to always run this step to publish test results when there are test failures
        if: ${{ always() }}

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]

    steps:
      - uses: actions/checkout@v6
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      # Install pip and pytest
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install pytest
      - name: Test with pytest
        run: pytest tests.py --doctest-modules --junitxml=junit/test-results-${{ matrix.python-version }}.xml
      - name: Upload pytest test results
        uses: actions/upload-artifact@v3
        with:
          name: pytest-results-${{ matrix.python-version }}
          path: junit/test-results-${{ matrix.python-version }}.xml
        # Use always() to always run this step to publish test results when there are test failures
        if: ${{ always() }}

Публикация в PyPI

Вы можете настроить рабочий процесс так, чтобы публиковать пакет Python в PyPI после прохождения CI-тестов. В этом разделе показано, как вы можете GitHub Actions загружать свой пакет в PyPI каждый раз при публикации релиза. Дополнительные сведения см. в разделе Управление выпусками в репозитории.

В приведенном ниже примере рабочего процесса используется надежная публикация для проверки подлинности с помощью PyPI, что устраняет необходимость в маркере API, настроенном вручную.

# Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
# Они предоставляются сторонним поставщиком, и на них распространяются
# отдельные условия обслуживания, политика конфиденциальности и поддержка
# документации.

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

name: Upload Python Package

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: Build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: Upload distributions
        uses: actions/upload-artifact@v3
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest

    needs:
      - release-build

    permissions:
      # IMPORTANT: this permission is mandatory for trusted publishing
      id-token: write

    # Dedicated environments with protections for publishing are strongly recommended.
    environment:
      name: pypi
      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
      # url: https://pypi.org/p/YOURPROJECT

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v3
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@6f7e8d9c0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d

# Этот рабочий процесс использует действия, которые не сертифицированы GitHub.
# Они предоставляются сторонним поставщиком, и на них распространяются
# отдельные условия обслуживания, политика конфиденциальности и поддержка
# документации.

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

name: Upload Python Package

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  release-build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: Build release distributions
        run: |
          # NOTE: put your own distribution build steps here.
          python -m pip install build
          python -m build

      - name: Upload distributions
        uses: actions/upload-artifact@v3
        with:
          name: release-dists
          path: dist/

  pypi-publish:
    runs-on: ubuntu-latest

    needs:
      - release-build

    permissions:
      # IMPORTANT: this permission is mandatory for trusted publishing
      id-token: write

    # Dedicated environments with protections for publishing are strongly recommended.
    environment:
      name: pypi
      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
      # url: https://pypi.org/p/YOURPROJECT

    steps:
      - name: Retrieve release distributions
        uses: actions/download-artifact@v3
        with:
          name: release-dists
          path: dist/

      - name: Publish release distributions to PyPI
        uses: pypa/gh-action-pypi-publish@6f7e8d9c0b1a2c3d4e5f6a7b8c9d0e1f2a3b4c5d