文章目录
- 一、Black自动格式化工具
- 二、格式化行为的核心内容
-
- [1. 统一缩进和空格规则](#1. 统一缩进和空格规则)
- [2. 括号换行：一致的多行结构展开](#2. 括号换行：一致的多行结构展开)
- [3. 字符串风格统一](#3. 字符串风格统一)
- [4. 函数/类定义中的空行规则](#4. 函数/类定义中的空行规则)
- [5. import 排序（建议搭配 isort）](#5. import 排序（建议搭配 isort）)
- [6. 注释不动、换行优雅](#6. 注释不动、换行优雅)
- [7. 可配置项极少，强调"零配置"理念](#7. 可配置项极少，强调“零配置”理念)
- 三、安装
- 四、使用方式
-
- [（1）单文件 - 格式化：black example.py（修改原文件）](#（1）单文件 - 格式化：black example.py（修改原文件）)
- [（2）多文件 - 格式化：black .（修改原文件）](#（2）多文件 - 格式化：black .（修改原文件）)
- [（3）查看修改内容（支持单/多文件）：black --diff（不修改原文件）](#（3）查看修改内容（支持单/多文件）：black --diff（不修改原文件）)
- [（4）在VS Code中安装插件实时使用（推荐）](#（4）在VS Code中安装插件实时使用（推荐）)
✅ 一、自动执行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. 括号换行：一致的多行结构展开
在函数调用或定义参数较多、过长时，自动使用"垂直风格"展开括号内容：
python
# 原始写法
def foo(a, b, c, d): pass
# 格式化后
def foo(
a,
b,
c,
d,
):
pass这提升了 diff 稳定性，减少多人协作时"只改一行却整组变了"的问题。
3. 字符串风格统一
- 默认使用 双引号
" " - 除非包含嵌套双引号，才会用单引号
python
# 原始
s = 'Hello'
# 格式化后
s = "Hello"4. 函数/类定义中的空行规则
- 顶级函数或类定义之间留 2行
- 类中方法之间留 1行
5. import 排序（建议搭配 isort）
Black 本身只对 import 保持分组，但不负责排序顺序：
python
# Black会这样组织：
import os
import sys
import 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
👉 它会直接修改原文件（不会备份）。
python
import cv2
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()执行black D:\py\other\test.py后的运行结果如下：
python
import cv2
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()（2）多文件 - 格式化：black .（修改原文件）
你也可以一次性格式化整个项目文件夹：black .
其中 . 表示当前目录，它会递归查找所有 .py 文件进行格式化。
（3）查看修改内容（支持单/多文件）：black --diff（不修改原文件）
若希望一次检查多个文件，避免误改生产代码，推荐结合 Git 使用：black . --check
python
import cv2
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()执行black --diff D:\py\other\test.py后的运行结果如下：
python
(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.py
All done! ✨ 🍰 ✨
1 file would be reformatted.（4）在VS Code中安装插件实时使用（推荐）
打开VS Code设置中搜索Python Formatting Provider，设为black
允许保存时自动格式化：
python
// settings.json 配置
"editor.formatOnSave": true,
"python.formatting.provider": "black"这样每次按Ctrl+S保存时，Black就会自动帮你格式化代码。