五彩斑斓的 Black —— Python代码格式化工具

良好的 Python 代码应有良好的格式规范（不止于遵守 PEP 8 ），使用一个更强大更专业的代码格式化工具，来替代编辑器自带的「格式化代码」功能是有一定必要的，这还可以使团队成员即使在不同编辑器下工作也可以得到完全相同的风格。相比于目前社区中较为流行的 autopep8，其实还有一个更好的选择 —— Black 。

简介

“Any color you like.”

GItHub | 官方文档 | PyPI | 在线试用

Black 自称“零妥协代码格式化工具（The uncompromising code formatter）”。

截止到2021年9月，Black 已经在 GitHub 斩获 22.4k 个 Stars，由 Google 开发维护的 YAPF 为 12.1k ，而 autopep8 则只有 3.9k 。可以说 Black 是目前最广受好评的 Python 代码格式化工具。

安装

可以通过 pip 直接从 PyPI 下载安装：

pip install black

注意需要 Python 3.6.2 以上的版本。

如果想在 Jupyter Notebooks 中使用，则可以通过如下代码安装：

pip install black[jupyter]

如果急于试用最新版本，可以通过下面的命令从 GitHub 安装（不推荐）：

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

简单使用

作为脚本运行

black {source_file_or_directory}

作为 Python 包运行

如果将 Black 作为脚本运行不起作用，您可以尝试将其作为包运行：

python -m black {source_file_or_directory}

跳过字符串格式化

Black 会默认将字符串格式化为使用双引号包裹，但有些项目已经使用了单引号的规范且不应修改为双引号，就需要加上一个 -S / --skip-string-normalization 的选项。

black -S {source_file_or_directory}

集成到 IDE / 编辑器中

相比于每次都专门打开一个终端，手动使用命令行调用 Black 格式化代码，我们更希望能把 Black 集成到我们常用的 IDE / 编辑器中，不需要离开写代码的界面即可完成格式化操作。

在 Pycahrm 中使用

Black 官方文档中给出了在 Pycharm（或 IntelliJ IDEA）中配置使用 Black 的方法：

确认 Black 安装位置

在 macOS / Linux / BSD 上：

$ which black
/usr/local/bin/black  # 可能的位置

在 Windows 上：

$ where black
%LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # 可能的位置

如果是使用 Pycahrm 建立的虚拟环境，则直接使用 $PyInterpreterDirectory$/black 作为程序路径。

在 Pycharm 中添加外部工具

打开 文件 -> 设置 -> 工具 -> 外部工具

File -> Settings -> Tools -> External Tools

创建工具

• 名称：Black
• 描述：毫不妥协的 Python 代码格式化工具
• 程序：「上一小节得到的安装位置」
• 参数：$FilePath$
• 工作目录：$ProjectFileDir$

如果需要自定义其他选项，写在 $FilePath$ 前即可，比如代表「取消格式化字符串为双引号包裹”」的选项 -S：

使用

在已经打开的代码编辑界面（或项目文件树的某个目录上）鼠标右键，找到 External Tools -> Black，点击即可。

设置快捷键

还可以在 设置 -> 键盘映射 -> 外部工具 -> Black 上右键，打开编辑快捷键的菜单，添加键盘快捷键：

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-fMWGYbut-1633632340478)(https://oss.muzing.top/image/20210925225052.png)]

如果已经习惯了 Pycharm 默认的Ctrl + Alt + L 快捷键格式化代码，那么可以这样设置：

1. 在 主菜单 -> 代码 -> 重新格式化代码 中删去快捷键
2. 给 外部工具 -> External Tools -> Black 设置键盘快捷键Ctrl + Alt + L

保存文件时自动格式化（可选）

1. 确保已经安装了 File Watchers 插件

2. 进入 设置 -> 工具 -> File Watchers，点击 + 以添加一个新的 watcher：

   • Name: Black
   • File type: Python
   • Scope: Project Files
   • Program: 上一小节得到的安装位置
   • Arguments: $FilePath$
   • Output paths to refresh: $FilePath$
   • Working directory: $ProjectFileDir$

3. 在高级选型中：

   • 取消勾选 “Auto-save edited files to trigger the watcher”
   • 取消勾选 “Trigger the watcher on external changes”

在 VS code 中使用

VS code 官方文档介绍

安装 Python 插件

首先确保已经在 VS code 中安装了 Python 插件。如果没有安装，则在 VS code 中按下 Ctrl + P ，并输入如下命令：

ext install ms-python.python

或者直接在扩展商店中搜索 Python 并安装。

配置 Python 扩展

按下 Ctrl + , ，打开 VS code 设置

在「设置」中搜索 python formatting provider ，然后把默认的 autopep8 改为 black 即可。

保存文件时自动格式化代码（可选）

在「设置」界面搜索 format on save ，可以勾选打开保存时格式化文件的功能。

取消格式化为双引号包裹字符串（可选）

在「设置」界面的右上角打开 settings.json 配置文件

在配置文件中添加一行

"python.formatting.blackArgs": [
        "--skip-string-normalization"
    ]

注意每个人的 settings.json 配置文件都有所不同，行号不太一样，在文件末尾新建一行添加即可。

在 Vim 中使用

同样可以在 Black 官方文档中找到在 Vim 中使用 Black 官方插件的方法：https://black.readthedocs.io/en/stable/integrations/editors.html#vim

更多

Black 还可以集成到许多其他编辑器中。此外，官方文档还给出了集成至 GitHub Actions 中、集成至利用 pre-commit 工具实现的版本控制集成工作流中的方法，这样每次更新项目都会自动使用 Black 重新格式化代码了。

详见文档：https://black.readthedocs.io/en/stable/integrations/index.html

其他

在 README 中展示

如果你的项目使用了 Black 工具，可以在 README.md 中加入下面一行

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

这样就可以显示一个 shields 图标了：[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-vzMw0bQg-1633632340494)(https://img.shields.io/badge/code%20style-black-000000.svg)]

吃瓜：单引号？双引号！

关于字符串应该用单引号还是双引号包裹，Black 的开发组成员和一些用户有不同的意见。在早先的版本中，Black 强制使用双引号，且用户无法自行修改。于是他们足足在 Issue 里“吵”了一百多楼，各种引经据典，据理力争……终于开发组不得不妥协，勉为其难的给出了一个不格式化字符串引号的选项。

GitHub 原楼请戳

进阶使用

我还将相当一部分 Black 官方文档 进行了翻译，包含全部命令行选项及详解、通过文件配置、The Black code style 等：

[保留占位，已经发布至我的博客，稍后发布至CSDN]

转载声明

本文为我的博客同名文章的精简版，可以点击下面的链接，查看本文的最新更新：

五彩斑斓的 Black —— Python代码格式化工具

本文允许转载，转载必须注明：

• 作者：muzing
• 原文链接：https://muzing.top/posts/a29e4743