こんにちは、吉政創成 菱沼です。
今回もPythonエンジニア育成推進協会のPython 3 エンジニア認定実践試験の主教材「Python実践レシピ／技術評論社」を使って学習中です。
前回、2.3「ソースコードの自動整形 -Blak」に入り、妥協しないコードフォーマッターBlackの基本的な部分について学びました。今回は、Blackのオプションや使い方などについて学びます。
前回の記事に興味がある方はこちらをご覧ください。
初めてのPython実践試験学習 第13回「コードフォーマッターBlack様」
Black様で使えるオプション
Blackにもオプションが用意されており、1行の最大の長さなどを設定することができます。
どういったコマンドがあるのかは「black –help」コマンドで確認することができますが、その中でもよく利用されるものについてテキストで紹介されています。
公式ドキュメントで確認したい方は以下のURLからどうぞ！
https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#command-line-options
—————————
P.35
| Blackの主要なコマンドラインオプション | 解説 |
| -l、–line-length | 1行の最大文字数（デフォルト88文字） |
| –check | ファイルをチェックし結果を出力する。ファイルの修正はしない。 |
| –diff | ファイルをチェックし差分を出力する。ファイルの修正はしない。 |
| –include | チェックしたいファイルやディレクトリを正規表現で指定 |
| –exclude | 除外するファイルやディレクトリを正規表現で指定 |
上記のオプションのなかでよく使われるのは–check–diffです。複数人で開発をする場合にそれぞれ書いたコードがBlackのルールに則っているか、CI（継続的インテグレーション）などで定期的にチェックするために使われます。
—————————
–checkを実行すると、指定したファイルに問題がある場合には1が表示され、ない場合には0が表示されるそうです。もう一つの–diffは修正される内容が表示されるとのこと。Blackにファイルを修正させたくない時に利用する模様。
これらのオプションを利用したい場合は、設定ファイルに記述することになります。
Black様のオプション設定を記述するpyproject.tomlとは？
—————————
P.35
「1行の文字数は99文字」という設定と、Blackのチェック対象にしないディレクトリを設定しています。
| [tool.black]line-length = 99exclude = ‘venv|tests\data’ |
なお、excludeが設定されていない場合、Gitの除外ファイルを指定する.gitignoreがあればそこに指定されているファイルはBlackのチェック対象から自動的に除外されます。
Blackの設定ファイルは、次の場所に配置することで有効になります。
- プロジェクトディレクトリ
・pyproject.toml - ユーザーディレクトリ
・~/.config/black（LinuxやmacOSなどの場合）
・～\black（Windowsの場合）
ユーザーディレクトリへ設定ファイルを配置すると、自身の開発環境で有効になるグローバルな設定となります。
—————————
設定ファイルをプロジェクトディレクトリの一番上の階層に設置する理由を調べてみたところ、
- 他のプロジェクトとの一貫性を持たせること
- 設定ファイルの管理がしやすいこと
- 他のツールの設定が一元管理できること
といった理由があるようです。複数のプロジェクトを走らせる現場なら確かにその方が便利なんだろうなと思いました。
また、「ユーザーディレクトリに設置するとグローバルな～」についてですが、これはBlackが設定ファイルを探すときの順序によるものだそうです。
Blackコマンドを実行する→コマンドを実行したディレクトリ内を探す→なければ親ディレクトリ→なければ親ディレクトリと言った形で、順番に上の階層にさかのぼっていき、それでもどうしても見つからない場合は、ユーザーのホームディレクトリの特定の場所を検索するところまでするそうです。そうして探す中で最初に見つかった設定ファイルを基準としてチェックをするということだと。
つまり、プロジェクトとは関係なく、開発者の個人的な好みを反映したpyproject.tomlをユーザーディレクトリに置いておくことで、個人的な開発をするときにpyproject.tomlをプロジェクトディレクトリにわざわざ作らなくとも、「個人的な好み」を反映した形でチェックしてくれるということなんだそうな。
pyproject.tomlの設置場所について詳しく知りたい方は以下のURLをご参照ください。
Black様に条件を伝えるpyproject.tomlを作ってみよう
というわけで、実際に「pyproject.toml」を作成して設置してみます。
私はVS Codeで作成しましたが、メモ帳などの好きなテキストエディタで大丈夫です。
先ほど設定ファイルの記述例を引用しましたが、その中のexcludeの項目にvenvとありました。
なぜ入っているかというと、チェックの対象に仮想環境（venv）を含めてしまうと、チェックにとんでもなく時間が掛かるそうで、仮想環境の構築に関連したファイルについては、対象外のリストとして入れておいた方が良いということのようです。例はサンプルなのでvenvと書かれていますが、実際には作った仮想環境の名称が指定されます。
私の場合、test2024というプロジェクトディレクトリの中に、いくつかのvenv環境が作成されており、このコラムで使用している環境の名前は「pythonic-exam」です。Blackがインストールされているのは今のところpythonic-examだけになります。
なので設置場所はプロジェクトの一番上の階層であるtest2024の中に。
そして除外の対象としたいのは仮想環境「pythonic-exam」を作成したときに作られたenv、Include、Lib、Scriptsと、test2024内にある他の仮想環境になります。
というわけで、サンプルに従って自分用に設定ファイルを変更してみたのがこちらです。
サンプルにはありませんでしたが、.pyとついたファイルをチェックするという条件を追加しました。
これでうっかりに定評のある私が何も気にせずBlackを実行しても、.pyファイル以外のファイルが修正されてしまうという事態は避けられるはずです。
ところで、サンプルと違って、1行ではなく、「’’’/()/’’’」で囲んで複数行で書かれています。
これは実際にこうしたファイルを作る必要が出てきた場合、複数のファイルやディレクトリを対象とすることになります。そうすると1行に詰め込むと読みにくくなってしまうので、正規表現である「’’’/()/’’’」で囲んで改行して書くようにするのだそうです。
また正規表現などの特別な時に使われるような記号（.、 *、 |、 (、 )、 \ など）を文字列として使っていた場合に、そのまま文字列として認識してもらうといった意図もあるそうです。
というわけで、該当のディレクトリ内にあるtestcodeディレクトリ内のファイルをチェックしてもらいました。
たぶんできてる。はず。
それではきりが良いので、今回はこちらで終了です。お付き合いいただきありがとうございました。
実践試験について知りたい方は以下をご覧ください。
●Python3エンジニア認定実践試験