Black：不妥协的 Python 代码格式化工具

Python 社区自己孵化的 Black，拿下了 41,528 Star，是 Python 代码格式化领域的实际标准。

Black 是 Python 软件基金会（PSF）维护的代码格式化工具，把自己定位为"不妥协的代码格式化器"。

"不妥协"的意思是，你放弃手动调整格式的控制权，换来速度、确定性，以及不再被 pycodestyle 唠叨格式问题的自由。

Black 格式化后的代码，不管在哪个项目里看起来都一样。格式变成透明之后，你的注意力会自然落到内容上。代码审查时的 diff 也会变小，review 效率更高。

安装和使用

安装一行命令搞定：

pip install black

需要 Python 3.10 以上。如果要格式化 Jupyter Notebook：

pip install "black[jupyter]"

使用也一样直接，指定文件或目录即可：

black {source_file_or_directory}

或者用模块方式运行：

python -m black {source_file_or_directory}

设计哲学

Black 遵循 PEP 8，但它有自己的态度。它格式化整个文件，不搞局部修补。风格配置项被刻意控制在很少的数量，团队不希望用户在格式细节上浪费时间。

早期的 Black 更绝对一些。随着用户变多、边界 case 报上来，现在的 Black 在一些地方做了务实的例外处理。

Black 格式化之后会检查重新格式化的代码是否产生等效的 AST。也就是说，格式化不会改变代码逻辑。如果对工具足够放心，加 --fast 可以跳过这个检查。

配置通过 pyproject.toml 读取。大部分用户不需要配任何东西。用 Black 团队的话说：「如果你在问自己’我需要配置什么吗’，答案是’不需要’。」

谁在用

开源项目里的用户名单很扎实：pytest、Django、SQLAlchemy、Poetry、pandas、Pillow、Twisted、Home Assistant 都在用 Black 保持代码风格一致。

企业端有 Dropbox、Lyft、Mozilla、Quora、Duolingo、Tesla。

SQLAlchemy 作者 Mike Bayer 的评价很直接：「我想不出整个编程生涯中还有哪个工具能比它带来更大的生产力提升。我现在做重构的按键次数大约是以前的 1%。」

attrs 作者 Hynek Schlawack 更简洁：「一个不烂的自动格式化器，是我圣诞愿望清单的全部。」

Django 核心开发者 Carl Meyer 则开玩笑说：「至少名字起得好。」

稳定性和演进

Black 已经进入稳定期，大的格式化变化不会频繁出现。风格上的改动主要来自 bug 修复和新 Python 语法的支持。项目有明确的稳定性策略文档，在提 issue 之前建议先读一下，很多看似是 bug 的行为其实是设计意图。

Black 还提供了一个小 badge 可以挂在项目 README 里，挂上就等于告诉协作者：别纠结格式了，Black 说了算。

写在最后

团队里的代码风格争论，消耗的时间和精力远超想象。Black 用一个简单直接的方式解决了这个问题：放弃选择。把格式交给工具，把精力留给真正重要的东西，对 Python 开发者来说，这买卖不亏。

Black 用一个简单直接的方式解决了这个问题：放弃选择。把格式交给工具，把精力留给真正重要的东西，对 Python 开发者来说，这买卖不亏。