一键格式化Python代码的黑魔法-black使用教程

介绍

black的特点

安装&配置

注意：后续技术分享，第一时间更新，以及更多更及时的技术资讯和学习技术资料，将在公众号CTO Plus发布，请关注公众号：CTO Plus

在Python编程领域，代码的可读性和规范性是非常重要的，因为良好的代码能够提高团队合作的效率，减少维护成本，并且有利于代码的持续集成和部署。为了保持代码的一致性和规范性，Python社区开发了许多工具和规范，其中一个非常知名的工具就是black。

black是一款受欢迎的自动化的Python代码格式化工具，它可以帮助开发者自动格式化Python代码，使之符合PEP 8规范。它能够根据一系列的规则自动调整代码的格式，从而使代码更加整洁、易读和一致。这款工具在我的产品开发中经常使用。

它的目标是强制性地使用PEP 8（Python编码风格指南）的规范，并且不需要我们进行任何人工干预。black使用了一种称为"uncompromising code formatter"的策略，即自动格式化代码而无需考虑任何个人偏好或者项目风格。

本篇文章《Python代码扫描：一键格式化Python代码的黑魔法-black使用教程》属于【Python代码规范与扫描】系列内容的第十篇，前面九篇可以根据自己情况自行查阅，同时欢迎公众号CTO Plus后续的文章：

代码规范与静态扫描系列内容：

介绍

Python3 black工具是一个强大的自动化代码格式化工具，它可以提高代码的可读性和规范性，减少团队协作的难度。通过自动格式化代码，使用黑色的代码风格，我们可以保持代码的一致性，提高团队协作效率，提高项目的可维护性。遵循最佳实践，并与团队成员进行良好的沟通和协商，将black集成到我们的日常开发流程中，将会给我们带来更好的开发体验和代码质量。

Black 在代码检查工具当中算是比较新的一个。它与 Autopep8 和 Yapf 类似，但限制较多，没有太多的自定义选项。这样的好处是不需要去决定使用怎么样的代码风格，让Black来做决定就好。

Black依赖于Python 3.6+，但它可以格式化用Python 2编写的代码。

black的特点

black可以轻松地集成到开发工作流程中，具有以下特点和优点：

black的特点包括自动化、一致性和简洁性，它可以减少代码审查和讨论的时间，提高团队的协作效率。

1. 自动化格式化：black会自动检测代码中的语法、缩进、空行、换行等问题，并根据PEP 8规范进行调整。这减少了我们手动格式化代码的工作量，并确保代码的一致性和可读性。

2. black配置选项很少甚至不需要配置：black的设计理念是使得所有的代码格式都是相同的，因此没有任何配置选项。这样一来，团队中的每个我们都可以使用相同的黑色代码风格，减少了因个人偏好而产生的代码格式不一致的问题，避免因为配置选项太多反而导致格式规范不一致。

3. 容易集成：black可以很容易地与其他开发工具集成，比如编辑器、IDE、代码库等。许多流行的代码编辑器和IDE（如VS Code、PyCharm、Sublime Text）都提供了black的插件或者集成，让我们能够在保存代码时自动使用black进行格式化。

4. 扩展性：black支持许多自定义选项和忽略规则，以满足不同项目的需求。我们可以通过制定特定的选项，调整black的行为，以适应项目的特定要求。

5. 强制使用团队规范：black确保了整个团队使用相同的代码风格，避免了团队成员之间的代码格式之争。这对于维持高质量的代码库和提高团队协作非常重要。

安装&配置

可以通过以下命令使用pip安装Black，执行：

pip install black

如果你使用conda作为包管理器，可以使用以下命令安装Black：

conda install -c conda-forge black

安装完之后，即可在Scripts目录下看到black.exe的可执行文件

Pycharm中配置black

其他配置选项可以参考官方文档，关于在IDE PyCharm中配置可以参考前面Ruff和pylint的使用配置。如下即为我的配置选项

配置完后，即可在外部工具中使用black

接下来分享下我对black的使用实践

black的使用及最佳实践

在使用Black进行Python代码格式化时，为了获得最佳效果和体验，可以考虑以下最佳实践：

1. 在项目中使用版本控制：在项目中使用版本控制（如Git）可以帮助我们更好地管理代码，并保留历史记录。在使用black之前，确保我们的代码已经提交到版本控制仓库中，并创建一个新的分支以进行格式化。

2. 预览和比对更改，关注格式化结果：在运行black之前，建议我们先预览即将发生的更改。black提供了一个`--diff`选项，可以显示要更改的每个文件的差异。这样可以更好地了解black将如何更改代码，并确认更改是否符合预期。因为虽然Black可以自动格式化代码，但有时也可能会产生不符合预期的结果。因此，在执行格式化操作后，建议仔细检查格式化的结果，确保代码的可读性和可维护性没有受到影响。

3. 进行批量格式化：black可以批量格式化整个项目的代码。可以使用`black .`命令来格式化当前目录和子目录下的所有Python文件。请注意，这将直接更新文件的内容，请确保在运行之前已经备份了我们的代码。

4. 配置编辑器插件：大多数流行的编辑器（如VS Code、PyCharm等）和IDE都提供了black的插件或者集成。安装和配置适当的插件，可以在保存代码时自动运行black进行格式化，并及时给出反馈，提高代码质量。

5. 遵循团队规范：black是一种团队规范的工具，所以一定要在项目或团队中确立black的使用规则，包括使用何种选项和规则，并与团队成员共享。

6. 结合lint工具：最后一点，Black还可以与其他lint工具（如flake8、pylint等）结合使用，进一步提高代码的质量。lint工具可以帮助检查代码中的潜在问题，并与Black一起使用，可以更好地保证代码的可读性和可维护性。

命令行参数

此处我总结下Black工具常用的一些命令行参数，其他的可以参考官方文档：

--line-length=<length>：设置每行的最大字符数，默认为88。

--skip-string-normalization：跳过对字符串的规范化处理。

--include=<patterns>：设置要包含的文件或目录模式。

--exclude=<patterns>：设置要排除的文件或目录模式。

对指定的目录或文件进行扫描

执行 black path/to/dir 或 black path/to/module.py 就可以使用 Black 优化代码。

格式化单个文件

可以使用以下命令对单个Python文件进行格式化：

black /path/to/file.py

在PyCharm中对单个文件进行扫描

这将直接修改文件中的代码，使之符合PEP 8规范。

格式化整个目录

可以使用以下命令对整个目录下的所有Python文件进行格式化：

black /path/to/directory

PyCharm中对整个项目工程进行扫描

Black将递归地遍历目录，并对所有Python文件进行格式化。

格式化代码片段

black还可以使用以下命令对代码片段进行格式化：

black -l 79 -

然后输入要格式化的代码片段，并按Ctrl + D结束输入。

最后

Black是一款受欢迎的Python代码格式化工具，它可以帮助开发者自动格式化Python代码，使之符合PEP 8规范。通过使用Black，开发者可以减少代码审查和讨论的时间，提高团队的协作效率。在使用Black时，可以结合版本控制、关注格式化结果、配合编辑器插件和结合lint工具等最佳实践，进一步提高代码的质量和可维护性。让我们一起使用Black，让Python代码更加规范和美观！