简介这是一份面向Python开发者与代码质量初学者的Pychecker 0.8.19静态分析工具源码包可用于在运行前排查类型不匹配、未定义引用、未使用变量、异常处理不当及循环依赖等常见问题适合作为代码审查与静态分析原理的学习样本。压缩包共54个文件以41个Python源码为主体辅以配置说明、变更记录、测试用例及批处理脚本整体约176KB体量轻便便于本地解压查阅与搭建实验环境。目前已有391人学习下载。包内保留了较完整的核心检查流程、警告与配置机制以及多组测试用例读者可借此理解Pychecker的规则组织、检查入口和报告输出方式也可将其作为小型静态检查工具的参考实现用于课程实验、项目代码复核、历史版本研究或自有工具链的原型验证。1. 凌晨两点的 NameError和一路绿灯的 python 代码检查去年冬天某公司的一个定时任务在凌晨两点抛NameError: name retry_times is not defined而 CI 里的 python 代码检查从头到尾是绿的。翻代码发现那个变量只在if分支里赋值异常路径直接走到了引用处。这件事之后我把仓库的检查链重排了一遍核心补的就是 pychecker 这类静态检查工具它不跑你的业务逻辑只把模块解析成抽象语法树、建符号表再顺着作用域链判断「这个名字到底有没有被赋过值、有没有被用过就扔」。它最适合三种人——维护五年以上老仓库的、脚本散落在十几个目录没人敢删的、刚接手别人项目想先摸雷区的新同学。下面按「原理怎么立住 → 本地怎么接 → 规则怎么改 → 坑在哪 → 怎么卡住合并」的顺序拆。2. pychecker 的检查原理符号表、作用域链与名字解析2.1 编译期到底能拿到什么AST 与符号表要理解 pychecker 能查什么先得知道 Python 在import一个模块时干了什么。解释器先把源码compile成 code object这个过程中间会产出两样静态检查工具最依赖的东西抽象语法树AST和符号表symtable。AST 描述「代码长什么样」符号表描述「每个名字在这个作用域里是被赋值了、被引用了还是只是个参数」。pychecker 的工作面基本就落在这两层上所以它不需要你的依赖装全、不需要数据库连得上纯文本就能跑。我一般先用二十行代码把这两样东西打出来看比读任何文档都直观import ast import symtable SRC def load(path, retryFalse): data open(path).read() if retry: times 3 return data.upper(), times # 第一层只做语法解析不做任何名字检查 tree ast.parse(SRC) print(ast.dump(tree, indent2)[:200]) # 第二层建符号表能看出每个名字的赋值/引用关系 table symtable.symtable(SRC, demo.py, exec) for child in table.get_children(): # 模块级下挂的是函数作用域 print(scope:, child.get_name(), child.get_type()) for sym in child.get_symbols(): print( sym.get_name(), assigned, sym.is_assigned(), referenced, sym.is_referenced(), parameter, sym.is_parameter(), )这段代码的逻辑是分两步走ast.parse只保证语法合法里面哪怕全是未定义变量它也照单全收symtable.symtable才是关键第三个参数exec表示按模块顶层来建表另外两个可选值是eval表达式和single交互式单行选错了作用域层级会对不上。get_children()拿到的是嵌套作用域函数、类、lambda 都会各占一个get_symbols()返回的是当前作用域里的名字集合。跑完你会看到times的assignedTrue、referencedTrue但符号表本身不告诉你赋值发生在哪个分支。这正是漏报的源头times只在if retry里赋值retryFalse时return那行必炸。所以真正成熟的检查器不会只读符号表还要在 AST 上做一层控制流近似——把if/else、try/except、for/while的路径分开看判断某个名字在「所有能到达引用点的路径」上是否都被赋过值。这一步做得多细直接决定了工具是「能用的」还是「只会报格式问题的」。提示如果你只是想快速验证一个怀疑symtable比装一整套检查器快得多想做成流水线卡点才需要完整的 AST 遍历加路径分析。2.2 为什么它比 grep 靠谱作用域链与 LEGB很多人第一反应是「我grep一下变量名不就行了」。这在三种场景下会立刻失真。第一种是重名十个文件里都有datagrep分不清哪个是形参、哪个是模块级常量、哪个是循环变量。第二种是遮蔽函数里写了list [...]把内置的list遮掉了grep完全看不出问题但后面任何一次list(...)调用都会TypeError。第三种是闭包和global/nonlocal名字在语法上出现在内层函数里实际绑定却在外层纯文本匹配根本追不到。pychecker 这类工具走的是 LEGB 顺序——Local、Enclosing、Global、Builtin逐层往上找最近一次绑定。它同时维护一份内置名字清单len、list、id、type这些一旦发现你在局部作用域里给它们赋值就报「遮蔽内置名」。这条规则在老代码里命中率极高我见过一个文件里同时把id、type、input全遮了一遍跑起来没报错纯属运气。作用域链分析还带来一个副作用能力未使用变量检测。符号表里is_assignedTrue但is_referencedFalse且名字不是_开头的约定俗成占位符基本就是写完忘了删。这类问题不影响运行但会持续污染阅读体验也是 code review 里最容易被跳过的部分。import symtable SRC def handler(events): buffer [] limit 100 for e in events: buffer.append(e) return buffer table symtable.symtable(SRC, demo.py, exec) fn table.get_children()[0] unused [ s.get_name() for s in fn.get_symbols() # 赋过值、没被引用、不是参数、不是以下划线开头的占位符 if s.is_assigned() and not s.is_referenced() and not s.is_parameter() and not s.get_name().startswith(_) ] print(可能未使用:, unused) # [limit]这里的判断条件每一项都有含义is_assigned()排除纯外部名字not is_referenced()是核心判据not is_parameter()是因为没用到的形参往往是接口约定回调、信号槽报了纯属噪音startswith(_)是给「我知道它没用但我要留着」留的后门。四个条件缺一个误报率就会明显上升。参数上唯一需要调的是最后那条前缀约定有的团队用_unused有的用__按团队习惯改就行。2.3 静态分析的边界哪些问题它注定查不出来把能力吹完必须说边界否则你会对着一个查不出的 bug 怀疑工具坏了。第一类是动态属性getattr(obj, name)、setattr、**kwargs拼出来的调用静态阶段压根不知道name是什么。第二类是动态导入importlib.import_module(mod_name)模块名是运行时算出来的工具连文件都定位不到。第三类是装饰器改写签名一个wraps写错的装饰器可以让函数的真实参数表完全变样静态看得见语法、看不见运行时行为。第四类是元类与__getattr__兜底属性访问永远「看起来合法」。我一般的处理原则是把静态检查当「下限守卫」不当「正确性证明」。它能保证的是「不存在明显的名字错误、明显的作用域错误、明显的死代码」剩下靠单测和类型注解补。所以接入顺序上我会先让 pychecker 只报 error 级等基线清干净了再逐条开 warning别一上来全量开否则第一天就被几千条历史问题淹没——这是最多人翻车的地方。2.4 一个最小可跑的检查闭环把前面几块拼起来就是一个能塞进脚本的最小检查器解析 → 建表 → 递归遍历所有子作用域 → 收集可疑名字 → 输出带行号的报告。真正产品化的工具还会加路径分析、跨模块导入解析和增量缓存但骨架就是这么点东西。理解骨架的好处是当工具报了一条你看不懂的告警时你能判断它是「符号表层面的事实」还是「路径分析的推测」——前者基本可信后者要看它的近似策略是否覆盖了你的写法。3. 接进本地工作流命令行、配置优先级与退出码3.1 从一条命令开始别急着写配置文件装的方式我一般走项目虚拟环境避免和系统 Python 打架# 建独立环境避免污染系统解释器 python -m venv .venv source .venv/bin/activate # 装到当前环境包名以你实际拿到的为准 pip install pychecker # 最朴素的一次调用只查 src 目录输出文本格式 pychecker src/ # 只看 error 级warning 先不管 pychecker --level error src/ # 机器可读输出方便后面接 CI 解析 pychecker --output-format json src/ report.json三条命令对应三种使用阶段第一条验证装没装上、能不能跑通第二条是日常开发用的只看会挂的那一档第三条是给流水线用的。参数上--level控制告警下限--output-format常见的取值是text、json、junit部分实现用--format装完跑一次--help确认别照抄。我不建议新手一上来就写配置文件先跑通裸命令看到真实输出再决定要压制什么。跑完第一遍你大概率会看到几百条。先别急着改代码把输出存下来# 存一份基线后面用来算「新增了多少」 pychecker --output-format json src/ baseline.json # 按规则码统计看哪类问题最集中 python - PY import json, collections data json.load(open(baseline.json)) c collections.Counter(i[code] for i in data) for code, n in c.most_common(10): print(f{code}\t{n}) PY这段脚本的作用是把「一堆看不懂的告警」压缩成「按规则码排序的分布」most_common(10)只看前十类。实操经验是前两三类往往占了七成以上先把这几类的存量清掉或者整体压制噪音立刻降到可接受水平。注意 JSON 里的字段名code、message、line不同实现可能不一致先print(data[0])看一眼结构再改脚本。3.2 配置文件的优先级与常用参数工具多了以后必然遇到「配置文件打架」一个pyproject.toml、一个setup.cfg、一个.pychecker谁说了算常见做法是优先级从高到低为「命令行参数 当前目录的专用配置文件 pyproject.toml里的专用段落 setup.cfg 用户级配置」并且就近原则——子目录里的配置会覆盖父目录。搞不清这条就会出现「我明明在根目录写了 exclude怎么子包还是被扫」的玄学。下面这份配置是我在多数项目里会用的起手式字段名以你装到的版本为准含义说明在表里# pyproject.toml [tool.pychecker] # 只查这些目录白名单比黑名单可靠 include [src, scripts] # 排除测试、迁移脚本、自动生成的 stub exclude [tests, migrations, *_pb2.py, */generated/*] # 告警下限先 error稳定后降到 warning level warning # 单行最大长度和格式化工具保持一致 max-line-length 100 # 整体忽略的规则码 ignore [PY005] # 只在指定路径上忽略某条规则 per-file-ignores [ src/legacy/*:PY001,PY003, scripts/*:PY001, ] # 并行进程数大仓库开 4~8 jobs 4参数作用我常用的取值与理由include/exclude控制扫描范围白名单写死黑名单兜底避免新目录被漏掉level告警下限新接入用error存量清完再降warningignore全局关规则只关确认无价值的那几条别超过 3 条per-file-ignores按路径关规则老代码专用配注释说明原因和清理期限max-line-length行长阈值与 black/ruff 保持一致否则两边反复拉扯jobs并行度按 CPU 核数一半取值过高反而被 IO 拖慢per-file-ignores是最容易被滥用的一个。我给自己定的规矩是每条豁免必须带一段注释写清「为什么豁免、什么条件下可以删」否则半年后没人敢动技术债就这么固化了。3.3 退出码是唯一的判据别靠人眼本地跑通只是第一步真正产生价值是在提交前和合并前卡住。所有这类工具的退出码语义基本一致0 表示干净1 表示发现问题2 表示工具自身出错配置写错、文件不存在。这里有个血泪教训——一定要把 2 当成失败处理否则配置写错导致「扫了 0 个文件」退出码不是 0 但你也没拦住等于全程空转。#!/usr/bin/env bash # pre-commit 钩子只查本次改动的 Python 文件 set -uo pipefail changed$(git diff --cached --name-only --diff-filterACM | grep -E \.py$ || true) [ -z $changed ] exit 0 pychecker --level error $changed status$? case $status in 0) echo 检查通过; exit 0 ;; 1) echo 存在 error 级问题请先修复再提交; exit 1 ;; *) echo pychecker 自身执行异常检查命令行与配置; exit 2 ;; esac逻辑上有三个要点。第一--diff-filterACM只取新增、修改、复制三类删除的文件不需要检查漏掉这个过滤会在删文件时误报。第二set -uo pipefail让管道里任意一环失败都能暴露grep无匹配时会返回 1所以后面补|| true防止脚本提前退出。第三case分支把 2 单独拎出来这是整个脚本最关键的一行。注意一次性把所有历史文件塞进钩子第一次提交会被拦几十次人会直接--no-verify绕过。正确做法是先跑全量存基线钩子只查增量存量按季度分配清理。4. 规则裁剪与自定义检查器从看得懂到改得动4.1 规则分级先把 error 和 warning 分清楚大部分检查工具的规则分三档含义不一样处理策略也不该一样error 是「运行必炸」级别比如未定义名、调用不存在的属性、return在finally外warning 是「大概率有问题」比如未使用变量、遮蔽内置名、可变默认参数info 是「风格建议」比如函数过长、嵌套过深。我见过的失败案例几乎都是把三档混在一起处理结果 error 被 warning 的海量告警淹没没人再看。下面这张表是我给团队定的分级规则码是工具输出里的标识具体编号以你的版本为准但分级逻辑是通用的级别典型规则是否阻断合并处理策略error未定义名、未绑定局部变量、不可达代码后仍有引用是当次必须修不豁免warning未使用变量、遮蔽内置名、可变默认参数是带预算新增必须修存量给清理期限info圈复杂度、函数行数、注释密度否只看趋势不进卡点「带预算」这个说法来自实践给存量问题设一个总数上限只允许减少不允许增加新代码进来顶破上限就失败。这样既不清零所有历史债也不会让债务继续膨胀。4.2 写一个自定义检查器把团队约定固化成代码通用规则永远覆盖不到团队特有的约定比如「所有外部 HTTP 调用必须带 timeout」「禁止在业务层直接print」「数据库查询必须走封装层」。这些东西写进文档没人看写成检查器才有人遵守。多数工具支持插件式扩展核心是继承一个 Visitor 基类、实现visit_XXX方法import ast class TimeoutChecker(ast.NodeVisitor): 禁止无 timeout 的外部调用命中就记一条带上行号 def __init__(self): self.problems [] def visit_Call(self, node): fn node.func # 只关心形如 requests.get / requests.post 的调用 if isinstance(fn, ast.Attribute) and isinstance(fn.value, ast.Name): if fn.value.id requests and fn.attr in {get, post, put}: kwargs {k.arg for k in node.keywords if k.arg} if timeout not in kwargs: self.problems.append( (node.lineno, frequests.{fn.attr} 缺少 timeout 参数) ) # 必须继续下探否则嵌套调用会被漏掉 self.generic_visit(node) # 用法解析文件后喂进去 tree ast.parse(open(src/api.py, encodingutf-8).read()) checker TimeoutChecker() checker.visit(tree) for line, msg in checker.problems: print(f{line}: {msg})逐段说清楚。visit_Call是 AST visitor 的约定命名遇到函数调用节点就会触发不需要手动注册。isinstance(fn, ast.Attribute)加isinstance(fn.value, ast.Name)这两层判断是为了精确匹配requests.xxx这种「模块.函数」形式如果只判断fn.attr in {...}会把self.get()、client.post()全部误伤。kwargs {k.arg for k in node.keywords if k.arg}里的if k.arg是防御性的——**options这种展开调用进来时arg是None不加判断会抛异常。最后一行self.generic_visit(node)最容易漏。漏掉它的后果是只检查最外层调用requests.get(url).json()这种链式写法里内层的get根本不会触发 visitor。这个 bug 我调过一次表现是「明明有漏 timeout 的调用工具一声不吭」查了半天才发现是递归没往下走。调用处的参数说明ast.parse一定要显式指定encodingutf-8Windows 上默认按 GBK 读遇到中文注释直接SyntaxError看起来像是「工具坏了」实际是编码问题。node.lineno是 1-based报告里直接输出就是编辑器里能跳转的行号。4.3 抑制与基线三种手段别用混抑制手段有三类用途完全不同。第一种是行内抑制在行尾加# noqa: PY001之类的注释粒度最细适合「我知道这行有问题但必须这么写」。第二种是文件级或目录级忽略配在per-file-ignores里适合整个模块都是生成代码或兼容层的情形。第三种是基线文件把当前所有存量问题的指纹存下来之后只报新出现的。前两种是「真豁免」第三种是「暂缓」。混用会出事把基线当成豁免代码挪了一行指纹就变问题重新冒出来把文件级忽略当成暂缓那个目录永远没人再动。我的做法是行内抑制必须带原因文件级忽略必须带清理期限基线文件进版本库并且每个月重算一次。# 行内抑制必须写原因否则下一个改这行的人不知道能不能删 legacy_client build_client(retries0) # noqa: PY005 兼容旧网关Q3 下线后删除noqa后面的规则码要写全只写# noqa会把该行所有规则一起关掉未来新加一条规则在这行失效你也发现不了。多规则用逗号分隔# noqa: PY001,PY003。5. 排查与避坑五类误报漏报的现象、成因与处置5.1 现象CI 全绿线上照样 NameError原因检查只跑了单文件跨文件的导入链没解析。函数里引用的名字来自from other import *或者延迟导入静态阶段看不到符号工具选择「不确定就不报」于是漏了。另一种更隐蔽变量在try块里赋值except里直接引用路径分析没覆盖异常路径。解决把检查范围从「改动的文件」扩到「改动文件 其依赖闭包」多数工具支持--follow-imports之类的开关同时关掉「不确定时不报」的宽容模式让它把可疑项以 info 级输出人工过一遍。我现在的习惯是 CI 里跑两遍一遍只查 error 做卡点一遍全量跑但只存档用于定期抽查。5.2 现象几千条告警团队直接绕过钩子原因没做存量隔离就全量接入。老仓库里历史问题动辄上万条第一次接进去就是灾难人的反应一定是git commit --no-verify一旦养成习惯这条防线就废了。解决分三步走。第一步跑全量生成基线文件并入库第二步钩子只查增量报错信息里明确写「本次新增 3 条历史 4821 条不在本次检查范围」第三步设季度目标每个季度把基线总数降 10%降不动就说明规则有问题该关掉。5.3 现象扫描越来越慢最后没人愿意在本地跑原因include写成了[.]把.venv、node_modules、site-packages、构建产物全扫了一遍或者开了jobs16但磁盘是机械盘进程全在等 IO比单进程还慢。解决include永远写白名单目录不要写.。exclude里至少要有.venv、venv、__pycache__、node_modules、dist、build、*.egg-info。jobs取 CPU 物理核数的一半可以先试 4。改完用time pychecker src/对比一下正常应该从几十秒降到几秒。5.4 现象和格式化工具反复打架改一行触发十个文件原因两套工具对行长的定义不同。格式化工具按「显示宽度」算中文算两个字符检查工具按「字符数」算中文注释密集的文件两边结论永远不一致于是你格式化完提交钩子报行长超限改完再格式化又变回去。解决把max-line-length在两边配成同一个值并且统一用「字符数」口径中文注释多的项目直接把它调宽到 120别硬卡 88。另外把格式化放在提交前自动执行pre-commit里先 format 再 check顺序不能反。5.5 现象豁免注释越积越多最后没人敢删原因# noqa只写了码没写原因半年后原作者离职谁也不知道这行是「真有问题不能改」还是「当年赶工期随手加的」。解决把「带原因」做成硬约束——写个几十行的脚本扫全仓凡是noqa后面没跟注释文本的一律报错再往前一步把原因里必须包含期限如Q3、2026-06也纳入检查。这事看着形式主义但确实是唯一能让豁免不腐烂的办法。我见过一个仓库里 300 多条noqa加上原因和期限之后三个月内自然清掉了将近一半——因为写原因的过程本身就让人重新想了一遍「真的需要吗」。6. 增量扫描与趋势让检查结果真正卡住合并全量扫描跑得再准如果每次都要等三分钟人就会绕过它。所以最后一层要解决的是「快」和「可比较」。增量扫描的做法是先算出本次改动涉及的文件集合再把这些文件连同它们的直接依赖一起送进检查器# 对比目标分支取出改动过的 Python 文件 base${1:-origin/main} files$(git diff --name-only --diff-filterACM $base...HEAD | grep -E \.py$ || true) [ -z $files ] { echo 无 Python 改动; exit 0; } # 只查增量输出 JSON 便于后续比对 pychecker --level error --output-format json $files new.json status$? # 与基线做差集只报告「新增」的问题指纹 python - PY import json, sys base {i[fingerprint] for i in json.load(open(baseline.json, encodingutf-8))} new json.load(open(new.json, encodingutf-8)) added [i for i in new if i[fingerprint] not in base] for i in added: print(f{i[path]}:{i[line]} [{i[code]}] {i[message]}) sys.exit(1 if added else 0) PY三个环节各有讲究。git diff --diff-filterACM里的...是三点语法表示「从共同祖先到 HEAD」比两点语法更准不会把目标分支后来的提交算成你的改动。fingerprint这个字段是工具给的稳定标识通常由「文件路径 规则码 上下文哈希」组成它对行号漂移有容忍度——这也是为什么不能自己拿path:line拼去重键代码往上挪两行就全成了新增。最后那个sys.exit(1 if added else 0)是整个脚本的判据只有真正新增的问题才让流水线失败历史问题一次都不提。这条规则一立团队对检查器的抵触会下降一个数量级——因为它不再翻旧账。趋势这块我只留两个数每千行代码的告警密度和noqa注释的总条数。前者反映整体卫生状况后者反映豁免有没有失控。把这两个数每周落到一张表里比任何检查报告都更能说明问题周次代码行数error 数告警密度条/千行noqa 条数W1128,400463.6312W4131,200121.1268W8135,90050.4191密度往下走、noqa往下走说明规则集是健康的密度不动而noqa猛涨说明大家在用豁免换清净这时候该回头审规则而不是继续压人。最后一个我每次都走的验证闭环写在钩子旁边当注释改规则之后先随手造一个已知会报错的样例文件确认它确实报出来再拿一个已知干净的模块确认没有误报两步都过才允许把新规则推到主分支。这条习惯是被一次翻车教出来的——当时我把一条 error 级规则误配成了ignore整整两周流水线全绿直到线上又炸了一次同名异常。从那以后规则变更我一律走「造错例 造干净例」这两步宁可多花五分钟也不相信「配置看着没问题」。希望这套拆法能帮到你少走我那几个月的弯路。本文还有配套的精品资源点击获取