black

项目概述

Black 是 Python 社区最流行的代码格式化器之一，以「毫不妥协」著称：风格选项刻意保持极少，格式化结果确定且全项目统一。它让你放弃对格式细节的控制，换回速度、确定性和免受风格告警打扰的开发体验。经 Black 格式化的代码在所有项目里观感一致，并生成最小化 diff 以加快代码评审。

格式交给 Black，精力还给代码本身。

主要功能

• 自动格式化：直接重排整个文件，风格统一无需讨论
• PEP 8 兼容：在 PEP 8 基础上给出确定的风格决策
• 最小 diff：格式化后产生尽可能小的差异，评审更聚焦
• 安全校验：默认校验格式化前后 AST 等价，避免改变语义
• pyproject 配置：支持通过 pyproject.toml 指定 include 与 exclude 等选项
• Notebook 支持：安装 black[jupyter] 可格式化 Jupyter Notebook
• 预提交钩子：常与 pre-commit 配合实现提交前自动格式化

适用人群

• Python 开发者
• 开源项目维护者
• 希望终结风格争论的团队
• 重视评审效率的技术负责人
• CI 流水线维护者

快速上手

1. 安装 Black

pip install black

2. 格式化文件或目录

black {source_file_or_directory}

3. 无 Python 环境的机器可从 GitHub Releases 下载独立可执行文件使用

4. 可选：在 pyproject.toml 中配置 include 与 exclude 模式

核心优势

• 风格零争论：选项极少，团队无需在风格上消耗时间
• 结果确定：同样的输入永远得到同样的输出
• 语义安全：默认校验 AST 等价，格式化不改行为
• 广泛验证：Django、SQLAlchemy、pandas 等大量项目长期使用

系统要求

注意事项

• 风格稳定：项目已进入稳定期，不再出现大规模风格变更
• 例外规则：部分场景存在 pragmatism 例外，提交 issue 前先查阅文档
• 速度取舍：AST 安全校验会略降速度，确有需要可用 --fast