psf/black

[](https://black.readthedocs.io/en/stable/)

坚定不移的代码格式化工具

_Black_ 是一个坚定不移的 Python 代码格式化工具。通过使用它，你同意放弃 手动格式化的细节控制。作为回报，_Black_ 给你速度、确定性和摆脱 `pycodestyle` 格式化唠叨的自由。你可以节省时间和精神能量，用于更重要的事情。 格式化后的代码在阅读不同项目时看起来都一样。经过一段时间后，格式化变得透明， 你可以专注于内容。 _Black_ 通过产生尽可能小的差异来加快代码审查的速度。 观看 [PyCon 2019 演讲](https://youtu.be/esZLCuWs_2Y) 了解更多信息。 **[在 ReadTheDocs 上阅读文档！](https://black.readthedocs.io/en/stable)** ## 安装和使用 ### 安装 通过运行 `pip install black` 可以安装 _Black_。它需要 Python 3.10+ 才能运行。 如果你想格式化 Jupyter Notebooks，请使用 `pip install "black[jupyter]"` 安装。 ### 使用 要立即开始使用合理的默认值： ``` black {source_file_or_directory} ``` 如果你以脚本方式运行 _Black_ 不起作用，你可以将其作为包运行： ``` python -m black {source_file_or_directory} ``` 更多信息请参阅我们的文档： - [使用和配置](https://black.readthedocs.io/en/stable/usage_and_configuration/index.html) 许多项目，从小到大，都成功地 [使用](https://github.com/psf/black#used-by) _Black_ 来强制执行一致的代码风格。 _Black_ 有一个全面的测试套件，包括高效的并行测试，以及我们自己的自动格式化和并行持续集成运行器。 现在我们已经变得稳定，你未来不应该期望有大的格式化变化。 风格变化将主要是对错误报告的响应和对新 Python 语法的支持。 有关更多信息，请参阅 [Black 代码风格](https://black.readthedocs.io/en/stable/the_black_code_style/index.html). 此外，作为一项安全措施，_Black_ 将检查格式化后的代码是否仍然产生一个有效的 AST， 该 AST 有效地等同于原始代码（有关详细信息，请参阅 [实用主义](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#ast-before-and-after-formatting) 部分）。如果你很有信心，可以使用 `--fast`。 ## _Black_ 代码风格 _Black_ 是一个符合 PEP 8 观点的格式化工具。_Black_ 在原位重新格式化整个文件。 风格配置选项故意有限，很少添加。它不考虑之前的格式化（有关例外，请参阅 [实用主义](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_ 代码风格的变化受稳定性政策的约束： - [Black 代码风格：稳定性政策](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy) 在提交问题之前，请参阅此文档。看似错误的行为可能是预期行为。 ### 实用主义 早期版本的 _Black_ 在某些方面是绝对主义的。它遵循其初始作者的思路。 在当时，这很合适，因为它使实现更简单，而且用户并不多。没有报告太多边缘情况。 作为一个成熟的工具，_Black_ 对其通常坚持的规则做出了一些例外。 - [Black 代码风格：实用主义](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#pragmatism) 在提交问题之前，请参阅此文档，就像上面的文档一样。看似错误的行为可能是预期行为。 ## 配置 _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 集成、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/): **Dusty Phillips**， [作家](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips): **Hynek Schlawack**，[`attrs` 的创建者]，Twisted 和 CPython 的核心开发者: **Carl Meyer**，[Django 的核心开发者]: **Kenneth Reitz**，[`requests` 和 [`pipenv` 的创建者](https://readthedocs.org/projects/pipenv/): ## 展示你的风格 在你的项目的 README.md 中使用徽章： ``` [](https://github.com/psf/black) ``` 在 README.rst 中使用徽章： ``` .. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black ``` 看起来像这样： [](https://github.com/psf/black) ## 许可证 MIT ## 贡献 欢迎！很高兴看到你愿意让这个项目变得更好。你可以通过阅读以下内容开始： - [贡献：基础知识](https://black.readthedocs.io/en/latest/contributing/the_basics.html) 你还可以查看其他贡献文档或与开发者交谈： - [贡献文档](https://black.readthedocs.io/en/latest/contributing/index.html) - [在 Discord 上聊天](https://discord.gg/RtVdv86PrH) ## 变更日志 日志已经相当长。它已经移动到自己的文件中。 查看 [CHANGES](https://black.readthedocs.io/en/latest/change_log.html). ## 作者 作者名单相当长，所以它住在自己的文件中。 查看 [AUTHORS.md](./AUTHORS.md) ## 行为准则 参与 _Black_ 项目、特别是问题跟踪器、拉取请求和社交媒体活动的人， 都应尊重他人，并更普遍地遵循 [Python 社区行为准则](https://www.python.org/psf/codeofconduct/) 中阐述的指南。 同时，鼓励幽默。事实上，对 Monty Python 的《蒙提·派森飞行马戏团》的基本熟悉是预期的。 我们不是野蛮人。 如果你 _真的_ 需要打某人，请在跳舞时用鱼打。

标签：conda, DNS解析, PyPI, Python, 下载量, 代码一致性, 代码可读性, 代码审查, 代码格式化, 代码维护, 代码规范, 代码风格, 开源框架, 开源项目, 持续集成, 文档, 无后门, 许可证, 逆向工具