基本事項¶

Blackの使用と設定に関する基礎知識。

Blackは、動作が良好なUnixスタイルのコマンドラインツールです。

フォーマットするソースが見つからない場合は何も行いません。
ファイル名として-が使用されている場合、標準入力から読み込み、標準出力に書き込みます。
標準エラーにユーザーへのメッセージのみを出力します。
内部エラーが発生した場合、またはCLIオプションによって指示された場合を除き、コード0で終了します。

使用方法¶

Blackは、ファイルをすべてその場で再フォーマットします。適切なデフォルト設定ですぐに開始するには

black {source_file_or_directory}

スクリプトとして実行できない場合、パッケージとしてBlackを実行できます。

python -m black {source_file_or_directory}

セクションの無視¶

Blackは、# fmt: skipを含む行、または# fmt: offで始まり# fmt: onで終わるブロックを再フォーマットしません。# fmt: skipは、複数のコメント（例：# fmt: skip # pylint # noqa）またはセミコロンで区切られたリスト（例：# fmt: skip; pylint; noqa）のいずれかで他のpragma/コメントと混在させることができます。# fmt: on/offは、同じインデントレベルに、同じブロック内に存在する必要があります。つまり、それらの間に最初のインデントレベルを超えるインデント解除はありません。Blackは、コードをまたがる便宜上、YAPFのブロックコメントも同様に認識します。

コマンドラインオプション¶

Blackのコマンドラインオプションは、black --helpを実行することで表示できます。すべてのオプションについては、以下でさらに詳しく説明します。

Blackには現在多くの設定項目がありますが、それでもなお独自のスタイルを重視しているため、スタイルオプションは意図的に制限されており、追加されることはほとんどありません。

pyproject.tomlファイルを使用して、上記のコマンドラインオプションをすべて設定することもできます（詳細は後述）。

`-h`、`--help`¶

使用可能なコマンドラインオプションを表示して終了します。

`-c`、`--code`¶

文字列として渡されたコードをフォーマットします。

$ black --code "print ( 'hello, world' )"
print("hello, world")

`-l`、`--line-length`¶

許容する1行あたりの文字数。デフォルトは88です。

スタイルドキュメントも参照してください。

`-t`、`--target-version`¶

Blackの出力がサポートする必要があるPythonのバージョン。black --helpを実行して--target-versionオプションを探すと、サポートされているバージョンの完全なリストが表示されます。コードでサポートされているバージョンをすべて含める必要があります。Python 3.8から3.11をサポートしている場合は、次のように記述します。

$ black -t py38 -t py39 -t py310 -t py311

設定ファイルでは、次のように記述できます。

target-version = ["py38", "py39", "py310", "py311"]

デフォルトでは、Blackはpyproject.tomlのプロジェクトメタデータ、特に[project.requires-python]フィールドからターゲットバージョンを推測します。これにより決定的な結果が得られない場合は、Blackはファイルごとの自動検出を使用します。

Blackはこのオプションを使用して、コードを解析する際に使用する構文を決定します。さらに、スタイルを決定する場合にも使用される場合があります。たとえば、関数呼び出しでの*argsの後の末尾のコンマのサポートはPython 3.5で追加されたため、BlackはターゲットバージョンがすべてPython 3.5以降の場合にのみこのコンマを追加します。

$ black --line-length=10 --target-version=py35 -c 'f(a, *args)'
f(
    a,
    *args,
)
$ black --line-length=10 --target-version=py34 -c 'f(a, *args)'
f(
    a,
    *args
)
$ black --line-length=10 --target-version=py34 --target-version=py35 -c 'f(a, *args)'
f(
    a,
    *args
)

`--pyi`¶

ファイル拡張子に関係なく、すべての入力ファイルを型スタブのようにフォーマットします。これは、標準入力でソースをパイプ処理する場合に役立ちます。

`--ipynb`¶

ファイル拡張子に関係なく、すべての入力ファイルをJupyter Notebookのようにフォーマットします。これは、標準入力でソースをパイプ処理する場合に役立ちます。

`--python-cell-magics`¶

Jupyter Notebookを処理する際に、指定したマジックを既知のpython-マジックのリストに追加します。カスタムpythonマジックを含むセルのフォーマットに役立ちます。

`-x, --skip-source-first-line`¶

ソースコードの最初の行をスキップします。

`-S, --skip-string-normalization`¶

デフォルトでは、Blackはすべての文字列に二重引用符を使用し、スタイルドキュメントで説明されているように、文字列プレフィックスを正規化します。このオプションが指定されている場合、文字列は変更されません。

`-C, --skip-magic-trailing-comma`¶

デフォルトでは、Blackは既存の末尾のコンマを、短い行を別々に残すべきであることの指標として使用します。スタイルドキュメントで説明されているように、このオプションが指定されている場合、マジック末尾のコンマは無視されます。

`--preview`¶

次のメジャーリリースでBlackの主要な機能に追加されることが予想される、破壊的な可能性のあるスタイルの変更を有効にします。来年のスタイルを試してみたい場合は、これを使用してください。

プレビュースタイルについて詳しくは、こちらをご覧ください。

このフラグによって生成されるコードスタイルについては、リリース間で保証はありません。

`--unstable`¶

--previewのすべてのスタイル変更に加えて、最終的に行いたい追加の変更を有効にします。ただし、--previewスタイルに戻す前に修正する必要がある既知の問題があります。これらの変更を試して、問題の修正に役立てたい場合は、これを使用してください。

このフラグによって生成されるコードスタイルについては、リリース間で保証はありません。

`--enable-unstable-feature`¶

--unstableスタイルから特定の機能を有効にします。プレビュースタイルドキュメントで、サポートされている機能のリストを確認してください。このフラグは、--previewが有効になっている場合にのみ使用できます。--previewスタイルを使用しており、コードに影響を与える機能が--previewから--unstableスタイルに移動されたが、この変更を元に戻すことによる混乱を避けたい場合は、このフラグを使用することをお勧めします。

これらの機能の動作、さらには存在についても、リリース間で保証はありません。

`--check`¶

ファイルを書き戻さず、ステータスだけを返します。Blackは次のコードで終了します。

何も変更されない場合、コード0。
いくつかのファイルが再フォーマットされる場合、コード1。
内部エラーが発生した場合、コード123。

--quietと組み合わせて使用した場合、内部エラーが発生した場合を除き、終了コードのみが返されます。

$ black test.py --check
All done! ✨ 🍰 ✨
1 file would be left unchanged.
$ echo $?
0

$ black test.py --check
would reformat test.py
Oh no! 💥 💔 💥
1 file would be reformatted.
$ echo $?
1

$ black test.py --check
error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source.  Please report a bug on https://github.com/psf/black/issues.  This diff might be helpful: /tmp/blk_kjdr1oog.log
Oh no! 💥 💔 💥
1 file would fail to reformat.
$ echo $?
123

`--diff`¶

ファイルを書き戻さず、Blackが行った変更を示すdiffを出力します。標準出力に出力されるため、キャプチャが簡単です。

カラーdiffが必要な場合は、--colorで有効にできます。

$ black test.py --diff
--- test.py     2021-03-08 22:23:40.848954+00:00
+++ test.py     2021-03-08 22:23:47.126319+00:00
@@ -1 +1 @@
-print ( 'hello, world' )
+print("hello, world")
would reformat test.py
All done! ✨ 🍰 ✨
1 file would be reformatted.

`--color` / `--no-color`¶

カラーdiffを表示（または非表示）します。--diffが指定されている場合にのみ適用されます。

`--line-ranges`¶

指定されている場合、Blackはこれらの行のみをフォーマットしようとします。

このオプションは複数回指定でき、行の和集合がフォーマットされます。各範囲は、-で接続された2つの整数として指定する必要があります：<START>-<END>。<START>と<END>の整数インデックスは1ベースで、両端を含むものです。

複数行のステートメントの場合、Blackは範囲外の行もフォーマットする場合があります。このオプションを使用して複数のファイルまたはipynbファイルをフォーマットすることはサポートされていません。このオプションはpyproject.toml設定では指定できません。

例: black --line-ranges=1-10 --line-ranges=21-30 test.py は、1 行目から 10 行目、および 21 行目から 30 行目をフォーマットします。

このオプションは、主に「選択範囲のフォーマット」などのエディター統合のために使用されます。

注記

#4052 のため、同一の内容を持つ未フォーマットの行が存在する場合、--line-ranges は指定範囲外の行もフォーマットすることがあります。--safe モードでは、Black のフォーマット安定性チェックも無効になります。

`--fast` / `--safe`¶

デフォルトでは、Black はコードのフォーマット後にAST セーフティチェックを実行します。--fast フラグはこのチェックを無効にし、--safe フラグは明示的に有効にします。

`--required-version`¶

実行する Black の特定のバージョンを要求します。これは、プロジェクトのすべての貢献者が同じバージョンを使用していることを保証するのに役立ちます。異なるバージョンの Black では、コードのフォーマットが多少異なる可能性があるためです。このオプションは、環境間で一貫した結果を得るために、設定ファイルで設定できます。

$ black --version
black, 24.8.0 (compiled: yes)
$ black --required-version 24.8.0 -c "format = 'this'"
format = "this"
$ black --required-version 31.5b2 -c "still = 'beta?!'"
Oh no! 💥 💔 💥 The required version does not match the running version!

メジャーバージョンのみを指定することもできます。

$ black --required-version 22 -c "format = 'this'"
format = "this"
$ black --required-version 31 -c "still = 'beta?!'"
Oh no! 💥 💔 💥 The required version does not match the running version!

当社の安定性ポリシーにより、これは安定したフォーマットを保証しますが、フォーマットに影響を与えない改善を活用することもできます。

`--exclude`¶

再帰的な検索で除外するファイルとディレクトリに一致する正規表現です。空の値は、パスが除外されないことを意味します。すべてのプラットフォーム（Windows も）で、ディレクトリにはスラッシュを使用してください。デフォルトでは、Black は .gitignore にリストされているすべてのパスも無視します。この値を変更すると、すべてのデフォルトの除外が上書きされます。

正規表現に改行が含まれている場合、詳細な正規表現として扱われます。これは通常、pyproject.toml 設定ファイルでこれらのオプションを設定する場合に役立ちます。詳細は設定形式を参照してください。

`--extend-exclude`¶

--exclude と同様ですが、デフォルト値を上書きする代わりに、デフォルト値に追加でファイルとディレクトリを追加します。

`--force-exclude`¶

--exclude と同様ですが、この正規表現に一致するファイルとディレクトリは、引数として明示的に渡された場合でも除外されます。これは、プリコミットフックやエディタープラグインなど、変更されたファイルに対して Black をプログラムで呼び出す場合に役立ちます。

`--stdin-filename`¶

標準入力から渡す場合のファイル名です。 stdin を使用するエディターで --force-exclude オプションが確実に尊重されるようにするために役立ちます。

`--include`¶

再帰的な検索で含めるファイルとディレクトリに一致する正規表現です。空の値は、名前に関わらずすべてのファイルが含まれることを意味します。すべてのプラットフォーム（Windows も）で、ディレクトリにはスラッシュを使用してください。.gitignore とコマンドラインオプションを含むすべての除外を上書きします。

`-W`、`--workers`¶

Black が複数のファイルをフォーマットする場合、プロセスプールを使用してフォーマットを高速化することがあります。このオプションは、並列ワーカーの数を制御します。BLACK_NUM_WORKERS 環境変数でも指定できます。デフォルトはシステムの CPU 数です。

`-q`、`--quiet`¶

すべての非クリティカルな出力の出力停止します。エラーメッセージは引き続き出力されます（2>/dev/null で無効にすることができます）。

$ black src/ -q
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio

`-v`、`--verbose`¶

変更されなかったファイル、または除外パターンにより無視されたファイルに関するメッセージを出力します。Black が設定ファイルを使用している場合、使用している設定ファイルの詳細を示すメッセージが出力されます。

$ black src/ -v
Using configuration from /tmp/pyproject.toml.
src/blib2to3 ignored: matches the --extend-exclude regular expression
src/_black_version.py wasn't modified on disk since last run.
src/black/__main__.py wasn't modified on disk since last run.
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
reformatted src/black_primer/lib.py
reformatted src/blackd/__init__.py
reformatted src/black/__init__.py
Oh no! 💥 💔 💥
3 files reformatted, 2 files left unchanged, 1 file failed to reformat

`--version`¶

--version フラグを使用して、インストールされている Black のバージョンを確認できます。

$ black --version
black, 24.8.0

`--config`¶

設定ファイルから設定オプションを読み取ります。設定ファイルの詳細については、下記を参照してください。

環境変数オプション¶

Black は、環境変数による次の設定をサポートしています。

`BLACK_CACHE_DIR`¶

Black がキャッシュを保存するディレクトリです。

`BLACK_NUM_WORKERS`¶

Black が使用する並列ワーカーの数です。-W / --workers コマンドラインオプションは、この環境変数よりも優先されます。

コード入力の代替手段¶

Black は、標準入力からコードをフォーマットし、結果を標準出力に出力することをサポートしています。パスとして - を指定するだけで Black が認識します。

$ echo "print ( 'hello, world' )" | black -
print("hello, world")
reformatted -
All done! ✨ 🍰 ✨
1 file reformatted.

**ヒント:** Black に標準入力の入力を CLI を介して直接渡されたファイルとして扱わせる必要がある場合は、--stdin-filename を使用します。 stdin を使用するエディターで --force-exclude オプションが確実に尊重されるようにするために役立ちます。

--code オプションを使用して、コードを文字列として渡すこともできます。

書き戻しとレポート¶

デフォルトでは、Black は指定されたファイル、または検出されたファイルをその場で再フォーマットします。Python ファイルを実際に書き換えることなく、Black が何をするかを伝える必要がある場合があります。

このモードには、それぞれのフラグによって個別に有効化される 2 つのバリエーションがあります。

--check（いずれかのファイルが再フォーマットされる場合、コード 1 で終了します）
--diff（ファイルを再フォーマットする代わりに差分を出力します）

両方のバリエーションを同時に有効にすることができます。

出力の詳細度¶

Black は一般的に、有用性と簡潔さのバランスをとって、適切な量の出力を作成しようとします。デフォルトでは、Black は変更されたファイルとエラーメッセージ、および短い概要を出力します。

$ black src/
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
reformatted src/black_primer/lib.py
reformatted src/blackd/__init__.py
reformatted src/black/__init__.py
Oh no! 💥 💔 💥
3 files reformatted, 2 files left unchanged, 1 file failed to reformat.

--quiet と --verbose フラグは、出力の詳細度を制御します。

ファイルによる設定¶

Black は、pyproject.toml ファイルからコマンドラインオプションのプロジェクト固有のデフォルト値を読み取ることができます。これは、プロジェクトのカスタム --include と --exclude / --force-exclude / --extend-exclude パターンの指定に特に役立ちます。

**プロヒント:** 「何か設定する必要があるか？」と自問自答する場合、答えは「いいえ」です。Black は、賢明なデフォルトに関するものです。これらのデフォルトを適用すると、多くの他の Black フォーマットのプロジェクトに準拠したコードになります。

`pyproject.toml` ファイルとは何か¶

PEP 518 は、pyproject.toml を Python プロジェクトのビルドシステムの要件を格納するための設定ファイルとして定義しています。Poetry、Flit、または Hatch などのツールを使用すると、setup.py と setup.cfg ファイルの必要性を完全に置き換えることができます。

Black がファイルを探す場所¶

デフォルトでは、Black はコマンドラインで渡されたすべてのファイルとディレクトリの共通のベースディレクトリから開始して、[tool.black] セクションを含む pyproject.toml を探します。ファイルが見つからない場合は、親ディレクトリを検索します。ファイル、.git ディレクトリ、.hg ディレクトリ、またはファイルシステムのルートのいずれかが見つかった時点で検索を停止します。

標準入力をフォーマットする場合は、Black は現在の作業ディレクトリから開始して設定を検索します。

ホームディレクトリの特定の場所に格納されている「グローバル」設定を使用できます。これはフォールバック設定として使用され、つまり、上記のいずれの設定も見つからない場合にのみ使用されます。オペレーティングシステムによっては、この設定ファイルは次のように保存する必要があります。

Windows: ~\.black
Unix系システム（Linux、macOSなど）：$XDG_CONFIG_HOME/black（XDG_CONFIG_HOME環境変数が設定されていない場合は~/.config/black）

これらはディレクトリではなく、TOMLファイル自体のパスであることに注意してください（つまり、pyproject.tomlという名前にはなりません）。ここで、~はホームディレクトリのパスを表します。Windowsでは、C:\\Users\\UserNameのようなパスになります。

--configを使用して、特定のファイルへのパスを明示的に指定することもできます。この場合、Blackは他のファイルを探しません。

--verboseオプションを付けて実行すると、ファイルが見つかり使用された場合にメッセージが表示されます。

blackdはpyproject.tomlの設定を使用しないことに注意してください。

設定形式¶

ファイル拡張子からわかるように、pyproject.tomlはTOMLファイルです。これは、さまざまなツール用のセクションを別々に含んでいます。Blackは[tool.black]セクションを使用します。オプションキーは、コマンドラインのオプションの長い名前と同じです。

TOMLでは、正規表現にはシングルクォートで囲まれた文字列を使用する必要があることに注意してください。これはPythonのr文字列に相当します。複数行の文字列は、Blackによって冗長な正規表現として扱われます。重要な空白文字を表すには[ ]を使用します。

pyproject.tomlの例

[tool.black]
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
# 'extend-exclude' excludes files or directories in addition to the defaults
extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# in the root of the project.
(
  ^/foo.py    # exclude a file named foo.py in the root of the project
  | .*_pb2.py  # exclude autogenerated Protocol Buffer files anywhere in the project
)
'''

検索階層¶

コマンドラインオプションには、--helpで確認できるデフォルト値があります。pyproject.tomlでこれらのデフォルト値を上書きできます。最後に、ユーザーがコマンドラインで指定したオプションは、両方の上位に優先されます。

Blackは、実行全体を通して常に1つのpyproject.tomlファイルのみを使用します。複数のファイルを探したり、ファイル階層の異なるレベルから設定を合成したりしません。

次のステップ¶

次のステップとしては、自動検出を設定して、すべてのファイルやディレクトリを手動で列挙する代わりにblack .だけで済むようにすることが良いでしょう。ファイルの収集と検出を参照して開始できます。

もう1つの良い選択肢は、お好みのエディターとの統合、またはソースバージョン管理のためのpre-commitの設定です。

基本事項¶

使用方法¶

セクションの無視¶

コマンドラインオプション¶

-h、--help¶

-c、--code¶

-l、--line-length¶

-t、--target-version¶

--pyi¶

--ipynb¶

--python-cell-magics¶

-x, --skip-source-first-line¶

-S, --skip-string-normalization¶

-C, --skip-magic-trailing-comma¶

--preview¶

--unstable¶

--enable-unstable-feature¶

--check¶

--diff¶

--color / --no-color¶

--line-ranges¶

--fast / --safe¶

--required-version¶

--exclude¶

--extend-exclude¶

--force-exclude¶

--stdin-filename¶

--include¶

-W、--workers¶

-q、--quiet¶

-v、--verbose¶

--version¶

--config¶