Black自动格式化工具

在线文本对比

✅ 一、自动执行Python代码规范的常用工具

工具名称	功能类别	说明
Black	代码格式化工具	自动格式化Python代码，主张“无配置就是最好的配置”，风格一致性极强
isort	import排序	自动将import语句分组排序（标准库、第三方库、本地模块），保持整洁
flake8	代码风格检查	基于PEP8规范，检查命名、空格、缩进、未使用变量、重复定义、复杂度等
pylint	代码质量评估	提供评分机制并报告冗余/危险代码，适合用于静态代码分析和质量评估
mypy	静态类型检查	对标PEP 484，检查类型注解的正确性，适合大型项目构建类型安全
autopep8	自动PEP8修复	根据flake8风格检查自动修复，但不如Black统一、现代

✅ 二、IDE集成建议（VSCode等）
若使用 VSCode、PyCharm 等IDE，可集成以下工具：

功能	推荐插件	设置位置
自动格式化	Black Formatter	settings.json配置black为默认格式化器
风格检查	flake8	可通过插件提示下划线标出错误
import排序	isort	可结合保存时自动执行

一、Black自动格式化工具

Black 是 Python 社区广泛使用的自动格式化工具，可以一键帮你格式化代码，风格统一、无争议，开发者只需专注业务逻辑，不再纠结代码缩进、空格、换行风格等细节。

口号：The Uncompromising Code Formatter —— 不可协商的代码风格（所以不用做风格选择题）

二、格式化行为的核心内容

1. 统一缩进和空格规则

• 使用4个空格缩进
• 删除不必要的空格（如 if(x == 1) → if (x == 1)）
• , 号后自动添加空格（除非在函数参数中省略）
• 去除尾部空格
• 保证每个文件结尾 只有一个空行

2. 括号换行：一致的多行结构展开

在函数调用或定义参数较多、过长时，自动使用“垂直风格”展开括号内容：

# 原始写法
def foo(a, b, c, d): pass# 格式化后
def foo(a,b,c,d,
):pass

这提升了 diff 稳定性，减少多人协作时“只改一行却整组变了”的问题。

3. 字符串风格统一

• 默认使用 双引号" "
• 除非包含嵌套双引号，才会用单引号

# 原始
s = 'Hello'# 格式化后
s = "Hello"

4. 函数/类定义中的空行规则

• 顶级函数或类定义之间留 2行
• 类中方法之间留 1行

5. import 排序（建议搭配 isort）

Black 本身只对 import 保持分组，但不负责排序顺序：

# Black会这样组织：
import os
import sysimport numpy as np
import torch

⚠ 推荐 配合 isort 使用，处理完整排序逻辑。

6. 注释不动、换行优雅

• Black 不会修改注释内容
• 但会适当调整注释的位置以匹配格式化后的结构

7. 可配置项极少，强调“零配置”理念

Black 有意只保留极少的选项，例如：

三、安装

用pip直接安装：pip install black，需要 Python 3.9 及以上版本。

四、使用方式

（1）单文件 - 格式化：black example.py（修改原文件）

假设你有一个叫 example.py 的 Python 脚本，只需一行命令：black example.py
👉 它会直接修改原文件（不会备份）。

import cv2tif_path =     r"D:\py\other\stig_x_0.007.tif"  # 不可以有中文
img =      cv2.imread(tif_path, cv2.IMREAD_UNCHANGED)
if img is None:raise SystemExit(f"无法读取图像 '{tif_path}'")# 显示图片
cv2.    imshow("imgs", img)
cv2.    waitKey(0)
cv2.    destroyAllWindows()

执行black D:\py\other\test.py后的运行结果如下：

import cv2tif_path = r"D:\py\other\stig_x_0.007.tif"  # 不可以有中文
img = cv2.imread(tif_path, cv2.IMREAD_UNCHANGED)
if img is None:raise SystemExit(f"无法读取图像 '{tif_path}'")# 显示图片
cv2.imshow("imgs", img)
cv2.waitKey(0)
cv2.destroyAllWindows()

（2）多文件 - 格式化：black .（修改原文件）

你也可以一次性格式化整个项目文件夹：black .
其中 . 表示当前目录，它会递归查找所有 .py 文件进行格式化。

（3）查看修改内容（支持单/多文件）：black --diff（不修改原文件）

若希望一次检查多个文件，避免误改生产代码，推荐结合 Git 使用：black . --check

import cv2tif_path = r"D:\py\other\stig_x_0.007.tif"  # 不可以有中文
img = cv2.imread(tif_path, cv2.IMREAD_UNCHANGED)
if img is None:raise SystemExit(f"无法读取图像 '{tif_path}'")# 显示图片
cv2. imshow("imgs", img)
cv2.waitKey(0)
cv2.destroyAllWindows()

执行black --diff D:\py\other\test.py后的运行结果如下：

(py39) PS D:\py> black --diff D:\py\other\test.py
--- D:\py\other\test.py 2025-06-17 09:20:21.661186+00:00
+++ D:\py\other\test.py 2025-06-17 09:20:25.159215+00:00
@@ -1,11 +1,11 @@import cv2-tif_path =     r"D:\py\other\stig_x_0.007.tif"  # 不可以有中文
-img =      cv2.imread(tif_path, cv2.IMREAD_UNCHANGED)
+tif_path = r"D:\py\other\stig_x_0.007.tif"  # 不可以有中文
+img = cv2.imread(tif_path, cv2.IMREAD_UNCHANGED)if img is None:raise SystemExit(f"无法读取图像 '{tif_path}'")# 显示图片
-cv2.    imshow("imgs", img)
-cv2.    waitKey(0)
-cv2.    destroyAllWindows()
\ No newline at end of file
+cv2.imshow("imgs", img)
+cv2.waitKey(0)
+cv2.destroyAllWindows()
would reformat D:\py\other\test.pyAll done! ✨ 🍰 ✨
1 file would be reformatted.

（4）在VS Code中安装插件实时使用（推荐）

打开VS Code设置中搜索Python Formatting Provider，设为black
允许保存时自动格式化：

// settings.json 配置
"editor.formatOnSave": true,
"python.formatting.provider": "black"

这样每次按Ctrl+S保存时，Black就会自动帮你格式化代码。