今日三荐：跨方言 SQL 转译、语法树改写与 Python 类型检查

1. sqlglot：把 SQL 读成一棵树，再写回另一种方言

为什么今天看

最值得拆的机制

• 三段式流水线。 一条 SQL 先被 Tokenizer 切成 token，再被 Parser 建成表达式树，最后由 Generator 写回文本。命令行的 --tokenize 和 --parse 正好把前两段单独暴露出来，不写一行 Python 就能看到中间产物。8
• 表达式树就是一棵类树。 Select、Column、Alias、Add、Table 各是一个节点类，节点带 find_all() 这类遍历方法，也带 .sql() 把自己写回文本。官方另写了一篇 AST primer 专门讲这棵树怎么走。810
• 一个方言就是三个挂点。 继承 Dialect 之后，改 Tokenizer 里的引号、标识符定界符和关键字表，改 Generator 里的 TRANSFORMS（节点怎么打印）和 TYPE_MAPPING（类型怎么翻译），一门方言就立起来了。仓库 sqlglot/dialects/ 下每个方言一个文件，可以挑一个短的照抄。8
• 优化器是一组可以单独跑的规则。 sqlglot/optimizer/ 里有 qualify、annotate_types、pushdown_projections、simplify、eliminate_subqueries 等十几条，optimize() 负责按顺序串起来。想改哪条规则，改动面就是那一个文件。8
• executor 用 Python 字典当表。 它能真的把查询跑出来，官方给的定位是够用来做单元测试。想理解「JOIN 和 GROUP BY 到底做了什么」，先在这个小引擎上看一遍，比读真数据库省事。8

复现难度：低

最小上手路径

pip install sqlglot

# 把 DuckDB 的 EPOCH_MS 翻成 Hive 的写法
python -m sqlglot "SELECT EPOCH_MS(1618088028295)" --read duckdb --write hive
# SELECT
#   FROM_UNIXTIME(1618088028295 / POW(10, 3))

# 只看分词结果
python -m sqlglot "SELECT 1" --tokenize
# <Token token_type: TokenType.SELECT, text: SELECT, line: 1, col: 6, ...>

# 只看表达式树
python -m sqlglot "SELECT a, b + 1 AS c FROM d" --parse

今晚练习

1. 挑一句你写过的、带方言特有函数的 SQL，用 --read 和 --write 翻一次，再 --parse 看树；同一句在 --tokenize 和 --parse 两个阶段的差别，正好是「文本」和「结构」的差别。8
2. 在 Python 里 parse_one("SELECT * FROM x JOIN y JOIN z")，用 find_all(exp.Table) 把表名打出来，再用 .sql() 把树写回去。8
3. 读 posts/ast_primer.md 和 posts/python_sql_engine.md 两篇官方长文，它们把一个 SQL 引擎从零拆出来讲，配着这次改动的 sqlglot/optimizer/pushdown_projections.py 一起看。10

版本动作与限制

2. ast-grep：用语法树搜索和改写代码

为什么今天看

最值得拆的机制

• 模式就是代码。 模式本身要能被 tree-sitter 解析成合法代码，ast-grep 把它建成一棵树，再拿去比目标代码的树。所以 print($A) 能跨行跨空格匹配到任意单参数调用，而 print(a, b) 不会命中——一个元变量只吃一个节点。12
• 元变量分几种。 $META 匹配一个具名节点，$$$ARGS 匹配零个到多个节点（函数参数、语句都行），$$VAR 连匿名节点也吃，名字以 _ 开头的元变量只匹配不捕获。同一个名字出现两次就变成等价约束：$A == $A 只命中两边完全相同的比较。12
• 匹配的宽松程度是显式参数。 strictness 从 cst、smart、ast、relaxed、signature 到 template 共六档，默认 smart：模式里的节点必须全部命中，目标代码里的匿名节点（比如 async 这个关键字）可以跳过。这正是 function $A() {} 能同时命中普通函数和 async function 的原因。1314
• 关系规则按上下文选节点。 inside、has、follows、precedes 四个操作符让规则可以写成「在 for 循环里的 await 表达式」，stopBy 控制向上或向下搜索到哪一层停。15
• 规则可以做成一个项目。 YAML 里写 id、language、rule、message、severity，sgconfig.yml 用 ruleDirs 指向规则目录，ast-grep scan 一次跑完，ast-grep test 还能给规则写快照用例。16
• 每个语言一份 JSON Schema。 仓库 schemas/ 下有 29 个文件，Python、TypeScript、Rust、Go、C 各一份，写 YAML 规则时编辑器能直接补全字段名。17

复现难度：低

最小上手路径

# pip 上的包名是 ast-grep-cli，也可以换成 npm install -g @ast-grep/cli 或 brew install ast-grep
pip install ast-grep-cli

# 找一个文件，写一句模式
ast-grep run -p 'print($A)' -l python t2.py
# t2.py:1:print("start")
# t2.py:4:print(value)

# 看模式在 tree-sitter 里被解析成什么
ast-grep run --debug-query=cst -p 'print("start")' -l python t2.py

# 改写默认只预览 diff，加 --update-all 才落盘
ast-grep run -p 'print($A)' -r 'log($A)' -l python t2.py

# rules/no-print.yml
id: no-print
language: Python
severity: warning
message: 用日志代替 print
rule:
  pattern: print($A)

今晚练习

1. 用 $A == $A 在自己的项目里找重复比较，再用 $_FUNC($_FUNC) 找单参数调用；第二条里两个同名元变量因为带下划线不被捕获，各自可以匹配不同内容。12
2. 写一条关系规则，把文档给的例子跑一遍：pattern: await $PROMISE 加上 inside: {kind: for_in_statement, stopBy: end}，它会报出循环里的 await。15
3. 打开在线 playground，同一句模式换几门语言试，顺便看看 --strictness 六档对同一段代码的命中差异。18

版本动作与限制

3. pyrefly：不运行 Python，先推断它会怎么错

为什么今天看

最值得拆的机制

• 求解分三步。 先算出每个模块导出什么（这一步要把 import * 传递地解开），再把每个模块单独转成一组绑定，最后求解绑定——跨模块的部分就去别的模块取值。20
• 绑定图长这样。 键是 define x@1、use x@2、anon @2，@ 后面是标识符在文件里的字节偏移，用来消歧；值是别的键或字面量，所以整张图是一张有向图。20
• 递归和分支汇合都用占位符。 解不动的时候插入一个 Type::Var；控制流汇合处用 phi 合并两个值，phi(int, str) 就是 int | str。对自引用，官方给的做法是取可达上界：x = x 这种循环最后收敛成一个具体类型。20
• 增量只做到模块级。 官方明确说，不学 Roslyn 和 TypeScript 那样先解单个标识符，也不用 Rust Analyzer 那套细粒度增量缓存，理由是把一个模块的绑定整批解完已经够快，代码因此简单得多。20
• crate 按职责切开。 pyrefly_types 定义类型和类型上的运算，pyrefly_graph 负责索引与依赖缓存，pyrefly_config 读配置（顺带迁移 mypy 和 pyright 的配置），pyrefly_bundled 装 typeshed 存根，pyrefly_wasm 是浏览器沙箱。20

复现难度：低（装）／中（读源码）

最小上手路径

pip install pyrefly
pyrefly init                 # 生成 pyrefly.toml，并尝试迁移已有的 mypy/pyright 配置
pyrefly check                # 检查整个项目
pyrefly check --summarize-errors

ERROR Argument `Literal['2']` is not assignable to parameter `y` with type `int` in function `add` [bad-argument-type]
ERROR Object of class `int` has no attribute `missing_attribute` [missing-attribute]
 INFO 2 errors

今晚练习

1. 写一个能让窄化生效的文件：参数标成 str | None，在 if x is None: 分支里直接返回，再调 .upper()，看它是否放行；把判断改成 if x is not None: 再看一次诊断。这一条对应上面的 flow types 设计。20
2. 对一个没标注的函数跑 pyrefly infer，比较它补出来的签名和你心里想的那份差在哪。19
3. 打开 crates 目录，找到「把模块转成绑定」这一步落在哪个 crate，再翻 pyrefly_types 里的 Type::Var 怎么被填上。20

版本动作与限制

怎么选今晚的第一条路径