Python のビルドとテスト

はじめに

このガイドは、Pythonパッケージのビルド、テスト、公開の方法を紹介します。

GitHub ホストランナーには、Python と PyPy を含む、ソフトウェアがプレインストールされたツールキャッシュがあります。自分では何もインストールする必要がありません！最新のソフトウェアと、Python および PyPy のプレインストールされたバージョンの完全なリストについては、「GitHub ホステッドランナーの使用」を参照してください。

前提条件

YAMLとGitHub Actionsの構文に馴染んでいる必要があります。詳しくは、「GitHub Actions について」を参照してください。

Python と pip の基本的な理解をしておくことをおすすめします。詳細については、以下を参照してください:

Python スターターワークフローの使用

すぐに開始するには、リポジトリの .github/workflows ディレクトリにスターターワークフローを追加します。

GitHub は、既にリポジトリに少なくとも 1 つの .py ファイルが含まれている場合に動作する Python のスターターワークフローを提供します。このガイドの以降のセクションでは、このスターターワークフローをカスタマイズする方法の例を示します。

GitHub.com で、リポジトリのメインページへ移動します。
リポジトリ名の下にある [アクション] をクリックします。
ワークフローが既にリポジトリ内にある場合は、 [新しいワークフロー] をクリックします。
「ワークフローの選択」ページには、推奨されるスターターワークフローの選択内容が表示されます。「Python アプリケーション」を検索します。
「Python アプリケーション」ワークフローで、[設定] をクリックします。
必要に応じてワークフローを編集します。たとえば、Python のバージョンを変更します。
[変更をコミットする] をクリックします。

python-app.yml ワークフローファイルがリポジトリの .github/workflows ディレクトリに追加されます。

Pythonのバージョンの指定

GitHub ホストランナー上で Python または PyPy のプレインストールされたバージョンを使うには、setup-python アクションを使用します。このアクションでは各ランナーのツールキャッシュから指定されたバージョンの Python または PyPy を見つけ、必要なバイナリを PATH に追加します。これは、残りのジョブで永続化されます。特定のバージョンの Python がツールキャッシュにプレインストールされていない場合、setup-python アクションでは python-versions リポジトリから適切なバージョンをダウンロードして設定します。

setup-python の使用は、GitHub Actions で Python を使うための推奨される方法です。これは、そうすることでさまざまなランナーやさまざまなバージョンの Python で一貫した動作が保証されるためです。セルフホストランナーを使用している場合は、Python をインストールして PATH に追加する必要があります。詳細については、「setup-python アクション」を参照してください。

以下の表は、各GitHubホストランナー内でのツールキャッシュの場所です。

	Ubuntu	Mac	Windows
ツールキャッシュディレクトリ	`/opt/hostedtoolcache/*`	`/Users/runner/hostedtoolcache/*`	`C:\hostedtoolcache\windows\*`
Python ツールキャッシュ	`/opt/hostedtoolcache/Python/*`	`/Users/runner/hostedtoolcache/Python/*`	`C:\hostedtoolcache\windows\Python\*`
PyPy ツールキャッシュ	`/opt/hostedtoolcache/PyPy/*`	`/Users/runner/hostedtoolcache/PyPy/*`	`C:\hostedtoolcache\windows\PyPy\*`

セルフホストランナーを使用している場合は、setup-python アクションを使って依存関係を管理するようにランナーを構成できます。詳細については、setup-python README のセルフホストランナーでの setup-python の使用に関するページを参照してください。

GitHubは、セマンティックバージョン構文をサポートしています。詳細については、「セマンティックバージョニングの使用」および「セマンティックバージョニングの仕様」を参照してください。

Pythonの複数バージョンの利用

次の例では、ジョブのマトリックスを使用して、複数の Python バージョンを設定します。詳しくは、「ジョブにマトリックスを使用する」を参照してください。

YAML

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        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.9", "pypy3.10", "3.9", "3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        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.10 です。あるいは、最新のマイナーリリースを取得するためにセマンティックバージョン構文を使うこともできます。以下の例では、Python 3の最新のマイナーリリースを使います。

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v4
        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@v4
      - name: Set up Python
        # This is the version of the action for setting up Python, not the Python version.
        uses: actions/setup-python@v4
        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.6 with arch x64 not found などのエラーで失敗します。このエラーメッセージには、利用できるバージョンが含まれます。

実行したくない Python の構成がある場合は、ワークフローで exclude キーワードを使用することもできます。詳しくは、「ギットハブ　アクション　のワークフロー構文」を参照してください。

YAML

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.10", "3.11", "pypy3.9", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.9"
          - os: windows-latest
            python-version: "3.9"

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.10", "3.11", "pypy3.9", "pypy3.10"]
        exclude:
          - os: macos-latest
            python-version: "3.9"
          - os: windows-latest
            python-version: "3.9"

デフォルトバージョンのPythonの利用

依存関係を明示的にしやすくなるので、ワークフローで使用する Python のバージョンの構成には setup-python を使うことをお勧めします。 setup-python を使わない場合は、python の呼び出し時にいずれかのシェルで PATH に設定された既定のバージョンの Python が使用されます。デフォルトバージョンのPythonは、GitHubホストランナーによって様々なので、予想外の変更が生じたり、期待しているよりも古いバージョンが使われたりするかもしれません。

GitHubホストランナー	説明
Ubuntu	Ubuntu ランナーでは、`/usr/bin/python` および `/usr/bin/python3` の下に複数のバージョンのシステム Python がインストールされています。 GitHubがツールキャッシュにインストールしエチルバージョンに加えて、UbuntuにパッケージングされているバージョンのPythonがあります。
Windows	ツールキャッシュにあるPythonのバージョンを除けば、WindowsにはシステムPythonに相当するバージョンは含まれていません。他のランナーとの一貫した動作を保ち、`setup-python` アクションなしですぐに Python が使えるようにするために、GitHub ではツールキャッシュからいくつかのバージョンを `PATH` に追加します。
macOS	macOSランナーには、ツールキャッシュ内のバージョンに加えて、複数バージョンのシステムPythonがインストールされています。システム Python バージョンは `/usr/local/Cellar/python/*` ディレクトリにあります。

依存関係のインストール

GitHubホストランナーには、パッケージマネージャーのpipがインストールされています。コードのビルドとテストに先立って、pipを使ってパッケージレジストリのPyPIから依存関係をインストールできます。たとえば、以下の YAML では、pip パッケージインストーラーと、setuptools および wheel パッケージがインストールまたはアップグレードされます。

ワークフローの速度を上げるために、依存関係をキャッシュすることもできます。詳細については、「依存関係をキャッシュしてワークフローのスピードを上げる」を参照してください。

YAML

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

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

Requirementsファイル

pip の更新後の一般的な次の手順は、requirements.txt から依存関係をインストールすることです。詳しくは、「pip」をご覧ください。

YAML

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

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

依存関係のキャッシング

setup-pythonアクションを使用して依存関係をキャッシュおよび復元できます。

次の例では pip の依存関係をキャッシュします。

YAML

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

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

既定で、setup-python アクションでは、リポジトリ全体で依存関係ファイル (pip の場合は requirements.txt、pipenv の場合は Pipfile.lock、poetry の場合は poetry.lock) を検索します。詳細については、setup-python README のパッケージの依存関係のキャッシュに関するページを参照してください。

カスタム要件がある場合、またはキャッシュに対してより細かい制御が必要な場合は、cache アクションを使用できます。ランナーのオペレーティングシステムによって、pipは依存関係を様々な場所にキャッシュします。キャッシュする必要があるパスは、使用するオペレーティングシステムによって、上記の Ubuntu の例とは異なる場合があります。詳細については、cache アクションリポジトリの Python キャッシュの例に関するページを参照してください。

コードのテスト

ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。

pytest及びpytest-covでのテスト

この例では、pytest および pytest-cov をインストールまたはアップグレードします。そしてテストが実行され、JUnit形式で出力が行われ、一方でコードカバレッジの結果がCoberturaに出力されます。詳細については、JUnit と Cobertura に関するページを参照してください。

YAML

steps:
- uses: actions/checkout@v4
- name: Set up Python
  uses: actions/setup-python@v4
  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@v4
- name: Set up Python
  uses: actions/setup-python@v4
  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

コードの lint に Ruff を使う

以下の例では、ruff をインストールまたはアップグレードし、それを使ってすべてのファイルを lint します。詳しくは、「Ruff」を参照してください。

YAML

steps:
- uses: actions/checkout@v4
- name: Set up Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- name: Lint with Ruff
  run: |
    pip install ruff
    ruff --output-format=github .
  continue-on-error: true

steps:
- uses: actions/checkout@v4
- name: Set up Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.x'
- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt
- name: Lint with Ruff
  run: |
    pip install ruff
    ruff --output-format=github .
  continue-on-error: true

リンティングステップには continue-on-error: true が設定されています。これにより、リンティングステップが成功しなかった場合にワークフローが失敗しなくなります。すべてのリンティングエラーに対処したら、ワークフローで新しい Issue を見つけられるようにこのオプションを削除できます。

toxでのテストの実行

GitHub Actionsでは、toxでテストを実行し、その処理を複数のジョブに分散できます。 tox を起動する際には、特定のバージョンを指定するのではなく、-e py オプションを使って PATH の Python のバージョンを選択する必要があります。詳細については、tox に関するページを参照してください。

YAML

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        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.10", "3.11"]

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
        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 アクション」を参照してください。

YAML

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v4
        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.7", "3.8", "3.9", "3.10", "3.11"]

    steps:
      - uses: actions/checkout@v4
      - name: Setup Python # Set Python version
        uses: actions/setup-python@v4
        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() }}

パッケージレジストリへの公開

CI テストにパスしたら、Python パッケージをパッケージレジストリに公開するようにワークフローを構成できます。このセクションでは、GitHub Actions を使用して、リリースを公開するたびにパッケージを PyPI にアップロードする方法について説明します。

この例では、2 つの PyPI API トークンを作成する必要があります。パッケージを公開するのに必要なトークンまたは資格情報を格納するために、シークレットを使用することができます。詳しくは、「GitHub Actions でのシークレットの使用」を参照してください。

YAML

# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。

# GitHub では、コミット SHA にアクションをピン留めすることが推奨されます。
# 新しいバージョンを取得するには、SHA を更新する必要があります。
# タグまたはブランチを参照することもできますが、アクションは警告なしに変更される可能性があります。

name: Upload Python Package

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build
      - name: Build package
        run: python -m build
      - name: Publish package
        uses: pypa/gh-action-pypi-publish@v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してください。

# GitHub では、コミット SHA にアクションをピン留めすることが推奨されます。
# 新しいバージョンを取得するには、SHA を更新する必要があります。
# タグまたはブランチを参照することもできますが、アクションは警告なしに変更される可能性があります。

name: Upload Python Package

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install build
      - name: Build package
        run: python -m build
      - name: Publish package
        uses: pypa/gh-action-pypi-publish@v1
        with:
          password: ${{ secrets.PYPI_API_TOKEN }}

スターターワークフローの詳細については、「python-publish」を参照してください。

Python のビルドとテスト

この記事の内容