KBEngine 内嵌 CPython 3.7 的 pyclbr 模块:只读解析源码构建类浏览器的 Function/Class 描述符
KBEngine 内嵌 CPython 3.7 的 pyclbr 模块:只读解析源码构建类浏览器的 Function/Class 描述符
pyclbr(Python class browser)是 KBEngine 仓库内嵌的 CPython 3.7.3 标准库组件(见 kbe/src/lib/python/Include/patchlevel.h 中的 PY_VERSION "3.7.3"),它通过分词(tokenize)而非导入的方式扫描 .py 源码,提取模块级函数、类、嵌套定义与继承关系,生成 Function/Class 描述符树。读完本文,你能完整掌握 readmodule()、readmodule_ex() 两个入口函数的参数与返回结构、Function/Class 描述符的全部属性(含 3.7 新增的 parent/children)、基于缩进栈的源码解析原理与模块缓存机制,并能像 IDLE 的 Module Browser 那样用它安全地实现一个模块/类浏览器。
一、pyclbr 的定位:为什么"不 import 也能看结构"
pyclbr 模块提供关于 Python 模块中定义的函数、类和方法的有限信息——但这些信息已经足以实现一个模块浏览器。它的核心设计取舍在 kbe/src/lib/python/Lib/pyclbr.py 的模块 docstring 中交代得很清楚:
- 从源码提取,而不是导入模块。信息来自对
.py文本的分词扫描,因此对不受信任的代码是安全的——你永远不需要真正执行被浏览的代码(这是 pyclbr 相对于inspect的最大优势); - 代价是只支持纯 Python 模块。所有用 C/C++ 实现的标准库和扩展模块(extension modules)没有 Python 源码可读,pyclbr 对它们无能为力;
- 它"解析得足够多":识别 import 语句、
class/def语句,以及类的直接基类列表。
从源码结构看,整个模块只有一个公开接口(__all__ 见 pyclbr.py):
__all__ = ["readmodule", "readmodule_ex", "Class", "Function"]
注意官方文档(pyclbr.rst)特别提示:Class 和 Function 的实例是返回给你的描述符,"用户不应尝试自行创建这些类的实例"——它们由解析器内部构造并挂接好 parent/children 双向链。
二、两个入口函数:readmodule 与 readmodule_ex
2.1 readmodule(module, path=None) —— 只看顶层类
这是历史遗留接口。它返回一个字典,把模块级类名映射到 Class 描述符;如果可能,被导入的基类描述符也会包含在内:
module:要读取的模块名字符串,可以是包内的子模块(如"email.parser");path:可选的目录路径序列,查找源码前会前置(prepend)到sys.path之前。
源码实现见 pyclbr.py:它实际上是调用内部工作函数 _readmodule 后过滤掉 Function,只保留 Class:
def readmodule(module, path=None):
"""Return Class objects for the top-level classes in module.
This is the original interface, before Functions were added.
"""
res = {}
for key, value in _readmodule(module, path or []).items():
if isinstance(value, Class):
res[key] = value
return res
2.2 readmodule_ex(module, path=None) —— 完整的函数/类描述符树
readmodule_ex 是推荐的现代接口,返回一个基于字典的树:
- 字典的顶层键 → 模块级函数和类名,值是对应的
Function/Class描述符(只收录以def/class语句定义的项,以及from XXX import YYY带进来的类); - 嵌套对象挂在父对象的
children字典里(3.7 起支持,见下文); - 如果被读的是包(package),返回的字典会带一个特殊键
'__path__',其值是包含该包搜索路径的列表。
def readmodule_ex(module, path=None):
"""Return a dictionary with all functions and classes in module.
Search for module in PATH + sys.path.
If possible, include imported superclasses.
Do this by reading source, without importing (and executing) it.
"""
return _readmodule(module, path or [])
文档在 pyclbr.rst 中记录了 3.7 的版本说明:
versionadded 3.7:嵌套定义的描述符。它们通过新的
children属性访问,每个描述符还多了一个parent属性。
2.3 真实用例:IDLE 的 Module Browser 正是 pyclbr 的直接消费者
仓库内的 IDLE 实现 kbe/src/lib/python/Lib/idlelib/browser.py 展示了 readmodule_ex 的标准用法。树节点的 listchildren 方法(browser.py):
def listchildren(self):
"Return sequenced classes and functions in the module."
dir, base = os.path.split(self.file)
name, ext = os.path.splitext(base)
if os.path.normcase(ext) != ".py":
return []
try:
tree = pyclbr.readmodule_ex(name, [dir] + sys.path)
except ImportError:
return []
return transform_children(tree, name)
这里把待浏览文件所在目录拼进 path 参数,正是利用 path 前置 sys.path 的语义来定位非标准位置的文件。而 transform_children(browser.py)则演示了如何消费 Class.super:对字符串型的基类与 Class 型基类分别取名字,跨模块时拼上 module.Class 前缀,再按 lineno 排序展示。双击节点时(browser.py)利用描述符的 file + lineno 跳到源码定义行——这正是 file/lineno 属性存在的意义。
三、Function 描述符的属性
Function 实例描述由 def 语句定义的函数,属性定义在基类 _Object 中(pyclbr.py):
| 属性 | 说明 |
|---|---|
Function.file |
函数所定义的文件名 |
Function.module |
定义该函数的模块名 |
Function.name |
函数名 |
Function.lineno |
定义起始的行号 |
Function.parent |
顶层函数为 None;嵌套函数指向其父描述符(3.7 新增) |
Function.children |
字典,映射嵌套在其中的函数/类名到子描述符(3.7 新增) |
从源码结构看,_Object.__init__ 一次性初始化这些字段并空 children 字典:
class _Object:
def __init__(self, module, name, file, lineno, parent):
self.module = module
self.name = name
self.file = file
self.lineno = lineno
self.parent = parent
self.children = {}
def _addchild(self, name, obj):
self.children[name] = obj
嵌套时由 _nest_function(pyclbr.py)完成父子双向挂接:子描述符的 parent 指向父对象,父对象的 children[name] 指向子对象;若父对象是 Class,同时会向 methods 字典追加一条记录(见下一节)。
四、Class 描述符的属性:super 与 methods
Class 实例描述由 class 语句定义的类,拥有与 Function 相同的六个属性,另加两个:
| 属性 | 说明 |
|---|---|
Class.super |
直接基类列表。能定位到源码的基类是 Class 实例;定位不到的则退化为类名字符串 |
Class.methods |
方法名 → 起始行号的字典。虽然可由 children 推导,但为了向后兼容而保留 |
Class 的构造与 _addmethod(pyclbr.py):
class Class(_Object):
"Information about a Python class."
def __init__(self, module, name, super, file, lineno, parent=None):
_Object.__init__(self, module, name, file, lineno, parent)
self.super = [] if super is None else super
self.methods = {}
def _addmethod(self, name, lineno):
self.methods[name] = lineno
注意文档中 super 属性的关键细节(pyclbr.rst):"被声明为超类但 readmodule_ex 找不到源码的类,会以类名字符串而非 Class 对象列出"。模块 docstring 补充说明,由于 import 语句会被识别、被导入的模块也会被递归扫描,这种情况"不会经常发生",但消费代码必须对字符串和 Class 两种形态都做处理——IDLE 的 transform_children 正是这样写的(browser.py)。
五、解析原理:基于 token 流与缩进栈的 _create_tree
readmodule_ex 背后的真正工作由两层内部函数完成:_readmodule(定位源码、处理包与点号模块名)和 _create_tree(分词建树)。
5.1 模块定位与点号名称处理
_readmodule(pyclbr.py)的处理顺序:
- 模块缓存:全局字典
_modules(pyclbr.py)按全名缓存已读模块,重复读取直接返回——这也是 IDLE 每次刷新浏览器前调用pyclbr._modules.clear()(browser.py)的原因; - 内建模块:在
sys.builtin_module_names中且不在包内时,直接返回空树(无 Python 源码可读); - 点号模块名:
module.rfind('.')拆出包名与子模块名,先递归读包,确认父树里有'__path__'键,否则抛ImportError('No package named ...'),再以包的__path__作为搜索路径读子模块; - 查找文件:用
importlib.util._find_spec_from_path(fullmodule, search_path)在path + sys.path(包内则为包搜索路径)中查找 spec;是包则写入tree['__path__'];通过spec.loader.get_source()取源码文本,取不到(非 Python 源码)则返回空树。
5.2 缩进栈:识别嵌套层级的核心机制
_create_tree(pyclbr.py)把源码经 tokenize.generate_tokens 变成 token 流,维护一个**`(对象, 缩进) 元组组成的栈**:
- 遇到
DEDENT(或新的def/class)时,弹出所有缩进 ≥ 当前缩进的栈项,实现"回到外层作用域"——嵌套深度完全由缩进决定,这也是为什么 pyclbr 只能处理 Python 而非其他语言; - 遇到顶层(栈空)
def:构造Function(fullmodule, name, fname, lineno)放入tree;遇到栈非空的def:调_nest_function挂到栈顶对象下;class同理走_nest_class; - 遇到
def/class后紧跟的不是NAMEtoken(语法错误的定义)直接跳过,解析器对畸形代码相当宽容。
5.3 基类解析:括号内的 NAME/OP 拼接
class 处理中(pyclbr.py):如果类名后紧跟 (,进入基类扫描循环,用 level 计数括号深度,在 level == 1 时只收集 NAME 与 OP(即点号)token 拼出基类全名;遇到顶层 ) 或 , 时定稿一个基类:
- 名字已在本模块
tree中 → 直接替换为对应Class实例; - 否则若是
module.Class形式,且_modules缓存里有该模块、模块树里有该类 → 也替换为Class实例; - 否则保持字符串(对应
super属性文档中"退化为类名字符串"的行为)。
基类列表里的表达式(如 *SomeMeta 之外的复杂表达式)不支持,docstring 注释明确写了 "Expressions in the base list are not supported."。
5.4 import 语句触发递归扫描
解析器同时追踪 import 与 from ... import(仅限行首 start[1] == 0):
import X:递归_readmodule(X),把 X 及其依赖填进全局_modules缓存(这样后续基类解析才能命中);from X import A, B:递归读 X 后,把其中提到的名字A/B直接复制进当前模块树(tree[n2 or n] = d[n],支持as改名);from X import *则导入所有不以_开头的名字;- 所有递归都包在裸
except里——找不到或解析不了导入模块时静默放弃,绝不让浏览器因第三方模块而崩溃。
六、实战:命令行快速验证与嵌套结构测试
pyclbr.py 自带一个演示入口 _main(pyclbr.py):打印某模块按缩进排列的 class/def 树(含基类与行号)。在仓库内嵌 CPython 的 Lib 目录下可直接运行查看任意模块的结构:
cd kbe/src/lib/python/Lib && python pyclbr.py idlelib.browser
嵌套(3.7 新增能力)的正确性由测试套件 kbe/src/lib/python/Lib/test/test_pyclbr.py 保证,其中有三个值得关注的用例:
test_nested(test_pyclbr.py):用dedent构造一段含"函数套函数再套函数"、"类中类中类"的源码,调用mb._create_tree(m, p, f, source, t, i)后,与手工用mb.Function/mb.Class/_nest_function/_nest_class搭建的期望树做递归深度对比——逐项断言children.keys()相等、每个子对象parent精确指向父节点(assertIs)、(type, name, file, module, lineno)元组一致,以及Class.methods一致。这直接验证了parent/children双向链与lineno的正确性;checkModule主校验(test_pyclbr.py):把readmodule_ex的输出与__import__后的真实模块做交叉比对——顶层函数/类一一对应、基类名列表一致(real_basesvspyclbr_bases)、methods字典与真实__dict__中的方法一致;test_issue_14798(test_pyclbr.py):验证"点号名第一段不是包"时抛ImportError:self.assertRaises(ImportError, pyclbr.readmodule_ex, 'asyncore.foo'),与 5.1 节第 3 步的实现相呼应。
辅助 fixture kbe/src/lib/python/Lib/test/pyclbr_input.py 覆盖了 @classmethod/@staticmethod 装饰器方法、赋值拷贝的函数(om = Other.om 等)——测试注释指出:对装饰器包裹的成员,pyclbr 因为是按文本解析 def 而判对,基于运行时内省的方法反而会误判,这从侧面印证了"文本解析"路线的价值。
七、能力边界小结
结合文档与源码,可以归纳出使用 pyclbr 时应当明确的限制与前提:
- 只读源码、不执行:安全,但对 C 扩展/内建模块只能得到空树(_readmodule 内建模块分支);
- 不支持基类列表中的表达式、不支持装饰器改写成员名的精确内省(见 pyclbr.py 注释与 pyclbr_input.py 注释);
- 模块缓存是全局的:跨目录刷新浏览前需
pyclbr._modules.clear(),否则会拿到旧模块的缓存结果; path参数语义是"前置到sys.path",浏览仓库任意子目录下的脚本时,把其所在目录传入即可,IDLE 的<a href="https://link.gitcode.com/i/32a4254678a42f99f3b9674d84cd95b6" target="_blank">dir] + sys.path写法([browser.py)是标准范例;- 版本前提:
parent/children嵌套能力为 3.7 新增(pyclbr.rst),本仓库内嵌的 CPython 恰为 3.7.3,行为与本文描述完全一致;若在更老的解释器上使用,嵌套定义不会出现在children中。
掌握以上内容后,你可以像 IDLE 一样,用 readmodule_ex + children 递归 + file/lineno 跳转三件套,为任意 Python 项目(例如 KBEngine 服务器资产目录 kbe/res/scripts/ 下的 .py 脚本)快速搭出一个静态、安全的代码结构浏览器。