Skip to main content

Chapter 23: AST and Symbol Table

核心问题与阅读主线

本章导读5 个核心小节 · 附自检与总结

Python 源码经过 tokenizer 和 PEG parser 之后,编译器已经得到结构化语法信息。本章追踪下一段交接:AST 如何把源码组织成语句、表达式和名字节点,symbol table 如何在 AST 上计算每个名字的作用域属性,后续编译状态如何据此生成局部变量、闭包变量和全局名字访问。

读完本章后,读者应能拿到一段包含嵌套函数、global、nonlocal、赋值和读取的 Python 代码,判断每个名字在当前 block 中属于 local、global、free 还是 cell,并能解释这些分类如何进入 code object metadata。这里的判断目标是编译前半段的语义准备,后续 Chapter 24 再展开 CFG 和 bytecode generation。

全章共用代码样本(下文各节持续拆解)

贯穿材料核心代码

本章以同一段代码贯穿 AST、symbol table 和 compiler state 边界。代码刻意包含模块变量、外层函数参数、外层局部变量、内层函数、nonlocal 声明和跨作用域读取:

VALUE = 10

def outer(step):
total = 0

def inner(item):
nonlocal total
total += item + step + VALUE
return total

return inner

这段代码在运行时会产生闭包,但闭包布局在执行前已经由编译阶段决定。AST 先表达“哪里有函数定义、赋值、名字读取和名字写入”,symbol table 再表达“每个 block 拥有哪些名字、哪些名字需要从外层捕获、哪些名字留给 globals/builtins 查找”。CPython 的 ast 文档、symtable 文档 和 InternalDocs compiler.md 都把这条链路放在 bytecode 生成之前;本文按这个顺序建立最小充分模型。

23.1 AST as structured syntax​

AST(Abstract Syntax Tree)是编译器看到的结构化语法对象。它把源码里的文本顺序转换成节点关系:module 包含语句列表,function definition 包含参数、函数体和装饰器,assignment 包含 target 和 value,name expression 记录名字文本和读写上下文。AST 的直接输入来自 parser,直接输出交给 symbol table 分析和后续 code generation。

在贯穿代码中,模块层 AST 的主干可以按对象关系阅读:Module.body 中先出现一个 Assign,再出现一个 FunctionDef。Assign 的 target 是 Name(id="VALUE", ctx=Store()),value 是 Constant(value=10)。FunctionDef(name="outer") 的参数里有 step,函数体中又包含 Assign(total = 0)、内部 FunctionDef(name="inner") 和 Return(Name("inner"))。内部函数体里有 Nonlocal(names=["total"])、AugAssign(total += ...) 和 Return(total)。

这个结构说明 AST 已经丢掉一部分源码表层细节,同时保留编译需要的结构信息。括号、缩进文本、空行、注释等表层形式通常已经退场;语句边界、表达式嵌套、目标位置、读取位置、源码 location 仍然保留。AST 节点的 _fields 描述子节点字段,lineno、col_offset、end_lineno、end_col_offset 让错误报告、调试信息和 location table 有来源。Python 3.14 文档中的 AST 节点还暴露 _field_types,这类字段属于版本敏感接口,阅读时应以目标 Python 版本文档为准。

用 Python 层 API 可以观察这个结构:

import ast

source = """
VALUE = 10

def outer(step):
total = 0

def inner(item):
nonlocal total
total += item + step + VALUE
return total

return inner
"""

tree = ast.parse(source)
print(ast.dump(tree, indent=4))

这段代码展示的是 Python 层 ast.AST 对象视图。CPython 内部编译器使用的是 ASDL 生成的 C 结构,例如 stmt_ty、expr_ty 和相关序列结构;Python 层 ast 模块提供可检查、可变换的公开接口。两者在节点形状上对应同一套抽象语法定义,内存表示和 API 责任不同。

AST 的关键读法是先看节点类型,再看字段语义,最后看 ctx。Name(id="total", ctx=Store()) 表示这个名字处在写入位置,Name(id="total", ctx=Load()) 表示它处在读取位置。AugAssign 同时涉及读取旧值和写回新值,但 target 的 AST context 仍然是 store 位置;symbol table 会结合 nonlocal total 把这个写入归入外层绑定。

AST 本身表达 syntax structure,它尚未完成全部 scope 决策。Name("VALUE") 在 AST 上只说明这里读取了一个名字,后续分析才决定它走 local、free、global 还是 builtin 查找。这个边界能解释很多编译期现象:语法树已经有名字节点,名字的执行期访问方式仍要等待 symbol table 和 compiler state 决定。

本节的可复用判断顺序是:先找 AST root,例如 Module、Expression 或 Interactive;再按 statement 和 expression 节点展开子字段;接着检查 Name.ctx、Global、Nonlocal、FunctionDef、ClassDef 等会影响名字归属的节点;最后把这些结构交给 symbol table 解释作用域。

23.2 Symbol table and scope analysis​

Symbol table 是编译器为每个 code block 建立的名字分类表。一个 block 可以是 module、function、class,以及较新版本中为 annotation scope、type alias、type parameter 等语法建立的特殊 scope。symbol table 的输入是 AST,输出是每个 block 的 symbol 集合、嵌套 block 关系和每个 symbol 的分类标记。

贯穿代码中至少有三个主要 block:模块 block、outer function block、inner function block。模块 block 绑定 VALUE 和 outer。outer block 绑定参数 step、局部变量 total、局部函数名 inner。inner block 绑定参数 item,声明 total 为 nonlocal,读取 step 和 VALUE。这些结论来自编译期静态分析,执行 outer() 前就已经确定。

可以把这段代码的 symbol table 结果压缩成同一组维度:

BlockName关键分类判断依据
moduleVALUElocal + global模块级赋值会写入模块 namespace,同时对函数内解析而言属于 global 层
moduleouterlocal + global + namespacedef outer 在模块 namespace 绑定函数名,并产生子 block
outerstepparameter + local,后续成为 cell参数属于当前函数 local;内层 inner 读取它
outertotallocal,后续成为 cell当前函数赋值;内层 inner 通过 nonlocal 写入它
outerinnerlocal + namespace内部函数定义在 outer local namespace 绑定名字,并产生子 block
inneritemparameter + local内层函数参数由当前 block 自己绑定
innertotalnonlocal + freenonlocal total 指向外层函数绑定,当前 block 使用闭包访问
innerstepfree当前 block 读取,外层函数绑定,当前 block 通过闭包访问
innerVALUEglobal当前函数和外层函数均无绑定声明,解析留给 module globals 和 builtins

这个表揭示了 symbol table 和 runtime namespace 的交接。module block 的 local namespace 就是模块字典;function block 的 local 名字多数进入 fast locals 布局;free 变量从外层 cell 读取;global 名字在运行时通过 globals/builtins 查找。编译器用这些分类选择后续 name operation 的生成方式。

global 和 nonlocal 的作用发生在 symbol table 分析阶段。global VALUE 会把当前 block 对 VALUE 的绑定或读取指向模块层名字;nonlocal total 要求外层非 global block 中存在对应绑定,并把当前 block 的访问归入 free variable。声明与赋值冲突、nonlocal 找不到外层绑定等错误也在这类分析中被发现。

CPython 源码阅读时,symbol table 相关主入口可以按固定顺序定位:Python/symtable.c 中 _PySymtable_Build() 建立符号表,访问 AST 时会进入不同 symtable_visit_* 分支,遇到函数、类、comprehension 或 annotation 相关结构时进入新 block,退出时收束当前 block 的名字分类。公开的 symtable 模块是观察这张表的 Python 层接口,适合验证分类,但它展示的是编译器分析结果的接口化视图。

判断一个名字的 scope 时,稳定顺序是:先确认它所在 block;再检查该 block 内是否有参数、赋值、for target、except target、with as target、import 或函数/class 定义绑定;接着检查 global 和 nonlocal 声明;然后检查是否被嵌套 block 引用;最后决定它在当前 block 中属于 local、global、free,或在外层 block 中升级为 cell。

23.3 Free variable analysis and compiler metadata​

Free variable analysis 解决闭包布局问题。free variable 指当前 block 使用但由外层 function block 绑定的名字。cell variable 指当前 block 自己绑定,同时需要被嵌套 block 捕获的名字。二者共同决定 code object 中的 co_freevars、co_cellvars,也决定运行时函数对象如何保存 closure cells。

贯穿代码中,inner 读取 step,并通过 nonlocal total 读写 total。从 inner 的角度看,step 和 total 都是 free variables。换到 outer 的角度看,step 和 total 都需要成为 cell variables,因为 inner 的 code object 需要在 outer 返回后仍能通过 cell 访问它们。

这个关系可以画成一个编译期到运行期的交接图:

图中的核心边界是:symbol table 只分类名字,后续 code generation 才根据分类生成具体访问指令。inner 中读取 step 的表达式仍然是一个 Name 节点,compiler state 会根据 symbol table 把它当作 closure dereference 处理。inner 中写入 total 的 AugAssign 也会在 name operation 阶段结合 nonlocal 分类,生成对 closure cell 的读写。

闭包元数据进入 code object 后,runtime 才能构造函数对象。执行 outer(step) 时,frame 中的 step 和 total 对应 cell;执行到 def inner 时,CPython 创建 inner function object,并把这些 cell 放入它的 closure。outer 返回后,outer frame 可以结束,cells 仍由 inner function object 持有。这个结果看起来像运行期行为,前提布局来自编译期 symbol table 和 code object metadata。

class block 需要单独标注边界。函数内部的 nested function 会沿 enclosing function scope 捕获 free variables;class body 虽然也会产生 namespace,但方法体中的普通名字查找不会把 class namespace 当作 enclosing function locals 使用。Python 3.14 的 symtable.Symbol.is_free_class() 文档专门描述了 class scope 对 method 视角的特殊 free 行为。读源码时,class、function、comprehension 和 annotation scope 的差异应分开判断。

一个实用的闭包判断顺序是:先在最内层 block 找到读取或写入的 name;再向外寻找最近的 function block 绑定;如果当前 block 声明了 nonlocal,必须命中外层 function block;如果当前 block 只读取外层绑定,该名字在当前 block 中是 free;如果外层 block 的 local 被内层 free 引用,外层名字成为 cell。这个顺序能直接解释 UnboundLocalError、闭包共享状态和 nonlocal 修改外层变量的编译期基础。

23.4 AST transformation and validation​

AST transformation 是在结构化语法层修改程序。它可以替换表达式、插入语句、重写函数体、添加 location 信息,也可以用于静态分析、代码生成和工具链处理。它的边界同样明确:转换后的树必须满足目标 Python 版本的 AST schema、字段完整性、上下文合法性和源码位置要求。

下面的例子把读取位置的 VALUE 替换成常量 10。它只修改 Load 场景下的 Name,保留赋值目标中的 VALUE。ast.copy_location() 把原节点位置复制到新节点,ast.fix_missing_locations() 补齐转换中新建节点缺少的位置字段。

import ast

class InlineValue(ast.NodeTransformer):
def visit_Name(self, node):
if node.id == "VALUE" and isinstance(node.ctx, ast.Load):
return ast.copy_location(ast.Constant(value=10), node)
return node

tree = ast.parse(source)
new_tree = InlineValue().visit(tree)
new_tree = ast.fix_missing_locations(new_tree)
code = compile(new_tree, "example.py", "exec")
判断链条

这个转换能通过 validation 的前提有三点。

01

步骤 1

Constant 是表达式节点,可以放在读取表达式位置。

02

步骤 2

它只替换 Load 场景,没有把赋值 target 改成常量。

03

步骤 3

新节点带有可用 location。

AST validation 关注结构约束。表达式位置需要表达式节点,语句列表需要语句节点,赋值 target 需要合法 store context,del target 需要 delete context,必填字段需要存在,列表字段需要是列表,optional 字段允许为空。Python 3.13 起构造 AST 节点时一些省略字段有默认处理;Python 3.15 起缺少必需字段和任意额外字段的兼容行为会收紧。工程上处理 AST 时应把目标 Python 版本写清楚。

AST transformation 也会影响 symbol table。把 Name("VALUE", Load()) 改成 Constant(10) 后,inner block 对 VALUE 的 global reference 消失;把一个新的 Name("extra", Load()) 插入表达式后,symbol table 会把它归入 local/free/global 的某一类。转换工具如果只关注树形结构,生成的代码可能在名字解析阶段出现新的失败。因此 AST rewrite 的检查顺序应包含结构检查和名字分类复查。

CPython 源码中,Python/ast.c 负责 AST validation,Python/ast_preprocess.c 负责部分编译前预处理,Python/symtable.c 再基于 AST 建立 symbol table。公开 API 中,compile(ast_tree, filename, mode) 是把 Python 层 AST 交回编译器的入口。只要使用这个入口,转换后的树就会重新经历 validation、symbol table 和后续编译流程。

23.5 AST to compiler state boundary​

AST 到 compiler state 的边界,是从“源码结构”进入“可生成指令的编译状态”。AST 告诉编译器当前节点是什么结构;symbol table 告诉编译器每个名字应该按哪类 scope 处理;compiler state 保存当前 unit、当前 block、常量表、名字表、变量布局、location 和待生成的 instruction sequence。后续 CFG 和 bytecode 在 Chapter 24 中继续展开。

这条边界可以压缩成一条稳定路径:

在 CPython InternalDocs 描述的链路中,_PyAST_Compile() 触发 AST 到 code object 的编译;第一步构造 symbol table;随后 compiler_codegen() 把 AST 转成 pseudo instructions;再通过 flowgraph 和 assemble 阶段形成 bytecode 与 PyCodeObject。源码入口可按 Python/compile.c、Python/symtable.c、Python/flowgraph.c、Python/assemble.c 这组文件阅读。

名字访问正好体现这个边界。AST 中的 Name(id="item", ctx=Load())、Name(id="step", ctx=Load())、Name(id="VALUE", ctx=Load()) 看起来结构相似,但 symbol table 分类不同。compiler state 在生成 name operation 时会结合 expr context 和 scope 分类:item 走当前函数 local,step 走 closure free variable,VALUE 走 global lookup。相同 AST 节点类型经过不同 scope metadata,会进入不同 runtime access path。

location 信息也在这个边界交接。AST 节点上的 lineno 和 column offset 让后续 instruction、exception table、traceback 和调试信息能回到源码位置。合成节点如果缺少 location,工具可以用 fix_missing_locations() 补齐;CPython 内部生成的合成指令也可能使用无源码位置的 location。阅读编译器源码时,应把“语义结构”和“源码定位”分成两个字段族看。

本章最终建立的判断模型是:AST 负责表达语法树,symbol table 负责计算名字的 scope,compiler state 负责把节点结构和 scope metadata 合并成可生成指令的状态。遇到编译期疑问时,先判断问题属于 AST 结构、scope classification、AST validation、compiler state 还是后续 CFG/bytecode。这个分层能防止把闭包、全局查找、语法形状和 opcode 选择混在同一个解释里。

最小自检任务​

动手自检先独立判断

阅读下面代码,判断 factory、base、factor、value、LIMIT 在各自 block 中的分类,并说明哪些名字会进入 closure metadata。

LIMIT = 100

def factory(base):
factor = 2

def scale(value):
return min(value * factor + base, LIMIT)

return scale

要求按顺序回答:模块 block 中有哪些绑定;factory block 中哪些名字是 local;scale block 中哪些名字是 local、free、global;factory code object 中哪些名字应成为 cell variables;scale code object 中哪些名字应成为 free variables。

本章知识点总结​

  • AST 角色

    AST 把源码转换成语句、表达式、名字和字段组成的结构化语法对象。

  • 节点字段

    AST 节点通过字段表达子节点关系,通过 location 字段保留源码定位信息。

  • 名字上下文

    Name.ctx 区分读取、写入和删除位置,是后续名字分类的重要输入。

  • 结构边界

    AST 表达源码结构,scope 决策由 symbol table 在 AST 之上完成。

  • Block 分类

    symbol table 为 module、function、class 和特殊 scope 建立独立名字表。

  • Local 判断

    参数、赋值 target、导入名、函数名和 class 名都会在当前 block 中形成绑定。

  • Nonlocal 判断

    nonlocal 把当前 block 的名字访问指向外层 function block 中已有绑定。

  • Free 变量

    当前 block 使用外层 function block 绑定的名字时,该名字在当前 block 中属于 free variable。

  • Cell 变量

    当前 block 的 local 被嵌套 block 捕获时,该名字在当前 block 中成为 cell variable。

  • 闭包元数据

    co_cellvars 和 co_freevars 来自编译期 scope classification,并支撑运行时 closure cells。

  • AST 转换

    AST rewrite 必须保持节点类型、字段完整性、context 和 location 的结构约束。

  • 编译边界

    compiler state 把 AST 结构和 symbol table metadata 合并成后续 pseudo instructions、CFG 和 bytecode 的输入。