Python 代码格式化

工具简介

Python 代码格式化工具会把代码整理成广泛使用的 Black 风格：统一的缩进、运算符两边的空格、双引号、顶层定义之间空两行，过长的行在合适的位置换行。

底层运行的是 Ruff 的格式化程序。Ruff 是用 Rust 编写的高速 Python 代码检查和格式化工具，这里把它编译成了 WebAssembly。Ruff 的输出和 Black 几乎逐行一致，所以在这里格式化过的代码，提交时不会再被项目的 pre-commit 钩子改动。

使用方法

1. 粘贴 Python 代码，或打开一个 .py 文件。
2. 输入的同时，右侧就会显示格式化后的代码。
3. 如果项目使用不同的风格，可以调整选项：
   • 缩进：4 个空格是 PEP 8 的规定，也是默认值；也可以选 2 个空格或制表符。
   • 每行宽度：88 是 Black 的默认值，79 是 PEP 8 的上限，100 或 120 适合宽屏。
   • 引号：双引号、单引号，或者保持每个字符串原来的引号。
   • 尾随逗号时保持展开：以逗号结尾的集合保持每行一项。
4. 复制或下载结果。

代码无法解析时，错误信息会指出解析器停下的位置，例如第 4 行的 Expected `,`, found `=` ，点击即可跳到那一行。

示例

示例是一个写得很随意的小模块：import 挤在一行里没有空格，数据类的冒号前多了空格，方法用两个空格缩进，if 语句写在一行里。格式化之后，所有代码块都改成 4 个空格缩进，if 的语句体换到下一行，运算符两边补上空格，单引号换成双引号，类和函数之间加上空行。原本以逗号结尾的列表被展开，每个字典占一行。

格式化不会做的事

格式化只调整排版。它不会排序 import、删除没用到的变量，也不会重命名任何东西，这些是代码检查工具的工作（可以用 ruff check --fix）。注释和文档字符串都会保留；遇到无法解析的代码，格式化程序会直接报错，而不是猜测着修改。

小技巧

• 把每行宽度设成和项目 pyproject.toml 里一样的值，结果就能和 CI 保持一致。
• 在提问或代码评审里贴代码之前先格式化一下，阅读起来会轻松很多。
• 从 Notebook 或聊天记录里复制来的代码如果混用了制表符和空格，格式化一次就能统一。