> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/psf/black) · [上游 README](https://github.com/psf/black/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
[](https://black.readthedocs.io/en/stable/)
毫不妥协的代码格式化工具
> “随你喜欢什么颜色。”
_Black_ 是一款毫不妥协的 Python 代码格式化工具。使用它即表示你同意将手工格式化的琐碎细节交由它处理。作为回报，_Black_ 为你带来速度、确定性，以及不再被 `pycodestyle` 唠叨格式的自由。你将节省时间和精力，投入到更重要的事情上。
格式化后的代码无论你在阅读哪个项目，看起来都一样。久而久之，格式化会变得透明，你可以专注于内容本身。
_Black_ 通过生成尽可能小的 diff，让代码审查更快。
观看 [PyCon 2019 演讲](https://youtu.be/esZLCuWs_2Y) 了解更多。
---
**[在 ReadTheDocs 上阅读文档！](https://black.readthedocs.io/en/stable)**
---
## 安装与使用
### 安装
_Black_ 可通过运行 `pip install black` 安装。运行需要 Python 3.10+。若要格式化 Jupyter Notebook，请使用 `pip install "black[jupyter]"` 安装。
若不想安装 Python 就想运行 _Black_，可从 [最新 GitHub 发布版本](https://github.com/psf/black/releases/latest). 下载 PyInstaller 构建的独立可执行文件之一。
### 用法
若要立即以合理的默认配置开始使用：
```sh
black {source_file_or_directory}
```
若以脚本方式运行无效，可将 _Black_ 作为包运行：
```sh
python -m black {source_file_or_directory}
```
更多信息请参阅我们的文档：
- [用法与配置](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
_Black_ 已被众多大小项目 [成功采用](https://github.com/psf/black#used-by)。_Black_ 拥有全面的测试套件，包含高效的并行测试，以及自有的自动格式化与并行持续集成（Continuous Integration）运行器。既然我们已趋于稳定，未来你不应再期待大规模格式变更。风格上的变化将主要针对 bug 报告和新 Python 语法支持。更多信息请参阅 [The Black Code Style](https://black.readthedocs.io/en/stable/the_black_code_style/index.html).
此外，作为一项会减慢处理速度的安全措施，_Black_ 会检查重新格式化后的代码仍能生成与原始代码在语义上等价的有效 AST（详见 [Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting) 一节）。若你很有把握，可使用 `--fast`。
## _Black_ 代码风格
_Black_ 是一款符合 PEP 8 的 opinionated（有主见）格式化工具。_Black_ 会就地重新格式化整个文件。风格配置选项被刻意限制，很少新增。它不会考虑先前的格式化（例外见 [Pragmatism](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)）。
我们的文档涵盖当前 _Black_ 代码风格，也记录了计划中的变更。两者都值得一看：
- [_Black_ 代码风格：当前风格](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html)
- [_Black_ 代码风格：未来风格](https://black.readthedocs.io/en/stable/the_black_code_style/future_style.html)
_Black_ 代码风格的变更受稳定性政策（Stability Policy）约束：
- [_Black_ 代码风格：稳定性政策](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy)
提交 issue 前请先查阅本文档。看似 bug 的行为可能是预期行为。
### 实用主义（Pragmatism）
_Black_ 早期版本在某些方面曾是绝对主义者，沿袭了其最初作者的风格。这在当时并无大碍，因为实现更简单，而且用户也不多，报告的边界情况很少。作为成熟工具，_Black_ 会对它一贯坚持的规则做出一些例外。
- [_Black_ 代码风格：实用主义](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism)
提交 issue 前请先查阅本文档，与上文文档一样。看似 bug 的行为可能是预期行为。
## 配置
_Black_ 可从 `pyproject.toml` 文件读取项目特定的命令行选项默认值。这对于为项目指定自定义 `--include` 以及 `--exclude`/`--force-exclude`/`--extend-exclude` 模式尤其有用。
更多细节请参阅我们的文档：
- [基础：通过文件配置](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file)
若你需要更通用的配置文档：
- [用法与配置](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html)
**专业提示**：若你在想「我需要配置什么吗？」答案是「不需要」。_Black_ 的核心就是合理默认。应用这些默认即可让你的代码与许多其他 _Black_ 格式化项目保持一致。
## 使用者
以下知名开源项目信任 _Black_ 来强制执行一致的代码风格：pytest、tox、Pyramid、Django、Django Channels、Hypothesis、attrs、SQLAlchemy、Poetry、PyPA 应用（Warehouse、Bandersnatch、Pipenv、virtualenv）、pandas、Pillow、Twisted、LocalStack、所有 Datadog Agent Integration、Home Assistant、Zulip、Kedro、OpenOA、FLORIS、ORBIT、WOMBAT，以及更多。
以下组织使用 _Black_：Dropbox、KeepTruckin、Lyft、Mozilla、Quora、Duolingo、QuantumBlack、Tesla、Archer Aviation。
有遗漏吗？请告知我们。
## 用户评价
**Mike Bayer**，[`SQLAlchemy`](https://www.sqlalchemy.org/): 的创建者：
> 回想我整个编程生涯，我想不出还有哪一款工具，仅凭引入就给我带来了如此巨大的生产力提升。如今我们做重构，大约只需过去没有自动格式化时 1% 的按键量。
**Dusty Phillips**，[作家](https://www.amazon.com/stores/Dusty-Phillips/author/B00HSYG5BO):：
> _Black_ 替你做了主见选择，你就不必再纠结。
**Hynek Schlawack**，[`attrs`](https://www.attrs.org/), 的创建者，Twisted 与 CPython 核心开发者：
> 我圣诞节唯一想要的，就是一款不烂的垃圾自动格式化工具！
**Carl Meyer**，[Django](https://www.djangoproject.com/) 核心开发者：
> 至少名字起得好。
**Kenneth Reitz**，[`requests`](https://requests.readthedocs.io/en/stable/) 与 [pipenv](https://pipenv.pypa.io/en/stable/): 的创建者：
> 这极大地改善了我们代码的格式。非常感谢！
## 展示你的风格
在你的项目 README.md 中使用徽章：
```md
[](https://github.com/psf/black)
```
在 README.rst 中使用徽章：
```rst
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
```
效果如下：
[](https://github.com/psf/black)
## 许可证
MIT
## 贡献
欢迎！很高兴看到你愿意让项目变得更好。你可以从阅读以下内容开始：
- [Contributing: The basics](https://black.readthedocs.io/en/latest/contributing/the_basics.html)
你也可以查看其余贡献文档，或与开发者交流：
- [Contributing documentation](https://black.readthedocs.io/en/latest/contributing/index.html)
- [Chat on Discord](https://discord.gg/RtVdv86PrH)
## 更新日志
日志已经变得相当长了，因此已移至单独的文件。
参见 [CHANGES](https://black.readthedocs.io/en/latest/change_log.html).
## 作者
作者名单如今已相当长，因此它存放在单独的文件中。
参见 [AUTHORS.md](./AUTHORS.md)
## 行为准则
参与 _Black_ 项目的每个人，尤其是在 issue tracker、pull requests 和社交媒体活动中，都应以尊重的态度对待他人，并更普遍地遵循
[Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
中所述的准则。
同时，我们鼓励幽默。事实上，我们期望大家基本熟悉 Monty Python's Flying Circus（《巨蟒剧团》）。我们不是野蛮人。
而如果你 _真的_ 需要扇某人耳光，那就一边跳舞一边用鱼来打。