Black：格式检查与项目配置

Black 负责统一 Python 源码格式。先用 --check --diff 查看结果，再决定是否写回；格式检查通过不代表程序逻辑正确。本文示例使用 Python 3.11、Black 26.5.1。

检查一个文件，再格式化

在已经选定的 Python 环境中安装工具。python -m black 可以明确使用这个解释器对应的 Black；裸命令 black 则取决于终端的 PATH。

python -m pip install "black==26.5.1"
python -m black --version

建立 example.py，内容如下。这段程序本身合法，只是格式尚未统一。

example.py

def total(values): return sum( values )
assert total([1,2,3])==6

在它所在的目录运行：

python -m black --check --diff example.py
python -m black example.py
python -m black --check example.py
python example.py

第一条只显示差异；本例尚未格式化，因此检查返回 1。第二条写回文件，第三条检查返回 0。第四条执行原有断言，确认示例仍得到 6。自动化任务应分别判断检查与程序测试的结果。

原记录中的 black path or file 表达的是“传入文件或目录”。or 并非 Black 的语法。例如对项目源码目录执行 python -m black src/，会按文件发现规则选择其中的 Python 文件。

在项目中保存配置

在项目根目录放置下面的 pyproject.toml。target-version 指定源码需要兼容的 Python 语法；它不会安装或切换 Python。

pyproject.toml

[tool.black]
line-length = 88
target-version = ["py311"]
required-version = "26.5.1"

python -m black --config pyproject.toml --check --diff example.py

Black 也会自动查找包含 [tool.black] 的项目配置。显式指定 --config 便于确认正在使用哪一份文件；一次运行只使用一份配置，不会把不同目录的配置层层合并。命令行选项可以覆盖配置值。详细规则见 Black 的用法与配置。

检查失败时如何处理

结果	意义	下一步
--check 返回 0	选中的源码无需再格式化	继续运行项目检查
格式检查完成，返回 1 并报告 would reformat	至少一个文件需要格式化	阅读差异，再执行写回命令
无法解析源码、内部错误或参数错误	工具没有正常完成格式检查	查看错误信息，先修复语法、版本或参数问题

不要把任何非零退出码都解释为“只差格式”。例如 required-version 与运行版本不符时，也可能返回 1，但格式检查尚未开始；应先阅读错误信息并核对版本。语法缺失的文件也不能靠格式化补全。团队应固定 Black 版本并一起升级；--preview 会启用未来样式，只有准备接受相应变化时再使用。

项目地址保留在 psf/black。安装与解释器的对应关系见 pip 的环境与配置。