tabnanny 是 Python 标准库中专用于检测 TAB 与空格混用缩进问题的工具，仅检查制表符和空格混合导致的语法歧义，不涉及 PEP 8 风格、语法错误或自动修复。
tabnanny 是什么，它能检测哪些缩进问题？
tabnanny 是 Python 标准库中一个轻量级的缩进检查工具，它不分析逻辑，只专注检测混用 TAB 和空格导致的语法歧义。它不会报 IndentationError 那种运行时错误，而是提前发现「可能被解释器误读」的缩进结构——比如某行用 4 个空格缩进，下一行却用 1 个 TAB（等价于 8 个空格），而 Python 解释器会按制表符宽度展开后比对，结果不可靠。
常见触发场景：
- 同一文件中
TAB和空格交替使用 - 缩进层级在视觉上对齐，但实际字符混合（例如：空格+TAB+空格）
- 使用不同编辑器（如 Vim 默认插入
TAB，VS Code 默认插入空格）协作时引入的隐性差异
如何用命令行快速扫描单个或多个 Python 文件？
直接调用 python -m tabnanny 即可，无需安装：
python -m tabnanny script.py python -m tabnanny src/ tests/
关键行为说明：
立即学习“Python免费学习笔记（深入）”；
Claw Code Suite (Python-Only Edition)
下载
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 默认递归扫描目录下所有
.py文件 - 每发现可疑缩进，输出类似
script.py:12: suspicious indentation的提示，但不指出具体哪类混用 - 加
-v参数可显示更详细信息（如该行实际缩进字符序列） - 不支持排除路径（如
--exclude），需靠 shell 过滤：find . -name "<em>.py" ! -path "./venv/</em>" | xargs python -m tabnanny
为什么不能用 tabnanny 替代 flake8 或 black？
tabnanny 定位非常窄：它只做「制表符/空格一致性」的粗筛，不检查：
- 缩进是否符合 PEP 8 推荐的 4 空格（它接受 2 空格、8 空格，只要统一）
- 行尾空白、空行、括号换行等风格问题
- 实际语法错误（如
if块缺缩进、多缩进一层）
对比来看：
-
flake8会报E111（缩进不是 4 的倍数）、E117（混合缩进）、E122（续行缩进不对）等更细粒度问题 -
black直接重写缩进，不报错，但要求全文件统一为 4 空格且无 TAB -
tabnanny更像一个“安全开关”：如果它报了，基本说明该文件一定存在解释器层面的风险；但它不报，不代表缩进风格合规
在 CI 流程中集成 tabnanny 的注意事项
把它加进 CI 脚本很简单，但容易忽略两点：
- 它返回非零退出码（
1）表示「发现可疑缩进」，而非语法错误，所以 CI 中要明确处理这个退出码，否则会被当成执行失败中断流程 - 它不支持配置（如忽略某些文件），若项目里有历史遗留脚本必须保留 TAB 缩进，只能临时跳过：
python -m tabnanny $(git diff --cached --name-only | grep '.py$' | grep -v 'legacy/')
真正难的是定位问题行——tabnanny 只说第 N 行可疑，但不告诉你那一行用了 TAB 还是空格。这时候得配合 cat -A file.py | sed -n "${N}p" 或编辑器显示空白字符功能人工确认。
缩进问题表面是格式，背后常是协作习惯或编辑器配置没对齐。用 tabnanny 扫一遍，只是第一步。
