Black自动格式化工具

文章目录

  • 一、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就会自动帮你格式化代码。

相关推荐
chao_78925 分钟前
二分查找篇——寻找旋转排序数组中的最小值【LeetCode】
python·线性代数·算法·leetcode·矩阵
金玉满堂@bj41 分钟前
PyCharm 中 Python 解释器的添加选项及作用
ide·python·pycharm
程序员三藏1 小时前
如何使用Pytest进行测试?
自动化测试·软件测试·python·测试工具·职场和发展·测试用例·pytest
随心点儿1 小时前
使用python 将多个docx文件合并为一个word
开发语言·python·多个word合并为一个
不学无术の码农1 小时前
《Effective Python》第十三章 测试与调试——使用 Mock 测试具有复杂依赖的代码
开发语言·python
sleepybear11132 小时前
在Ubuntu上从零开始编译并运行Home Assistant源码并集成HACS与小米开源的Ha Xiaomi Home
python·智能家居·小米·home assistant·米家·ha xiaomi home
纪伊路上盛名在2 小时前
(鱼书)深度学习入门1:python入门
人工智能·python·深度学习
夏末蝉未鸣012 小时前
python transformers笔记(TrainingArguments类)
python·自然语言处理·transformer
德育处主任Pro2 小时前
「py数据分析」04如何将 Python 爬取的数据保存为 CSV 文件
数据库·python·数据分析
咸鱼鲸2 小时前
【PyTorch】PyTorch中数据准备工作(AI生成)
人工智能·pytorch·python