标签归档:code

Black-不折不扣的Python代码格式化程序

“你喜欢什么颜色都行。”

黑色是不折不扣的Python代码格式化程序。通过使用它,您同意放弃对手动格式化细节的控制。作为回报,黑色为您提供速度、决定论和从pycodestyle对格式化喋喋不休。你将为更重要的事情节省时间和精力。

不管您正在阅读的是什么项目,被涂黑的代码看起来都是一样的。格式在一段时间后会变得透明,您可以将注意力放在内容上

黑色通过产生尽可能小的差异,使代码审查速度更快

现在使用Black Playground看这场比赛PyCon 2019 talk了解更多信息


Read the documentation on ReadTheDocs!


安装和使用

安装

黑色可以通过运行以下命令来安装pip install black它需要运行Python 3.6.2+。如果还想格式化Python 2代码,请使用安装pip install black[python2]

如果你不能等最新的热度要从GitHub安装,请使用:

pip install git+git://github.com/psf/black

用法

要立即开始使用合理的默认值,请执行以下操作:

black {source_file_or_directory}

你可以跑黑色如果将其作为脚本运行不起作用,则将其作为程序包运行:

python -m black {source_file_or_directory}

有关更多信息,请参阅我们的文档:

注意:这是测试版产品

黑色已经是很久以前的事了successfully used许多项目,大大小小的。Black有一个全面的测试套件,具有高效的并行测试,以及我们自己的自动格式化和并行持续集成运行器。然而,黑色仍然是测试版。在一段时间内,情况可能会不稳定。这是由“Beta”Trove分类器以及版本号中的“b”明确表示的。这对你来说意味着在格式化程序变得稳定之前,您应该预期将来会更改一些格式这就是说,没有计划进行重大的风格改变,主要是对bug报告的响应

此外,作为减慢处理的安全措施,黑色将检查重新格式化的代码是否仍然生成与原始代码有效等效的有效AST(请参阅Pragmatism部分获取详细信息)。如果你感到自信,使用--fast

这个黑色代码样式

黑色是一个符合PEP8标准的固执己见的格式化程序。黑色就地重新格式化整个文件。样式配置选项是故意限制的,很少添加。它不考虑以前的格式(请参见Pragmatism(对于例外情况)

我们的文档涵盖了当前黑色代码样式,但也记录了对其的计划更改。它们都值得一看:

在提交问题之前,请参阅本文档。看起来像是窃听器的行为可能是故意的

实用主义

早期版本的黑色在某些方面曾经是专制主义的。他们模仿它的最初作者。这在当时是不错的,因为它使实现更简单,而且用户也不多。报道的边缘病例不多。作为一个成熟的工具,黑色确实对它本来持有的规则做出了一些例外

请在提交问题之前参考本文档,就像上面的文档一样。看起来像是窃听器的行为可能是故意的

配置

黑色控件读取其命令行选项的特定于项目的默认值。pyproject.toml文件。这对于指定自定义--include--exclude/--force-exclude/--extend-exclude项目的模式

您可以在我们的文档中找到更多详细信息:

如果您正在寻找更一般的配置文档,请执行以下操作:

PRO-TIP:如果您问自己“我需要配置什么吗?”答案是否定的。黑色都是关于合理的违约。应用这些缺省值将使您的代码与许多其他代码兼容黑色格式化项目

使用方

以下值得注意的开源项目值得信任黑色实施一致的代码样式:pytest、毒性、金字塔、Django通道、假设、attrs、SQLAlChemy、诗歌、Pypa应用程序(Warehouse、Bandersnatch、Pipenv、viralenv)、Pandas、Pillow、Every Datadog Agent Integration、Home Assistant、Zulip

以下组织使用黑色:Facebook,Dropbox,Mozilla,Quora,Duolingo

我们有没有错过什么人?让我们知道

推荐信

迈克·拜耳author of SQLAlchemy

在我整个编程生涯中,我想不出有哪一个工具能通过它的引入给我带来更大的生产力提升。我现在可以进行大约1%的按键重构,这是以前我们无法格式化代码时所需要的

尘土飞扬的菲利普斯writer

黑色固执己见,所以你不必

希内克·施拉瓦克creator of attrs,Twisted和CPython的核心开发者:

我想要的圣诞礼物就是一个不会让人讨厌的自动格式化程序!

卡尔·迈耶Django核心开发者:

至少名字是好的

肯尼思·赖茨(Kenneth Reitz),创建者requestspipenv

这极大地改进了我们代码的格式。万分感谢!

展现你的风格

使用项目自述文件中的徽章。md:

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

使用Readme.rst中的徽章:

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black

如下所示:

许可证

麻省理工学院

贡献

欢迎!很高兴看到你愿意把项目做得更好。您可以通过阅读以下内容开始:

您也可以查看投稿文档的睡觉或者与开发者对话:

更改日志

木头已经变得相当长了。它移到了自己的文件中

看见CHANGES

作者

现在的作者名单相当长,所以它在自己的档案里

看见AUTHORS.md

行为规范

所有参加这次活动的人黑色项目,特别是在问题跟踪器、拉取请求和社交媒体活动中,应该尊重他人,更普遍地遵循Python Community Code of Conduct

同时,幽默也受到鼓励。事实上,基本熟悉Monty Python的飞行马戏团是可以预期的。我们不是野蛮人

如果你真的需要打人耳光,边跳舞边和鱼做