Python tabnanny 怎样定位缩进中混用制表符的问题

Python tabnanny 可以帮助定位制表符与空格造成的缩进歧义。先用 python3 -m tabnanny 文件名.py 检查目标文件，再根据报告中的文件、行号和行文本找到行首空白；需要更多上下文时加 -v。它负责诊断，不会替你自动改写缩进。

整理旧项目时，应把“编辑器里看起来对齐”与“源码中使用了什么字符”分开。下面以将旧文件的混合缩进统一为空格为例说明操作；这不是声称某次 Python 升级才引入了限制，示例命令也不是本机运行记录。

官方文档：https://docs.python.org/3/library/tabnanny.html。

整理旧代码前，先明确缩进问题的范围

Python 用逻辑行开头的空白确定代码块分组。制表符的展开与当前列位置有关，并不是在所有位置都简单等于四个空格。编辑器把 Tab 显示成四列，并不会改变 Python 对源文件的处理规则。

混用空格和制表符、且缩进含义依赖于制表符宽度时，可能触发歧义或 TabError。反过来，tabnanny 没有报告也不等于“文件中不存在任何 Tab”，更不等于所有缩进都符合团队约定。

先定位单个文件，再扩大到源码目录

# 先检查实际报错的源码文件；路径替换为你的项目文件。
python3 -m tabnanny src/report.py

# 显示详细信息，便于了解检查对象和歧义说明。
python3 -m tabnanny -v src/report.py

# 单文件范围明确后，再递归检查自己的源码目录。
python3 -m tabnanny src

目录检查会递归处理其中的 .py 文件，文档明确目录本身不是符号链接时才进行递归。它不是一个自动识别仓库配置、忽略依赖目录的通用代码扫描器；传入路径前应先确定范围。

普通模式的缩进歧义报告可用于定位文件、行号和该行的表示。详细模式会补充说明；未发现这类问题时，普通模式通常不输出消息。文件读取或词法处理等错误也应分别看待，不能一概当成制表符混用。

只想收集有缩进歧义的文件名时，可使用下面的安静模式。它省略了定位行的细节，因此适合整理清单，不适合替代逐文件修正。

# 仅输出缩进歧义文件名；需要行号时去掉 -q 再查单个文件。
python3 -m tabnanny -q src

把行号与行首空白对应起来

拿到行号后，先看该行及其上方同级语句、所属 if 或 for 等代码块。报告行是问题被发现的位置，修正时还要考虑同一块中其他行的前缀，不应只把这一行移动到视觉上顺眼的位置。

若编辑器没有清楚显示空白，可用下面的只读片段查看指定几行的行首前缀。它不会修改文件，也不替代 tabnanny；用途只是将真实的 Tab 与空格表示出来。

import tokenize

# 改成实际文件和关注的行号范围；使用源码声明的编码读取。
with tokenize.open("src/report.py") as source:
    for number, line in enumerate(source, 1):
        if 18 

这里的 18 到 24 只是示例范围，不是某次扫描结果。行首前缀出现 \t 后，还需对照代码块判断它与其他行是否一致，不能仅凭包含该字符就断言该行一定是语法错误。

将混合缩进迁移为明确的空格层级

确定原本应该属于同一层级的语句后，将该代码块的行首缩进统一为空格。团队约定每级四个空格时，可以采用四个空格的层级；这是代码约定，tabnanny 本身并不是“四空格风格检查器”。

def total_ready(items):
    # 每级使用四个空格；累加只发生在条件成立的分支中。
    total = 0
    for item in items:
        if item["ready"]:
            total += item["amount"]
    # 返回语句属于函数体，而不是循环体。
    return total

这段修正示例突出的是层级含义：累加在条件内部，返回在循环外部。若把 return 缩进到循环内部，即使全是空格、没有歧义，也可能改变业务行为。

不要把整个文件中的 Tab 字符盲目替换，包括字符串、三引号文本或需要原样保存的数据。更稳妥的方式是针对已经确认层级的代码块重排缩进，并查看改动范围；复杂字符串区域另行确认。

修正后的复查范围与常见问题

# 保存文件后，重新检查刚修改的对象。
python3 -m tabnanny -v src/report.py

# 单文件问题处理完，再检查约定的业务源码范围。
python3 -m tabnanny src

上面的复查是给读者在自己项目中的操作建议，本文没有执行这些命令。消除缩进歧义后，还需要根据项目原有方式确认函数行为，尤其是循环和条件分支的归属，不能把诊断无消息当作业务正确的证明。

为什么扫描通过但编辑器仍提示Tab？ 两者目标不同。编辑器可能禁止所有行首Tab，tabnanny关注缩进歧义。检查通过不表示满足所有风格约束。

能只凭命令退出码判断所有问题吗？ 不宜这样假设。CPython 实现对缩进歧义有报告后返回的路径，其他读取或词法错误又有不同处理。若接入自动化，需要明确使用版本与诊断分类，不能把它当成统一的“任意错误必定非零退出”接口。

为什么不直接在应用里调用内部函数？ 官方把它主要定位为脚本工具，并提示 API 可能改变。日常定位优先使用命令行入口；需要集成时再评估公开函数和版本约束。

参考：tabnanny 官方文档；Python 缩进规则；CPython tabnanny 实现。