GitHub Actions 統合¶

独自の Python 環境を設定することなく、GitHub Actions ワークフロー内で Black を使用できます。コードが Black のコーディングスタイルに一致することを強制するのに最適です。

互換性¶

このアクションは、GitHub がホストするすべてのランナー OS をサポートすることが知られています。さらに、公開されているバージョンの Black のみがサポートされています（つまり、PyPI で入手可能なバージョン）。

最後に、このアクションは Black を colorama エクストラと共にインストールするため、--color フラグは正常に動作するはずです。

使用方法¶

リポジトリ内に .github/workflows/black.yml という名前のファイルを作成し、以下の内容を記述します。

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: psf/black@stable

@stable タグの使用を推奨しますが、バージョンごとのタグも必要に応じて存在します。選択するアクションのバージョンは、アクションが使用する Black のバージョンとは独立していることに注意してください。

アクションが使用する Black のバージョンは、version で設定するか、pyproject.toml ファイルから読み取ることができます。version は、有効なバージョン指定子または、正確なバージョンが必要な場合はバージョン番号のみを指定できます。pyproject.toml ファイルからバージョンを読み取るには、use_pyproject を true に設定します。これにより、最初に tool.black.required-version フィールド、次に project.dependencies 配列、最後に project.optional-dependencies テーブルが検索されます。アクションはデフォルトで PyPI で利用可能な最新のリリースに設定されます。PyPI から入手可能なバージョンのみがサポートされているため、コミット SHA やブランチ名は使用できません。

Jupyter Notebook を含める場合は、Black を jupyter エクストラと共にインストールする必要があります。エクストラのインストールと Jupyter Notebook ファイルの包含は、jupyter で設定できます（デフォルトは false です）。

Black に渡される引数は、options（デフォルトは '--check --diff'）と src（デフォルトは '.'）で設定することもできます。--check フラグは、Black がフォーマットする必要があるファイルを見つけた場合にワークフローが失敗するようにするために必要です。

設定例を以下に示します。

- uses: psf/black@stable
  with:
    options: "--check --verbose"
    src: "./src"
    jupyter: true
    version: "21.5b1"

Black の安定性ポリシーでカバーされているバージョンと一致させる場合は、互換リリース演算子（~=）を使用できます。

- uses: psf/black@stable
  with:
    options: "--check --verbose"
    src: "./src"
    version: "~= 22.0"

pyproject.toml からバージョンを読み取る場合は、use_pyproject を true に設定します。

- uses: psf/black@stable
  with:
    options: "--check --verbose"
    src: "./src"
    use_pyproject: true