python black

## Black 是什么

Black 是一个 Python 代码格式化工具。说到格式化工具，很多人第一反应是“不就是个自动排版的嘛”，但 Black 的特别之处在于它把自己定位成“不妥协的代码格式化器”。什么意思呢？就像你写文章时有个严格的编辑，不是给你提建议说“这里可以改一下”，而是直接动手把你的句子重写一遍，而且风格统一得像是同一台打印机打出来的。

Black 的核心哲学是“可读性第一”，它认为代码的格式不应该由个人偏好决定，而应该由一套严格的规则来约束。这有点像交通规则：每个人都可以有自己的驾驶习惯，但红灯停绿灯行这种基本规则需要强制执行，这样才能保证整体交通的顺畅和可预测性。

Black 能做什么

Black 的核心能力其实很单一——格式化 Python 代码。但它的格式化方式相当彻底：

它会自动调整缩进，比如你写了个函数，参数列表超过行长度限制，Black 会自动把每个参数拆成单独一行。它还会处理括号的位置、运算符前后的空格、空行的数量等等。比如这段代码：

def calculate_something(first_param,second_param,third_param,fourth_param,fifth_param):
    result=first_param+second_param-third_param*fourth_param/fifth_param
    return result

Black 会把它格式化成：

def calculate_something(
    first_param,
    second_param,
    third_param,
    fourth_param,
    fifth_param,
):
    result = (
        first_param
        + second_param
        - third_param
        * fourth_param
        / fifth_param
    )
    return result

这种格式可能不是你习惯的风格，但它的优点是：不管谁写的代码，经过 Black 处理后看起来都像是同一个人写的。这对团队协作来说是个巨大的优势，再也不用在 code review 时为“这个逗号后面要不要加空格”这种问题争论了。

怎么使用 Black

Black 的安装很简单，用 pip 就行：

pip install black

基本用法也相当直接，在命令行里运行：

black your_file.py

这个命令会直接修改你的文件。如果你只是想预览效果，不想直接修改，加上 --check 参数：

black --check your_file.py

Black 还支持 --diff 参数，可以显示具体的修改内容，相当实用：

black --diff your_file.py

对于整个项目，你可以直接指定目录：

black ./

这会格式化当前目录下所有 Python 文件。不过要注意，Black 默认会跳过已经被格式化的文件，所以重复运行不会有什么开销。

最佳实践

在实际项目中使用 Black，有几个经验可以参考：

配置方面，Black 默认的行长度是 88 个字符。这个数字不是随便定的，它比常见的 80 字符宽一点，但又足够避免频繁换行。要是团队实在接受不了，可以通过项目配置文件修改。在项目根目录创建 pyproject.toml，写入：

[tool.black]
line-length = 100

不过建议别轻易改这个值，Black 的很多格式化决策都是基于这个行长度设计的，改了之后效果可能会打折扣。

集成到工作流中，最顺手的做法是把 Black 配置成代码提交前的自动检查。可以结合 pre-commit 钩子，在 .pre-commit-config.yaml 里加上：

repos:
  - repo: https://github.com/psf/black
    rev: 23.1.0
    hooks:
      - id: black

这样每次提交代码前都会自动格式化，确保仓库里的代码风格统一。

还有个实用的做法是在编辑器里配置保存时自动运行 Black。VS Code 的话，在设置里加上：

"editor.formatOnSave": true,
"python.formatting.provider": "black"

PyCharm 也可以通过 File Watcher 实现类似功能。这样写代码时完全不用操心格式，写完保存就自动整理好了。

和同类技术对比

Python 的代码格式化工具主要有几个：autopep8、yapf 和 Black。

autopep8 是三者中最早出现的，它的目标是让代码符合 PEP 8 规范。好处是改动最保守，基本只处理明显违反规范的地方，比如空格、缩进这些。但缺点也很明显：它对风格的统一程度有限，改完之后还是能看到不同人的书写习惯。

yapf 比 autopep8 激进一些，它借鉴了 Go 语言的 gofmt 设计思路，会更大胆地调整代码格式。但 yapf 提供了大量配置项，比如括号的放置方式、空行的策略等等。这虽然给开发者更多控制权，但也容易导致团队内部争论配置项该怎么设。

Black 在这两者之间找到了一个平衡点：它既像 yapf 那样彻底重排版面，又像 autopep8 那样几乎不需要配置。实际上 Black 只提供了几个可配置选项：行长度、字符串引号类型、是否跳过某些文件。这种“少即是多”的设计恰恰解决了团队协作中最头疼的问题——配置争议。

打个比方：autopep8 像个温和的校对员，只改明显的笔误；yapf 像个有自己风格的排版师，但你可以和他商量很多细节；Black 则像个独断的装修队，上来就说“客厅必须朝南，卧室必须 15 平米”，虽然你不一定喜欢它的每个决定，但省下了很多争吵的时间。

从实际使用体验来说，Black 的学习曲线几乎为零。刚接触时，看到它把一段好好的代码拆成多行可能会不太适应，但用上一周左右就会习惯。而且一旦习惯，再看没有经过 Black 格式化的代码，反而会觉得乱糟糟的。

对于新项目，建议从一开始就用 Black。对于老项目，可以先用 --check 看看会改动多少，如果改动量太大，可以考虑分模块逐步迁移。毕竟改变已有的代码风格总会有阵痛，但这阵痛是值得的。