black
24.10.0
「好きな色でいいよ。」
Black は、妥協のない Python コード フォーマッタです。これを使用すると、手動フォーマットの細部に対する制御を譲渡することに同意したことになります。その代わりに、 Black は速度、決定性、およびフォーマットに関するpycodestyle煩わしさからの自由を提供します。より重要な事柄のために時間と精神的エネルギーを節約できます。
黒く塗りつぶされたコードは、読んでいるプロジェクトに関係なく同じように見えます。しばらくすると書式設定が透明になり、コンテンツに集中できるようになります。
黒を使用すると、できる限り最小の差分が生成されるため、コード レビューが高速になります。
Black Playground を使用して今すぐ試してください。詳細については、PyCon 2019 の講演をご覧ください。
ReadTheDocs でドキュメントを読んでください。
Black は、 pip install black実行することでインストールできます。実行するには Python 3.9 以降が必要です。 Jupyter Notebook をフォーマットしたい場合は、 pip install "black[jupyter]"でインストールします。
最新の話題を待つことができず、GitHub からインストールしたい場合は、次を使用します。
pip install git+https://github.com/psf/black
適切なデフォルトを使用してすぐに開始するには:
black {source_file_or_directory}Black をスクリプトとして実行できない場合は、パッケージとして実行できます。
python -m black {source_file_or_directory}詳細については、次のドキュメントを参照してください。
黒はすでに大小を問わず多くのプロジェクトでうまく使用されています。 Blackには、効率的な並列テスト、独自の自動フォーマットおよび並列継続的インテグレーション ランナーを備えた包括的なテスト スイートがあります。現在は安定しているため、将来的に大きな書式変更が行われることは期待できません。文体の変更は主にバグレポートへの対応と新しい Python 構文のサポートになります。詳細については、「ブラック コード スタイル」を参照してください。
また、処理速度を低下させる安全対策として、 Black は再フォーマットされたコードが元のコードと実質的に同等の有効な AST を生成しているかどうかをチェックします (詳細については「プラグマティズム」セクションを参照)。自信がある場合は、 --fast使用してください。
Black は、PEP 8 準拠の独自のフォーマッタです。黒はファイル全体を所定の位置に再フォーマットします。スタイル設定オプションは意図的に制限されており、追加されることはほとんどありません。以前の書式設定は考慮されません (例外についてはプラグマティズムを参照してください)。
私たちのドキュメントでは現在のブラックコード スタイルについて説明していますが、それに対する計画された変更もドキュメント化されています。どちらも一見の価値があります。
ブラックコード スタイルへの変更は、安定性ポリシーによって拘束されます。
問題を送信する前にこのドキュメントを参照してください。バグのように見えるものは、意図された動作である可能性があります。
Blackの初期のバージョンは、ある点で絶対主義的でした。彼らはその最初の作者の名前をとりました。実装が簡単になり、とにかくユーザーが多くなかったので、これは当時は問題ありませんでした。エッジケースはあまり報告されませんでした。成熟したツールとして、 Black はそれ以外の場合に適用されるルールにいくつかの例外を設けています。
上記のドキュメントと同様に、問題を送信する前にこのドキュメントを参照してください。バグのように見えるものは、意図された動作である可能性があります。
Black は、コマンド ライン オプションのプロジェクト固有のデフォルト値をpyproject.tomlファイルから読み取ることができます。これは、プロジェクトのカスタム--includeおよび--exclude / --force-exclude / --extend-excludeパターンを指定する場合に特に便利です。
詳細については、次のドキュメントを参照してください。
より一般的な構成ドキュメントをお探しの場合は、次のようにします。
プロのヒント: 「何か設定する必要があるか?」という疑問がある場合は、答えは「いいえ」です。黒はすべて賢明なデフォルトです。これらのデフォルトを適用すると、コードが他の多くのBlack形式のプロジェクトに準拠するようになります。
次の注目すべきオープンソース プロジェクトは、一貫したコード スタイルを強制することでBlack を信頼しています: pytest、tox、Pyramid、Django、Django Channels、Hypothesis、attrs、SQLAlchemy、Poetry、PyPA アプリケーション (Warehouse、Bandersnatch、Pipenv、virtualenv)、pandas、Pillow 、Twisted、LocalStack、すべての Datadog Agent 統合、Home Assistant、Zulip、Kedro、 OpenOA、FLORIS、ORBIT、WOMBAT など。
次の組織はBlack を使用しています: Facebook、Dropbox、KeepTruckin、Lyft、Mozilla、Quora、Duolingo、QuantumBlack、Tesla、Archer Aviation。
誰か欠けている人はいませんか？お知らせください。
SQLAlchemyの著者であるMike Bayer氏:
私のプログラミング キャリア全体の中で、導入によってこれほど生産性が向上したツールは 1 つもありません。コード自体をフォーマットする方法がなかった以前に比べて、キーストロークの約 1% でリファクタリングを実行できるようになりました。
ダスティ・フィリップス、ライター：
黒人は自分の意見を持っているので、そうする必要はありません。
Hynek Schlawack氏、 attrsの作成者、Twisted と CPython のコア開発者:
クリスマスに欲しいのは、つまらない自動フォーマッタだけです。
Carl Meyer 氏、Django コア開発者:
少なくとも名前は良いです。
Kenneth Reitz 氏、 requestsとpipenvの作成者:
これにより、コードのフォーマットが大幅に改善されます。ありがとう！
プロジェクトの README.md でバッジを使用します。
[ ![ Code style: black ] ( https://img.shields.io/badge/code%20style-black-000000.svg )] ( https://github.com/psf/black )README.rst のバッジを使用する:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
次のようになります。
マサチューセッツ工科大学
いらっしゃいませ！プロジェクトをより良くすることに意欲的であることを嬉しく思います。これを読んで始めることができます。
残りの寄稿ドキュメントを参照したり、開発者と話したりすることもできます。
ログがかなり長くなってしまいました。独自のファイルに移動しました。
「変更」を参照してください。
現在、著者リストは非常に長いため、独自のファイルに保存されています。
AUTHORS.md を参照してください。
Blackプロジェクトに参加する全員、特に問題トラッカー、プル リクエスト、ソーシャル メディア活動に参加する人は全員、他の人を敬意を持って扱い、より一般的には Python コミュニティ行動規範に明記されているガイドラインに従うことが期待されます。
同時にユーモアも奨励されます。実際、モンティ・パイソンのフライング・サーカスについての基本的な知識は必要です。私たちは野蛮人ではありません。
そして、本当に誰かを平手打ちする必要がある場合は、踊りながら魚を使ってください。
