Black 是什么
Black 是一个几乎不给选项的 Python 格式化器：它把代码统一成一种风格，默认行宽 88 字符，用自动化结束风格争论。选项少是刻意设计——可调项目越少，团队越没有可争的余地。配置通常写在 pyproject.toml 的 [tool.black] 段里，CI 里用只检查不修改的模式做门禁。
基本信息
| 默认行宽 | 88 字符（与 PEP 8 的 79 不同） |
|---|---|
| 定位 | 统一格式、减少风格讨论，不检查语义问题 |
| 配置位置 | pyproject.toml 的 [tool.black] 段 |
| 常见选项 | line-length、target-version、skip-string-normalization |
常用命令
常用命令
black . # 就地格式化当前项目
black --check . # 只检查不修改，适合放在 CI
black --diff src/ # 先看将要修改的差异
black --line-length 100 . # 覆盖默认行宽落地要点
- 本地格式化、CI 只检查：避免每次提交都被 CI 打回重新排版。
- 首次全库格式化单独提交：让它成为一个无行为变化的机械改动，便于评审与跳过二分。
- 与 pre-commit 之类的提交钩子配合：格式化在提交前完成，不进评审视野。
- 忽略路径写进配置（生成代码、第三方 vendored 目录），避免反复产生噪声。
- 版本固定在依赖里：不同版本的格式化结果可能有细微差异，会导致 CI 与本地结论不一致。
与相邻工具的分工
| 工具 | 负责什么 |
|---|---|
| Black | 格式：缩进、换行、引号、空行 |
| Ruff / flake8 | 语义与潜在缺陷：未使用变量、可疑写法 |
| isort / Ruff 的导入规则 | 导入排序与分组 |
| mypy | 类型层面的静态检查 |
magic trailing comma 是少数可用的控制手段：在多行结构末尾留一个逗号，会强制格式化器展开成多行。
格式类工具同库不要重复启用：两个格式化器互相覆盖，diff 会持续抖动。
CI 与本地版本不一致时会出现「本地已格式化、CI 仍报错」：把格式化器版本写进依赖文件可避免这类扯皮。
容易被忽略的点
- 字符串引号规范化：默认会统一引号风格，若项目依赖原文，需要用选项或注释单独处理。
- 长表达式的换行策略：格式化器按自己的规则拆行，阅读不理想时改用临时变量往往是更好的解法。
- 笔记本与脚本文件：配置文件里明确排除不需要格式化的路径，避免改动生成内容。