# Python Formatter

URL: https://discuvr.org/python-formatter/?hl=zh-hans
Last updated: 2026-11-07
MCP tool: `format_python`

粘贴 Python 代码，按你选择的行宽和选项由 Black 格式化。语法错误会给出准确的行号。你的代码绝不会被执行，也绝不会被存储。

这个工具对你粘贴的内容运行 Black - 大多数 Python 项目早已认可的格式化工具 - 按你选择的行宽和引号处理方式进行格式化。如果文件无法解析，它会说明是哪一行；如果文件已经格式化过，它也会如实告知，而不是假装做了什么。

## 功能说明

- 以 79、88、100 或 120 列进行 Black 格式化。
- "仅检查"模式：在不修改文件的情况下，了解文件是否会发生变化。
- 保留你自己的引号风格，或让 Black 统一规范它。
- 遵守或忽略那个让集合保持展开状态的神奇尾随逗号。
- 当语法与版本相关时，指定目标 Python 版本。
- 语法错误会报告行号、列号以及周围的代码。
- 报告增删了多少行，以及文件的整体结构。

## 工作原理

1. 粘贴代码，或者整个文件的内容。
2. 选择一个行宽以及你关心的任何选项。
3. 点击格式化，然后复制或下载结果。

## 你的代码永远不会被执行

格式化 Python 代码并不需要运行它。代码会被解析成语法树，再完全在内存中根据这棵树重新生成 - 它从不会被写入文件，从不会被导入，也从不会被执行。一个会运行你粘贴内容的格式化工具，实际上就是带文本框的远程命令行。

## 为什么是 Black，而不是我们自己的看法

Black 是一种保持 AST 不变的转换：输出的代码与输入的代码是同一个程序。正是这个特性，才让一个格式化工具值得信任，也正因如此，这个工具的任何环节都没有语言模型参与。被要求整理代码的模型，偶尔会在整理过程中顺手改写某一行，而对可正常运行的代码进行无声的改动，正是格式化工具绝不能犯的失误。

## 仅检查

这和 CI 问的是同一个问题：这个文件会发生变化吗？检查模式会原样返回你的原始代码，并报告 Black 本来是否会重新格式化它，以及会改动多少行。这是快速弄清楚某个流水线为什么在一个你无法在本地复现的文件上失败的办法。

## 魔术尾随逗号与 fmt: off 实例

最后一项后面的逗号会让 Black 把调用或集合保持为每行一项：result = compute(alpha, beta,) 会变成四行，alpha, 和 beta, 各占一行。勾选忽略魔术尾随逗号后，同样的输入只要放得下行宽就会变成 result = compute(alpha, beta)。要保护手工对齐的代码块（例如矩阵），在它上方一行写 # fmt: off，下方写 # fmt: on，Black 会原样保留两者之间的内容；行尾的 # fmt: skip 只保护这一行。这些是 Black 自己的注释，所以在你项目的 CI 运行 Black 时同样有效。

## 问题

**我的代码会被上传或存储吗？**

代码会被发送到服务器，在内存中格式化后在同一个响应里返回。没有任何内容会被写入磁盘、缓存或记录日志，使用记录只保留计数 - 大小、选项、改动了多少行 - 从不保留代码本身。

**格式化会改变我代码的行为吗？**

不会。Black 改变的是排版，而不是行为，但它做的不只是挪动空格。它会删除多余的括号（x = (1) 变成 x = 1），把数字的前缀和指数改成小写（0XABCDEF 变成 0xABCDEF，1E5 变成 1e5），把调用拆成多行时补上末尾逗号，压缩连续的空行，并去掉 docstring 内部的空格（""" Doc. """ 变成 """Doc."""）。最后这一项会改变 __doc__ 的文本，只有当你的代码读取自己的 docstring 时才有影响。

**为什么它完全没有重新格式化我的文件？**

因为它在你选择的行宽下已经是格式化过的了。工具会直接说"已经格式化过"，而不是悄悄返回一份原样副本。

**它会排序我的 import 吗？**

不会。排序 import 是 isort 的工作，不是 Black 的，两者分歧足够常见，如果在这里这么做会让你感到意外。

**它能格式化有语法错误的文件吗？**

任何格式化工具都做不到 - 一个无法解析的文件没有可供重写的结构。你会得到行号、列号以及周围的代码，方便你修正后再试一次。

**它遵循 PEP 8 吗？**

Black 与 PEP 8 兼容，只有一处广为人知的偏差：它的默认行宽是 88 而不是 79。如果你需要更严格的数值，请在行宽选择器中选 79。

**最大能格式化多大的文件？**

每次最多 400,000 个字符。格式化超过 10 秒会被中止，只有非常大或高度重复的文件才会碰到，每个 IP 地址每 10 分钟可格式化 30 次。

**如何在编辑器、pre-commit 或 CI 中得到同样的格式？**

本页运行的是 Black，宽屏时页面顶部栏会显示其版本。Black 从 pyproject.toml 的 [tool.black] 部分读取项目设置，键名与长命令行选项相同：你选的"行长"对应 line-length = 88，勾选了"保留我的引号"就写 skip-string-normalization = true，"忽略魔术尾随逗号"对应 skip-magic-trailing-comma = true，在"目标"中固定的版本对应 target-version = ["py311"]。编辑器插件和 pre-commit 钩子读取的也是这个文件。用 black . 格式化，在 CI 中运行 black --check --diff . ：它不改动任何文件，若有文件会被重新格式化则以退出码 1 结束。请固定与本页相同的 Black 版本，因为每个日历年的第一个版本可能会改变稳定风格。

**输出结果与 Ruff 的格式化器（ruff format）相同吗？**

几乎总是相同，但并非逐字节一致。Ruff 的格式化器被设计为 Black 的直接替代品，Ruff 文档称，在 Django、Zulip 等已用 Black 格式化的大型项目上，超过 99.9% 的行结果完全相同。对从未经过 Black 处理的代码，差异会更多，尤其是行尾注释，其文档列出了有意为之的差异。它的默认行长同样是 88，在 [tool.ruff] 中用 line-length 设置；[tool.ruff.format] 中的 quote-style = "preserve" 对应"保留我的引号"，skip-magic-trailing-comma = true 对应"忽略魔术尾随逗号"。如果你的 CI 运行 ruff format --check，请用 Ruff 而不是本页来检查文件。

## 更多开发者工具

- [HTML 查看器](https://discuvr.org/html-viewer/?hl=zh-hans)
- [IP 子网计算器](https://discuvr.org/ip-subnet-calculator/?hl=zh-hans)
- [编码 / 解码](https://discuvr.org/encode-decode/?hl=zh-hans)
- [Unix 时间戳转换器](https://discuvr.org/timestamp-converter/?hl=zh-hans)

## 常一起使用

- [文本比较](https://discuvr.org/text-diff/?hl=zh-hans)
- [大小写转换与行工具](https://discuvr.org/case-converter/?hl=zh-hans)
- [Study Buddy](https://discuvr.org/study-buddy/?hl=zh-hans)

---

Part of Discuvr (https://discuvr.org/): Discuvr is a collection of free, focused tools for day-to-day professional work - office and data utilities, legal and compliance helpers, privacy and security checks, and developer formatters. Every tool has its own page, and most can also be called from ChatGPT or Claude over MCP.