Python tabnanny 怎样检查混合缩进的歧义

Python 的混合缩进不一定马上表现为清晰的语法错误：同一层代码里混入 Tab 和空格时，编辑器的显示宽度、解释器的制表位规则和人的阅读结果可能不一致。tabnanny 的作用就是把这类空白问题单独拎出来检查。最实用的做法是先扫描，再按行修复，最后用编译检查确认文件仍然能运行。

官方地址：https://docs.python.org/3/library/tabnanny.html

tabnanny 到底检查什么

它读取 Python 的 token，而不是简单统计每行字符数。对同一层语句，tabnanny 会比较前导空白在不同制表位宽度下是否仍然等价；如果某个 Tab 与若干空格的含义会随制表位变化，就会报告歧义。解释器本身可能进一步抛出 TabError 或 IndentationError，所以不要把 tabnanny 当成完整语法检查器。

先用命令检查文件和目录

# 单独检查一个 Python 文件
python -m tabnanny src/worker.py

# 递归检查目录中的 .py 文件
python -m tabnanny src/

# -v 显示检查进度，适合确认目录范围
python -m tabnanny -v src/

没有输出通常只表示当前检查范围没有发现 tabnanny 负责的空白问题；它不是“文件已经通过全部测试”的证明。目录较大时先从报错文件开始，能减少把第三方生成目录也纳入排查的噪声。

如何读懂混合缩进的歧义

假设外层代码使用四个空格，下一行却以一个 Tab 加两个空格开头。某些编辑器把它显示成十个或更多列，但 Python 的制表位通常按八列展开。此时两行看起来像同一层，token 计算却可能不同，tabnanny 会在报错行附近提示 indent not equal。如果错误是 indent not greater，重点看当前行是否真的比栈顶缩进更深，而不是只看屏幕上的视觉位置。

def load_items(items):
    result = []
    for item in items:
        # 示例统一使用四个空格，避免 Tab 与空格混用
        result.append(item.strip())
    return result

上面代码的关键不是“四个空格”这个数字本身，而是同一文件、同一层级始终使用一致的字符。若项目已有明确规范，应以项目规范为准；新代码通常选择空格并让编辑器把 Tab 键转换为空格。

定位具体行：显示空白，再做最小修改

先打开编辑器的“显示空白字符”功能，观察报错行和它的上一个同层语句。不要整文件无差别替换后再猜测结果；更稳妥的是选中一个代码块，把前导 Tab 转为空格，并保持块内相邻语句的层级关系。

from pathlib import Path
import tokenize

path = Path("src/worker.py")
with path.open("rb") as source:
    # tokenize 能快速确认文件是否能被词法扫描
    list(tokenize.tokenize(source.readline))

这段检查能帮助区分“空白导致 token 化失败”和“代码已经能 token 化但逻辑层级不符合预期”。它不会替代 tabnanny，也不会替代编译与测试。

修复后用编译检查收口

# 先重新扫描空白问题
python -m tabnanny src/worker.py

# 再验证语法与缩进能被解释器接受
python -m py_compile src/worker.py

两步都通过后，再执行项目测试。若 py_compile 报错而 tabnanny 没有输出，说明问题可能是括号、字符串、名称或其他语法，而不是混合缩进；按编译器给出的行号继续处理。

常见问题

tabnanny 能修复混合缩进吗？

不能。它负责发现并报告问题，实际修改应由编辑器或格式化工具完成。

为什么 tabnanny 没输出但程序仍报 IndentationError？

它只覆盖特定的空白歧义；代码可能存在括号结构、代码块层级或其他语法错误，应继续运行编译检查。

检查目录会不会扫描虚拟环境？

会，只要目录中有 Python 文件。生产项目应指定源码目录，或先排除虚拟环境、缓存和生成目录。