Python のビルドとテスト

はじめに

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

You must install the required software on your self-hosted runners. For more information about self-hosted runners, see "Hosting your own runners."

必要な環境

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

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

Using the Python starter workflow

GitHub provides a Python starter workflow that should work for most Python projects. This guide includes examples that you can use to customize the starter workflow. For more information, see the Python starter workflow.

To get started quickly, add the starter workflow to the .github/workflows directory of your repository.

YAML

name: Python package

on: [push]

jobs:
  build:

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

    steps:
      - uses: actions/checkout@v2
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v2
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install flake8 pytest
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
      - name: Lint with flake8
        run: |
          # stop the build if there are Python syntax errors or undefined names
          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
          # exit-zero はすべてのエラーを警告として扱う。 GitHub エディタの幅は 127 文字
          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
      - name: Test with pytest
        run: |
          pytest

Pythonのバージョンの指定

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

setup-actionの利用は、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の複数バージョンの利用

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      # python-version内のPyPyのバージョンが利用できる。
      # For example, pypy2 and pypy3
      matrix:
        python-version: ["2.7", "3.6", "3.7", "3.8", "3.9"]

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

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Set up Python 3.x
        uses: actions/setup-python@v2
        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.4 with arch x64 not foundといったエラーで失敗します。このエラーメッセージには、利用できるバージョンが含まれます。

実行したくないPythonの環境があるなら、ワークフロー中でexcludeキーワードを使うこともできます。詳しい情報については、「GitHub Actions のワークフロー構文」を参照してください。

YAML

name: Python package

on: [push]

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.6", "3.7", "3.8", "3.9", pypy2, pypy3]
        exclude:
          - os: macos-latest
            python-version: "3.6"
          - os: windows-latest
            python-version: "3.6"

デフォルトバージョンの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/*`mディレクトリにあります。

依存関係のインストール

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

YAML

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

Requirementsファイル

pipをアップデートした後、次の典型的なステップはrequirements.txtからの依存関係のインストールです。 For more information, see pip.

YAML

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

コードのテスト

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

pytest及びpytest-covでのテスト

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

YAML

steps:
- uses: actions/checkout@v2
- name: Set up Python
  uses: actions/setup-python@v2
  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
    pip install pytest-cov
    pytest tests.py --doctest-modules --junitxml=junit/test-results.xml --cov=com --cov-report=xml --cov-report=html

Flake8を使ったコードのlint

以下の例は、flake8をインストールもしくはアップグレードし、それを使ってすべてのファイルをlintします。詳しい情報についてはFlake8を参照してください。

YAML

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

The linting step has continue-on-error: true set. This will keep the workflow from failing if the linting step doesn't succeed. Once you've addressed all of the linting errors, you can remove this option so the workflow will catch new issues.

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.7", "3.8", "3.9"]

    steps:
      - uses: actions/checkout@v2
      - name: Setup Python
        uses: actions/setup-python@v2
        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.6", "3.7", "3.8", "3.9"]

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

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

You can configure your workflow to publish your Python package to a package registry once your CI tests pass. This section demonstrates how you can use GitHub Actions to upload your package to PyPI each time you publish a release.

For this example, you will need to create two PyPI API tokens. You can use secrets to store the access tokens or credentials needed to publish your package. 詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。

YAML

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

name: Upload Python Package

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        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@27b31702a0e7fc50959f5ad993c78deac1bdfc29
        with:
          user: __token__
          password: ${{ secrets.PYPI_API_TOKEN }}

For more information about the starter workflow, see python-publish.

Python のビルドとテスト

ここには以下の内容があります:

はじめに

必要な環境

Using the Python starter workflow

Pythonのバージョンの指定

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

特定のバージョンのPythonの利用

バージョンの除外

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

依存関係のインストール

Requirementsファイル

コードのテスト

pytest及びpytest-covでのテスト

Flake8を使ったコードのlint

toxでのテストの実行

成果物としてのワークフローのデータのパッケージ化

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

　特定のバージョンのPythonの利用