KBEngine 内嵌 CPython 3.7 的 pyclbr 模块:只读解析源码构建类浏览器的 Function/Class 描述符

原创2026-10-17 17:39:262,287 阅读
文章标签:游戏开发后端

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)的处理顺序:

  1. 模块缓存:全局字典 _modules(pyclbr.py)按全名缓存已读模块,重复读取直接返回——这也是 IDLE 每次刷新浏览器前调用 pyclbr._modules.clear()(browser.py)的原因;
  2. 内建模块:在 sys.builtin_module_names 中且不在包内时,直接返回空树(无 Python 源码可读);
  3. 点号模块名:module.rfind('.') 拆出包名与子模块名,先递归读包,确认父树里有 '__path__' 键,否则抛 ImportError('No package named ...'),再以包的 __path__ 作为搜索路径读子模块;
  4. 查找文件:用 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 后紧跟的不是 NAME token(语法错误的定义)直接跳过,解析器对畸形代码相当宽容。

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 保证,其中有三个值得关注的用例:

  1. 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 的正确性;
  2. checkModule 主校验(test_pyclbr.py):把 readmodule_ex 的输出与 __import__ 后的真实模块做交叉比对——顶层函数/类一一对应、基类名列表一致(real_bases vs pyclbr_bases)、methods 字典与真实 __dict__ 中的方法一致;
  3. 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 脚本)快速搭出一个静态、安全的代码结构浏览器。

登录后查看全文
kbengine