注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
はじめに
このガイドは、Pythonパッケージのビルド、テスト、公開の方法を紹介します。
GitHub ホスト ランナーには、Python と PyPy を含む、ソフトウェアがプレインストールされたツール キャッシュがあります。 自分では何もインストールする必要がありません! 最新のソフトウェアと、Python および PyPy のプレインストールされたバージョンの完全なリストについては、「GitHub ホスト ランナーの仕様」を参照してく� さい。
前提条件
YAMLとGitHub Actionsの構文に馴染んでいる必要があります。 詳細については、「GitHub Actions について学ぶ」を参照してく� さい。
Python、PyPy、pipの基本的な理解をしておくことをおすすめします。 詳細については、次を参照してく� さい。
GitHub Enterprise Server上でのセルフホストランナーの利用
GitHub Enterprise Server でセルフホスト ランナーと合わせてセットアップ アクション (actions/setup-LANGUAGE
など) を使用するときに、インターネットにアクセスできないランナー上にツール キャッシュを設定する必要がある� �合があります。 詳細については、「インターネットにアクセスできないセルフホスト ランナーにツール キャッシュを設定する」を参照してく� さい。
Python スターター ワークフローの使用
GitHub では、ほとんどの Python プロジェクトで使える Python スターター ワークフローが提供されています。 このガイドには、スターター ワークフローのカスタマイズに使用できる例が含まれます。 詳細については、「Python スターター ワークフロー」を参照してく� さい。
すぐに作業を開始するには、リポジトリの .github/workflows
ディレクトリにスターター ワークフローを追� します。
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.7", "3.8", "3.9", "3.10"]
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 treats all errors as warnings. The GitHub editor is 127 chars wide
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-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の複数バージョンの利用
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
# You can use PyPy versions in python-version.
# For example, pypy2 and pypy3
matrix:
python-version: ["2.7", "3.7", "3.8", "3.9", "3.10"]
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.9" です。 あるいは、最新のマイナーリリースを取得するためにセマンティックバージョン構文を使うこともできます。 以下の例では、Python 3の最新のマイナーリリースを使います。
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 のワークフロー構文に関するページを参照してく� さい。
name: Python package
on: [push]
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
python-version: ["3.7", "3.8", "3.9", "3.10", pypy2, pypy3]
exclude:
- os: macos-latest
python-version: "3.7"
- os: windows-latest
python-version: "3.7"
デフォルトバージョンの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
パッケージがインストールまたはアップグレードされます。
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 から依存関係をインストールすることです。 詳しくは、「pip」をご覧く� さい。
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 に関するページを参照してく� さい。
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 に関するページを参照してく� さい。
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
リンティング ステップには continue-on-error: true
が設定されています。 これにより、リンティング ステップが成功しなかった� �合にワークフローが失敗しなくなります。 すべてのリンティング エラーに対処したら、ワークフローで新しい Issue を見つけられるようにこのオプションを削除できます。
toxでのテストの実行
GitHub Actionsでは、toxでテストを実行し、その処理を複数のジョブに分散できます。 tox を起動する際には、特定のバージョンを指定するのではなく、-e py
オプションを使って PATH
の Python のバージョンを選択する必要があります。 詳細については、tox に関するページを参照してく� さい。
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python: ["3.8", "3.9", "3.10"]
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
アクション」を参照してく� さい。
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.7", "3.8", "3.9", "3.10"]
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() }}
パッケージレジストリへの公開
CI テストにパスしたら、Python パッケージをパッケージ レジストリに公開するようにワークフローを構成できます。 このセクションでは、GitHub Actions を使用して、リリースを公開するたびにパッケージを PyPI にアップロードする方法について説明します。
この例では、2 つの PyPI API トークンを作成する必要があります。 パッケージを公開するのに必要なトークンまたは資� �情� �を� �納するために、シークレットを使用することができます。 詳細については、「暗号化されたシークレットの作成と使用」を参照してく� さい。
# このワークフローはGitHubによって認定されていないアクションを使用します。
# それらはサードパーティによって提供され、
# 別個の利用規約、プライバシーポリシー、
# ドキュメントを参照してく� さい。
# GitHub では、コミット SHA にアクションをピン留めすることが推奨されます。
# 新しいバージョンを取得するには、SHA を更新する必要があります。
# タグまたはブランチを参照することもできますが、アクションは警告なしに変更される可能性があります。
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 }}
スターター ワークフローの詳細については、「python-publish
」を参照してく� さい。