はじめに
このガイドは、Pythonパッケージのビルド、テスト、公開の方法を紹介します。
GitHub ホストランナーには、Python および PyPy などのソフトウェアがプリインストールされたツールキャッシュがあります。 自分では何もインストールする必要がありません！ 最新のソフトウェアと、Python および PyPy のプリインストールされたバージョンの完全なリストについては、「GitHub ホストランナーの仕様」を参照してください。
必要な環境
YAMLとGitHub Actionsの構文に馴染んでいる必要があります。 詳しい情報については、「GitHub Actions を学ぶ」を参照してください。
Python、PyPy、pipの基本的な理解をしておくことをおすすめします。 詳しい情報については、以下を参照してください。
Pythonワークフローテンプレートでの開始
GitHubは、ほとんどのPythonプロジェクトで使えるPythonのワークフローテンプレートを提供しています。 このガイドには、テンプレートのカスタマイズに利用できる例が含まれます。 詳しい情報については、「Python のワークフローテンプレート」を参照してください。
手早く始めるために、テンプレートをリポジトリの.github/workflowsディレクトリに追加してください。
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [2.7, 3.5, 3.6, 3.7, 3.8]
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: |
# Python 構文エラーまたは未定義の名前がある場合はビルドを停止する
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: |
pytestPythonのバージョンの指定
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の複数バージョンの利用
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
# python-version内のPyPyのバージョンが利用できる。
# 例: pypy2 および pypy3
matrix:
python-version: [2.7, 3.5, 3.6, 3.7, 3.8]
steps:
- uses: actions/checkout@v2
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
# 現在の Python バージョンを印刷出力してマトリックスをテスト可能
- name: Display Python version
run: python -c "import sys; print(sys.version)"特定のバージョンのPythonの利用
Pythonの特定バージョンを設定することができます。 たとえば3.8が利用できます。 あるいは、最新のマイナーリリースを取得するためにセマンティックバージョン構文を使うこともできます。 以下の例では、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:
# セマンティックバージョン範囲の構文または Python バージョンの正確なバージョン
python-version: '3.x'
# Optional - x64 or x86 architecture, defaults to x64
architecture: 'x64'
# 現在の Python バージョンを出力してマトリックスをテスト可能
- 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: [2.7, 3.6, 3.7, 3.8, 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パッケージのインストールやアップグレードを行います。
GitHubホストランナーを使用する場合、依存関係をキャッシュしてワークフローの実行を高速化することもできます。 詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。
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 wheelRequirementsファイル
pipをアップデートした後、次の典型的なステップはrequirements.txtからの依存関係のインストールです。
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依存関係のキャッシング
GitHub ホストランナーを使用する場合、一意のキーを使用してpipの依存関係をキャッシュし、cacheアクションを使用して将来のワークフローを実行するときに依存関係を復元できます。 詳しい情報については、「ワークフローを高速化するための依存関係のキャッシュ」を参照してください。
ランナーのオペレーティングシステムによって、pipは依存関係を様々な場所にキャッシュします。 キャッシュする必要があるパスは、使用するオペレーティングシステムによって以下のUbuntuの例とは異なるかもしれません。 詳しい情報については、「Python のキャッシングの例」を参照してください。
steps:
- uses: actions/checkout@v2
- name: Setup Python
uses: actions/setup-python@v2
with:
python-version: '3.x'
- name: Cache pip
uses: actions/cache@v2
with:
# このパスは Ubuntu に固有です
path: ~/.cache/pip
# 対応する要件ファイルにキャッシュヒットがあるかどうかを確認する
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
${{ runner.os }}-
- name: Install dependencies
run: pip install -r requirements.txtノート： 依存関係の数によっては、依存関係キャッシュを使う方が高速になることがあります。 多くの大きな依存関係を持つプロジェクトでは、ダウンロードに必要な時間を節約できるので、パフォーマンスの向上が見られるでしょう。 依存関係が少ないプロジェクトでは、大きなパフォーマンスの向上は見られないかもしれず、pipがキャッシュされた依存関係をインストールする方法のために、パフォーマンスがやや低下さえするかもしれません。 パフォーマンスはプロジェクトによって異なります。
コードのテスト
ローカルで使うのと同じコマンドを、コードのビルドとテストに使えます。
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=htmlFlake8を使ったコードの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 .toxでのテストの実行
GitHub Actionsでは、toxでテストを実行し、その処理を複数のジョブに分散できます。 toxを起動する際には、特定のバージョンを指定するのではなく、-e pyオプションを使ってPATH中のPythonのバージョンを選択しなければなりません。 詳しい情報については toxを参照してください。
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python: [2.7, 3.7, 3.8]
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
# 「PATH」で Python のバージョンを使用して tox を実行する
run: tox -e py成果物としてのワークフローのデータのパッケージ化
ワークフローの完了後に、成果物をアップロードして見ることができます。 たとえば、ログファイル、コアダンプ、テスト結果、スクリーンショットを保存する必要があるかもしれません。 詳しい情報については「成果物を利用してワークフローのデータを永続化する」を参照してください。
以下の例は、upload-artifactアクションを使ってpytestの実行によるテスト結果をアーカイブする方法を示しています。 詳しい情報についてはupload-artifactアクションを参照してください。
name: Python package
on: [push]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [2.7, 3.5, 3.6, 3.7, 3.8]
steps:
- uses: actions/checkout@v2
- name: Setup Python # Set Python version
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
# pip および 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
# always() を使用して常にこのステップを実行し、テストが失敗したときにテスト結果を公開する
if: ${{ always() }}パッケージレジストリへの公開
CIテストにパスしたなら、Pythonパッケージを任意のパッケージレジストリに公開するようにワークフローを設定できます。
パッケージを公開するのに必要なアクセストークンや認証情報は、シークレットを使って保存できます。 以下の例では、twineとdistを使ってパッケージを作成してPyPIに公開しています。 詳しい情報については、「暗号化されたシークレットの作成と利用」を参照してください。
name: Upload Python Package
on:
release:
types: [created]
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 setuptools wheel twine
- name: Build and publish
env:
TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
run: |
python setup.py sdist bdist_wheel
twine upload dist/*テンプレートワークフローに関する詳しい情報については、「python-publish」を参照してください。