[Python] Blackの使い方 – ソースコードの自動整形

BlackはPythonコードの自動整形ツールで、PEP 8に準拠したフォーマットにコードを整形します。

使い方は簡単で、コマンドラインでblackコマンドを実行し、整形したいファイルやディレクトリを指定します。

例えば、black my_script.pyと入力すると、my_script.pyが自動的に整形されます。

オプションとして、--checkを使うと、整形せずにフォーマットが正しいかどうかを確認できます。

Blackは意見の分かれるフォーマットを排除し、統一されたスタイルを提供します。

Blackとは何か

Blackは、Pythonのコードを自動的に整形するためのツールです。

コードの可読性を向上させるために、統一されたスタイルでフォーマットを行います。

Blackは「意見のないスタイル」を採用しており、開発者がコードスタイルについて議論する必要を減らすことを目的としています。

これにより、チーム開発においても一貫性のあるコードが保たれ、メンテナンスが容易になります。

Blackは、コマンドラインから簡単に実行でき、特定のオプションを指定することで、さまざまな整形ルールを適用することが可能です。

Pythonのバージョンに応じた整形もサポートしており、幅広いプロジェクトで利用されています。

Blackのインストール方法

pipを使ったインストール

BlackはPythonのパッケージ管理ツールであるpipを使用して簡単にインストールできます。

以下のコマンドをターミナルまたはコマンドプロンプトで実行してください。

pip install black

このコマンドを実行することで、最新のBlackがインストールされます。

特定のバージョンをインストールしたい場合は、次のようにバージョン番号を指定します。

pip install black==22.3.0

バージョン確認方法

インストールが完了したら、Blackのバージョンを確認することができます。

以下のコマンドを実行してください。

black --version

このコマンドを実行すると、インストールされているBlackのバージョンが表示されます。

例えば、次のような出力が得られます。

black, 24.10.0 (compiled: yes)
Python (CPython) 3.12.4

インストール時のトラブルシューティング

Blackのインストール中に問題が発生することがあります。

以下は一般的なトラブルシューティングのポイントです。

これらのポイントを確認することで、インストール時の問題を解決できる可能性があります。

Blackの基本的な使い方

コマンドラインでの実行

Blackはコマンドラインから簡単に実行できます。

基本的なコマンドは以下の通りです。

black

このコマンドを実行すると、カレントディレクトリ内のすべてのPythonファイルが整形されます。

特定のファイルやディレクトリを指定することも可能です。

ファイル単位での整形

特定のPythonファイルを整形したい場合は、ファイル名を指定して実行します。

以下のコマンドを使用します。

black sample.py

このコマンドを実行すると、sample.pyというファイルが整形されます。

整形後のファイルは上書きされるため、元のコードは失われることに注意してください。

ディレクトリ単位での整形

ディレクトリ内のすべてのPythonファイルを整形するには、ディレクトリ名を指定します。

以下のコマンドを実行します。

black my_directory/

このコマンドを実行すると、my_directory内のすべてのPythonファイルが整形されます。

サブディレクトリも含めて整形されるため、プロジェクト全体を一度に整形することができます。

複数ファイルの一括整形

複数のファイルを一度に整形することも可能です。

ファイル名をスペースで区切って指定します。

以下のコマンドを実行します。

black file1.py file2.py file3.py

このコマンドを実行すると、file1.py、file2.py、file3.pyの3つのファイルが整形されます。

Blackの実行結果の確認

Blackを実行した後、整形された内容を確認するには、--checkオプションを使用します。

以下のコマンドを実行します。

black --check sample.py

このコマンドを実行すると、sample.pyが整形されているかどうかを確認できます。

整形が必要な場合は、整形されるべき内容が表示されます。

整形が不要な場合は、特に出力はありません。

これにより、コードが既に整形されているかどうかを簡単に確認できます。

Blackのオプション

–checkオプションでフォーマット確認

--checkオプションを使用すると、指定したファイルが整形されているかどうかを確認できます。

このオプションを使うと、整形が必要な場合にはその内容が表示され、整形されていない場合は何も表示されません。

以下のコマンドを実行します。

black --check sample.py

このコマンドを実行すると、sample.pyが整形されているかどうかを確認できます。

整形が必要な場合は、整形されるべき内容が表示されます。

–diffオプションで差分表示

--diffオプションを使用すると、整形前と整形後の差分を表示できます。

このオプションを使うことで、どの部分が変更されたのかを視覚的に確認できます。

以下のコマンドを実行します。

black --diff sample.py

このコマンドを実行すると、sample.pyの整形前と整形後の差分が表示されます。

変更された行が強調表示されるため、どの部分が修正されたのかが一目でわかります。

–line-lengthオプションで行の長さを指定

--line-lengthオプションを使用すると、整形時の行の最大長を指定できます。

デフォルトでは88文字ですが、プロジェクトのスタイルガイドに合わせて変更することができます。

以下のコマンドを実行します。

black --line-length 100 sample.py

このコマンドを実行すると、sample.pyの整形時に行の長さが100文字に設定されます。

これにより、長い行が自動的に折り返されることを防ぎます。

–target-versionオプションでPythonバージョンを指定

--target-versionオプションを使用すると、整形対象のPythonバージョンを指定できます。

これにより、特定のバージョンに合わせたコードスタイルが適用されます。

以下のコマンドを実行します。

black --target-version py38 sample.py

このコマンドを実行すると、sample.pyがPython 3.8に対応したスタイルで整形されます。

複数のバージョンを指定することも可能です。

–skip-string-normalizationオプションで文字列の整形を無効化

--skip-string-normalizationオプションを使用すると、文字列リテラルの整形を無効化できます。

これにより、シングルクォートとダブルクォートの変換が行われなくなります。

以下のコマンドを実行します。

black --skip-string-normalization sample.py

このコマンドを実行すると、sample.py内の文字列リテラルの整形が無効化されます。

特定のスタイルを維持したい場合に便利です。

–excludeオプションで特定ファイルを除外

--excludeオプションを使用すると、整形から特定のファイルやディレクトリを除外できます。

正規表現を使って指定することができます。

以下のコマンドを実行します。

black --exclude 'test_.*\.py' my_directory/

このコマンドを実行すると、my_directory内のファイルが整形されますが、test_で始まるPythonファイルは除外されます。

特定のファイルを整形から外したい場合に役立ちます。

Blackの設定ファイル

pyproject.tomlの概要

pyproject.tomlは、Pythonプロジェクトの設定を管理するためのファイルです。

Blackはこのファイルを使用して、整形に関する設定を一元管理します。

pyproject.tomlは、プロジェクトのルートディレクトリに配置され、他のツール(例えば、Flake8やPoetry)とも連携することができます。

このファイルを使うことで、プロジェクト全体の整形ルールを簡単に共有でき、チーム全体で一貫したスタイルを維持することが可能です。

pyproject.tomlでの設定例

以下は、pyproject.tomlでBlackの設定を行う例です。

[tool.black]
line-length = 88
target-version = ["py38", "py39"]
skip-string-normalization = true

この設定では、行の長さを88文字に設定し、Python 3.8および3.9に対応したスタイルで整形します。

また、文字列リテラルの整形を無効化しています。

これにより、プロジェクト内のすべてのファイルに対して一貫した設定が適用されます。

設定ファイルの優先順位

Blackは、設定ファイルの優先順位に従って設定を適用します。

以下の順序で設定が適用されます。

1. コマンドラインオプション
2. pyproject.tomlファイル
3. デフォルト設定

このため、コマンドラインで指定したオプションが最優先され、次にpyproject.tomlの設定が適用されます。

デフォルト設定は、特に指定がない場合に使用されます。

これにより、柔軟に設定を変更することができます。

Blackの設定ファイルを使うメリット

pyproject.tomlを使用することで、以下のようなメリットがあります。

• 一元管理: プロジェクト全体の設定を一つのファイルで管理できるため、設定の変更が容易です。
• チームでの共有: 設定ファイルをリポジトリに含めることで、チーム全体で同じスタイルを維持できます。
• 他のツールとの連携: pyproject.tomlは他のPythonツールとも互換性があるため、複数のツールを使う際に便利です。
• 設定の明示化: 設定内容が明示的に記述されるため、プロジェクトのスタイルガイドが明確になります。

これらのメリットにより、Blackを使用する際にはpyproject.tomlを活用することが推奨されます。

Blackのエディタ統合

VSCodeでのBlack設定

Visual Studio Code (VSCode) でBlackを使用するには、以下の手順を実行します。

1. Python拡張機能のインストール: VSCodeの拡張機能から Python を検索し、インストールします。
2. Blackのインストール: すでにBlackがインストールされていることを確認します。

ターミナルで以下のコマンドを実行します。

pip install black

3. 設定の変更: VSCodeの設定を開き、settings.jsonに以下の設定を追加します。

"python.formatting.provider": "black",
"editor.formatOnSave": true

これにより、ファイルを保存するたびにBlackが自動的に実行されます。

PyCharmでのBlack設定

PyCharmでBlackを使用するには、以下の手順を実行します。

1. Blackのインストール: ターミナルで以下のコマンドを実行して、Blackをインストールします。

pip install black

2. 設定の変更: PyCharmの設定を開き、Preferences > Tools > External Toolsに移動します。
3. 新しいツールの追加: +ボタンをクリックして新しいツールを追加し、以下の設定を行います。

• Name: Black
• Program: black(またはBlackのフルパス)
• Parameters: $FilePath$
• Working directory: $ProjectFileDir$

4. 実行: ファイルを右クリックし、External ToolsからBlackを選択して実行します。

Sublime TextでのBlack設定

Sublime TextでBlackを使用するには、以下の手順を実行します。

1. Blackのインストール: ターミナルで以下のコマンドを実行して、Blackをインストールします。

pip install black

2. Build Systemの作成: Tools > Build System > New Build System...を選択し、以下の内容を入力します。

{
    "cmd": ["black", "$file"],
    "selector": "source.python",
    "shell": true
}

このファイルをBlack.sublime-buildとして保存します。

3. Build Systemの選択: Tools > Build SystemからBlackを選択します。
4. 実行: Pythonファイルを開き、Cmd + B(Mac)またはCtrl + B(Windows/Linux)を押してBlackを実行します。

その他のエディタでのBlack設定

他のエディタでもBlackを統合することが可能です。

以下は一般的な手順です。

1. Blackのインストール: まず、ターミナルで以下のコマンドを実行してBlackをインストールします。

pip install black

2. エディタの設定: 使用しているエディタの設定メニューを開き、フォーマッタとしてBlackを指定します。

具体的な手順はエディタによって異なるため、各エディタのドキュメントを参照してください。

3. 自動実行の設定: ファイル保存時に自動的にBlackが実行されるように設定します。

これもエディタによって異なるため、各エディタの設定を確認してください。

これにより、さまざまなエディタでBlackを利用して、コードの整形を効率的に行うことができます。

Blackの応用例

CI/CDパイプラインでのBlackの利用

CI/CDパイプラインにBlackを組み込むことで、コードがリポジトリにマージされる前に自動的に整形されるように設定できます。

これにより、コードのスタイルが一貫して保たれ、レビュー時のスタイルに関する議論を減らすことができます。

具体的には、CIツール(GitHub Actions、Travis CIなど)の設定ファイルにBlackを実行するステップを追加します。

以下はGitHub Actionsの例です。

name: CI
on: [push, pull_request]
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.8'
      - name: Install dependencies
        run: |
          pip install black
      - name: Run Black
        run: |
          black --check .

この設定により、プッシュやプルリクエスト時にBlackが実行され、整形が必要な場合はエラーが返されます。

pre-commitフックでのBlackの自動実行

pre-commitフックを使用すると、コミット時に自動的にBlackを実行することができます。

これにより、コードがリポジトリに追加される前に整形が行われ、常に整形された状態を保つことができます。

以下は、pre-commitの設定例です。

1. pre-commitのインストール:

pip install pre-commit

2. .pre-commit-config.yamlの作成:

プロジェクトのルートディレクトリに以下の内容で.pre-commit-config.yamlファイルを作成します。

repos:
  - repo: https://github.com/psf/black
    rev: stable
    hooks:
      - id: black

3. pre-commitのインストール:

pre-commit install

これにより、コミット時にBlackが自動的に実行され、整形が行われます。

Blackと他のツール(isort, flake8)との併用

Blackは他のツールと併用することで、より効果的にコードの品質を保つことができます。

例えば、isortを使用してインポート文の順序を整え、flake8を使用してコードの静的解析を行うことができます。

以下は、これらのツールを併用するための設定例です。

1. ツールのインストール:

pip install black isort flake8

2. 設定ファイルの作成:

pyproject.tomlに以下の設定を追加します。

[tool.isort]
profile = "black"
[tool.black]
line-length = 88

この設定により、isortがBlackのスタイルに従ってインポート文を整形し、Blackがコード全体を整形します。

これにより、コードの整形とインポートの順序が一貫して保たれます。

チーム開発でのBlackの活用

チーム開発においてBlackを活用することで、コードのスタイルを統一し、メンテナンス性を向上させることができます。

以下のポイントを考慮することで、チーム全体でBlackを効果的に利用できます。

• 設定ファイルの共有: pyproject.tomlをリポジトリに含めることで、全員が同じ設定を使用できます。
• コードレビューの効率化: Blackを使用することで、コードレビュー時にスタイルに関する議論を減らし、機能やロジックに集中できます。
• 定期的な整形: 定期的にBlackを実行し、コードベースを整形することで、常にクリーンな状態を保つことができます。

これにより、チーム全体で一貫したスタイルを維持し、開発効率を向上させることができます。

Blackの制限と注意点

Blackが対応していないコードスタイル

Blackは「意見のないスタイル」を採用しているため、特定のコードスタイルに対する柔軟性がありません。

以下のようなスタイルには対応していないため、注意が必要です。

• カスタムインデント: Blackはスペース4つのインデントを使用しますが、タブや異なる数のスペースを使用することはできません。
• 行の長さの制限: デフォルトでは88文字に設定されていますが、これを超える行を特定のスタイルで整形することはできません。
• 特定のコメントスタイル: Blackはコメントの整形に関しても独自のルールを持っており、特定のスタイルを維持することが難しい場合があります。

これらの制限により、特定のプロジェクトやチームのスタイルガイドに従うことが難しい場合があります。

Blackの自動整形による副作用

Blackの自動整形は非常に便利ですが、いくつかの副作用が考えられます。

以下はその例です。

• 意図しない変更: Blackはコード全体を整形するため、意図しない部分が変更されることがあります。

特に、特定のスタイルを維持したい場合には注意が必要です。

• デバッグの難しさ: 自動整形によってコードが変更されるため、デバッグ時にどの部分が変更されたのかを追跡するのが難しくなることがあります。
• 他のツールとの競合: Blackと他のフォーマッタや静的解析ツール(例：isortやflake8)との間で設定が競合することがあり、整形結果が期待通りにならない場合があります。

これらの副作用を理解し、適切に対処することが重要です。

Blackの整形結果に不満がある場合の対処法

Blackの整形結果に不満がある場合、以下の対処法を検討できます。

1. 設定の見直し: pyproject.tomlで設定を見直し、行の長さやターゲットバージョンなどを調整します。
2. コマンドラインオプションの利用: --skip-string-normalizationや--line-lengthなどのコマンドラインオプションを使用して、特定の整形ルールを変更します。
3. 手動での修正: Blackによる整形後に、手動で特定の部分を修正することも可能です。

ただし、これにより一貫性が失われる可能性があるため、注意が必要です。

4. 他のフォーマッタとの併用: Blackと他のフォーマッタ(例：isort)を併用し、特定のスタイルを維持する方法もあります。

設定ファイルを適切に調整することで、整形結果を改善できます。

これらの対処法を活用することで、Blackの整形結果に対する不満を軽減し、より満足のいくコードスタイルを実現することができます。

まとめ

この記事では、Pythonのコード整形ツールであるBlackの基本的な使い方や設定方法、応用例、制限事項について詳しく解説しました。

Blackを活用することで、コードの可読性を向上させ、一貫したスタイルを保つことが可能になります。

ぜひ、プロジェクトにBlackを導入し、チーム全体でのコード整形を自動化することで、開発効率を高めてみてください。