Python AST抽象语法树深度解析：从ast模块原理到代码生成、静态分析与自动化重构实战

什么是抽象语法树（AST）

抽象语法树（Abstract Syntax Tree，AST）是源代码的一种树形表示形式，它将程序的结构抽象为节点和边的层次结构。在Python中，当你写下一行代码

时，Python解释器并不会直接执行这行文本，而是先将其解析为一棵AST：

1
2
3
4
5
6
7
8
9
10
Module(body=[

  Assign(

    targets=[Name(id='x', ctx=Store())],

    value=BinOp(

      left=Constant(value=1),

      op=Add(),

      right=Constant(value=2)

    )

  )

])

这棵树精确地描述了代码的语义结构：一个赋值语句，左边是变量

，右边是一个二元加法操作，操作数分别是常量1和2。理解AST是深入理解Python运行机制的关键一步，也是实现代码分析、转换和生成工具的基础。

Python的编译过程分为三个阶段：词法分析（Lexing）将源码拆分为token流；语法分析（Parsing）将token流构建为AST；编译（Compilation）将AST编译为字节码。我们今天重点关注的

模块，就工作在语法分析这一层，它提供了完整的AST节点类型定义和遍历、修改AST的工具。

ast模块核心API详解

解析代码为AST

是将源代码字符串转为AST的入口函数。它模拟了Python解释器的解析过程，但只生成AST而不编译为字节码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import ast



# 解析表达式

expr_tree = ast.parse('x + y * 2', mode='eval')



# 解析单个语句

stmt_tree = ast.parse('import os', mode='single')



# 解析完整模块（默认模式）

module_tree = ast.parse('''

def greet(name):

    return f"Hello, {name}!"

''')



print(ast.dump(module_tree, indent=2))

参数对应Python的编译模式：

用于模块（默认）、

用于表达式、

用于交互式语句。选择正确的mode很重要，因为不同模式对语法的接受范围不同。

AST节点的类型体系

Python AST中的每个节点都是

的子类实例。节点类型分为三大类：

• 语句节点（Statement）：

  1	FunctionDef

  、

  1

  ClassDef

  、

  1

  Assign

  、

  1

  Return

  、

  1

  Import

  、

  1

  If

  、

  1

  For

  、

  1

  While

  等

• 表达式节点（Expression）：

  1

  BinOp

  、

  1

  Call

  、

  1

  Name

  、

  1

  Constant

  、

  1

  Attribute

  、

  1

  Subscript

  等

• 辅助节点（Helper）：

  1

  Load

  、

  1

  Store

  、

  1

  Del

  （上下文）、

  1

  Add

  、

  1

  Sub

  （运算符）等

每个节点类型都有特定的属性。例如

有

、

、

、

、

等属性；

有

、

、

三个属性。理解这些属性是操作AST的基础。

一个实用技巧是使用

查看完整的树结构：

1
2
tree = ast.parse('print([x for x in range(10) if x % 2 == 0])')

print(ast.dump(tree, indent=2, show_attributes=True))

遍历AST：NodeVisitor与NodeTransformer

是只读遍历AST的标准方式。它使用访问者模式，你只需为感兴趣的节点类型定义

方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class ImportCollector(ast.NodeVisitor):

    def __init__(self):

        self.imports = []

    

    def visit_Import(self, node):

        for alias in node.names:

            self.imports.append(alias.name)

        self.generic_visit(node)  # 继续遍历子节点

    

    def visit_ImportFrom(self, node):

        for alias in node.names:

            self.imports.append(f"{node.module}.{alias.name}")

        self.generic_visit(node)



collector = ImportCollector()

collector.visit(tree)

print(collector.imports)

继承自

，但它的

方法可以返回新节点来替换原节点，返回

来删除节点：

1
2
3
4
5
6
7
8
9
10
11
class DebugRemover(ast.NodeTransformer):

    """移除所有debugger语句"""

    def visit_Expr(self, node):

        if isinstance(node.value, ast.Call):

            func = node.value.func

            if isinstance(func, ast.Name) and func.id == 'debugger':

                return None  # 删除该语句

        return node



optimized = DebugRemover().visit(tree)

ast.fix_missing_locations(optimized)

重要：使用

修改AST后，必须调用

来补全缺失的行号和列号信息，否则

会报错。

代码生成：用AST动态构建Python代码

AST不仅可以用来分析代码，还可以用来生成代码。这在元编程、代码模板和DSL（领域特定语言）实现中非常有用。相比于字符串拼接生成代码，AST方式能保证生成的代码在语法上总是正确的。

手动构建AST节点

我们可以直接实例化AST节点来构建代码，就像搭积木一样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import ast



# 构建一个简单的函数：def add(a, b): return a + b

func = ast.FunctionDef(

    name='add',

    args=ast.arguments(

        posonlyargs=[],

        args=[

            ast.arg(arg='a', annotation=None),

            ast.arg(arg='b', annotation=None)

        ],

        vararg=None,

        kwonlyargs=[],

        kw_defaults=[],

        kwarg=None,

        defaults=[]

    ),

    body=[

        ast.Return(

            value=ast.BinOp(

                left=ast.Name(id='a', ctx=ast.Load()),

                op=ast.Add(),

                right=ast.Name(id='b', ctx=ast.Load())

            )

        )

    ],

    decorator_list=[],

    returns=None,

    type_comment=None

)



module = ast.Module(body=[func], type_ignores=[])

ast.fix_missing_locations(module)



# 编译并执行

code = compile(module, '<ast>', 'exec')

exec(code)

print(add(3, 5))  # 输出: 8

使用ast.unparse反向生成源码

Python 3.9+提供了

函数，可以将AST转回可读的源代码字符串。这是调试和代码生成的利器：

1
2
3
tree = ast.parse('x = [i**2 for i in range(100) if i % 3 == 0]')

print(ast.unparse(tree))

# 输出: x = [i ** 2 for i in range(100) if i % 3 == 0]

需要特别注意的是，

输出的代码虽然语义等价，但格式可能与原始代码不同——注释会丢失、格式会标准化。它不应该用于”代码美化”工具，而是用于验证你构建或修改的AST是否正确。

实战：自动生成数据验证器

假设我们需要根据一个schema定义自动生成数据验证函数。这是典型的AST代码生成场景：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def generate_validator(class_name: str, fields: dict) -> ast.Module:

    """根据字段定义生成验证类"""

    methods = []

    

    for field_name, field_type in fields.items():

        # 生成验证方法

        method = ast.FunctionDef(

            name=f'validate_{field_name}',

            args=ast.arguments(

                posonlyargs=[],

                args=[ast.arg(arg='self', annotation=None),

                      ast.arg(arg='value', annotation=None)],

                vararg=None, kwonlyargs=[],

                kw_defaults=[], kwarg=None, defaults=[]

            ),

            body=[],

            decorator_list=[],

            returns=None, type_comment=None

        )

        

        # 根据类型添加验证逻辑

        if field_type == 'int':

            method.body = [

                ast.If(

                    test=ast.UnaryOp(

                        op=ast.Not(),

                        operand=ast.Call(

                            func=ast.Name(id='isinstance', ctx=ast.Load()),

                            args=[ast.Name(id='value', ctx=ast.Load()),

                                  ast.Name(id='int', ctx=ast.Load())],

                            keywords=[]

                        )

                    ),

                    body=[ast.Raise(

                        exc=ast.Call(

                            func=ast.Name(id='TypeError', ctx=ast.Load()),

                            args=[ast.Constant(value=f'{field_name} must be int')],

                            keywords=[]

                        ),

                        cause=None

                    )],

                    orelse=[]

                ),

                ast.Return(value=ast.Name(id='value', ctx=ast.Load()))

            ]

        elif field_type == 'str':

            method.body = [

                ast.If(

                    test=ast.UnaryOp(

                        op=ast.Not(),

                        operand=ast.Call(

                            func=ast.Name(id='isinstance', ctx=ast.Load()),

                            args=[ast.Name(id='value', ctx=ast.Load()),

                                  ast.Name(id='str', ctx=ast.Load())],

                            keywords=[]

                        )

                    ),

                    body=[ast.Raise(

                        exc=ast.Call(

                            func=ast.Name(id='TypeError', ctx=ast.Load()),

                            args=[ast.Constant(value=f'{field_name} must be str')],

                            keywords=[]

                        ),

                        cause=None

                    )],

                    orelse=[]

                ),

                ast.Return(value=ast.Name(id='value', ctx=ast.Load()))

            ]

        methods.append(method)

    

    class_def = ast.ClassDef(

        name=class_name,

        bases=[],

        keywords=[],

        body=methods,

        decorator_list=[]

    )

    

    module = ast.Module(body=[class_def], type_ignores=[])

    ast.fix_missing_locations(module)

    return module



# 使用

schema = {'name': 'str', 'age': 'int', 'email': 'str'}

tree = generate_validator('UserValidator', schema)

print(ast.unparse(tree))

静态分析实战：构建自定义Linter

AST最常见的应用场景之一是静态代码分析。与运行时分析不同，静态分析不需要执行代码，仅通过解析AST就能发现潜在问题。这比正则表达式匹配要精确得多，因为AST精确地反映了代码的语义结构。

检测不安全的函数调用

假设我们需要检测代码中是否存在潜在不安全的函数调用，例如

、

、

等：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
class SecurityChecker(ast.NodeVisitor):

    DANGEROUS_CALLS = {

        'eval': '使用eval()存在代码注入风险',

        'exec': '使用exec()存在代码注入风险',

        'compile': '使用compile()可能存在安全风险',

    }

    DANGEROUS_ATTRS = {

        ('subprocess', 'call'): '建议使用subprocess.run()并设置shell=False',

        ('os', 'system'): '建议使用subprocess.run()替代os.system()',

        ('pickle', 'loads'): 'pickle反序列化存在安全风险',

    }

    

    def __init__(self):

        self.issues = []

    

    def visit_Call(self, node):

        # 检查直接函数调用

        if isinstance(node.func, ast.Name):

            if node.func.id in self.DANGEROUS_CALLS:

                self.issues.append({

                    'line': node.lineno,

                    'message': self.DANGEROUS_CALLS[node.func.id],

                    'code': ast.unparse(node)

                })

        

        # 检查属性调用

        if isinstance(node.func, ast.Attribute):

            if isinstance(node.func.value, ast.Name):

                key = (node.func.value.id, node.func.attr)

                if key in self.DANGEROUS_ATTRS:

                    self.issues.append({

                        'line': node.lineno,

                        'message': self.DANGEROUS_ATTRS[key],

                        'code': ast.unparse(node)

                    })

        

        self.generic_visit(node)



# 测试

source = '''

import os, subprocess, pickle



data = eval(user_input)

os.system("ls -la")

result = pickle.loads(raw_bytes)

'''



checker = SecurityChecker()

checker.visit(ast.parse(source))

for issue in checker.issues:

    print(f"Line {issue['line']}: {issue['message']}")

    print(f"  Code: {issue['code']}")

复杂度分析：圈复杂度计算

McCabe圈复杂度是衡量函数复杂程度的经典指标。通过AST，我们可以精确计算它——每遇到一个分支点（if、for、while、and、or等）复杂度加1：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
class ComplexityCalculator(ast.NodeVisitor):

    BRANCH_NODES = (

        ast.If, ast.For, ast.While, ast.ExceptHandler,

        ast.With, ast.Assert

    )

    BOOL_OPS = (ast.And, ast.Or)

    

    def __init__(self):

        self.functions = {}

    

    def visit_FunctionDef(self, node):

        complexity = 1  # 基础复杂度

        for child in ast.walk(node):

            if isinstance(child, self.BRANCH_NODES):

                complexity += 1

            elif isinstance(child, ast.BoolOp):

                # 每个and/or操作增加1

                complexity += len(child.values) - 1

        

        self.functions[node.name] = {

            'complexity': complexity,

            'line': node.lineno,

            'risk': 'high' if complexity > 10 else 'medium' if complexity > 5 else 'low'

        }

        self.generic_visit(node)

    

    # Python 3.12+ 用 visit_TypeAlias 替代

    visit_AsyncFunctionDef = visit_FunctionDef



source = '''

def process_data(items, threshold, flag):

    result = []

    for item in items:

        if item.value > threshold and item.active:

            if flag:

                result.append(item.transform())

            elif item.priority == "high":

                result.append(item)

            else:

                try:

                    result.append(item.fallback())

                except ValueError:

                    pass

    return result

'''



calc = ComplexityCalculator()

calc.visit(ast.parse(source))

for name, info in calc.functions.items():

    print(f"{name}: complexity={info['complexity']}, risk={info['risk']}")

自动化重构实战：代码转换与迁移

AST最强大的应用之一是自动化代码重构。通过

，我们可以精确地定位并修改代码结构，而不需要手动逐文件查找替换。这比正则表达式安全得多，因为正则表达式无法区分字符串内容与代码、无法理解嵌套结构。

实战：将%格式化迁移到f-string

Python 3.6引入的f-string已经成为了字符串格式化的首选方式，但大量遗留代码仍在使用

格式化或

。我们可以用AST自动完成这个迁移：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
class PercentToFString(ast.NodeTransformer):

    """将 '%s' % x 转换为 f'{x}'"""

    

    def visit_BinOp(self, node):

        # 先处理子节点

        node = self.generic_visit(node)

        

        # 检查是否是 % 格式化

        if not isinstance(node.op, ast.Mod):

            return node

        if not isinstance(node.left, ast.Constant):

            return node

        if not isinstance(node.left.value, str):

            return node

        

        template = node.left.value

        

        # 处理简单的 %s 格式化

        if isinstance(node.right, ast.Tuple):

            values = node.right.elts

        elif isinstance(node.right, ast.Name):

            values = [node.right]

        else:

            return node  # 复杂情况不处理

        

        # 将 %s 替换为 {}

        parts = template.split('%s')

        if len(parts) - 1 != len(values):

            return node  # 数量不匹配，跳过

        

        # 构建 f-string JoinedStr

        values_iter = iter(values)

        fstring_values = []

        

        for part in parts:

            if part:

                fstring_values.append(

                    ast.Constant(value=part)

                )

            try:

                val = next(values_iter)

                fstring_values.append(

                    ast.FormattedValue(

                        value=val,

                        conversion=-1,

                        format_spec=None

                    )

                )

            except StopIteration:

                pass

        

        joined_str = ast.JoinedStr(values=fstring_values)

        return ast.copy_location(joined_str, node)



# 测试

source = '''

name = "World"

greeting = "Hello, %s!" % name

info = "%s is %s years old" % (name, age)

'''



tree = ast.parse(source)

transformed = PercentToFString().visit(tree)

ast.fix_missing_locations(transformed)

print(ast.unparse(transformed))

# 输出:

# name = 'World'

# greeting = f'Hello, {name}!'

# info = f'{name} is {age} years old'

实战：自动添加类型注解

对于没有类型注解的遗留代码，我们可以通过分析函数体内的操作和返回值来推断类型，并自动添加注解：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
class TypeInferrer(ast.NodeTransformer):

    """基于启发式规则推断并添加类型注解"""

    

    def visit_FunctionDef(self, node):

        # 收集函数体内的类型线索

        type_hints = {}

        

        for child in ast.walk(node):

            # 数字运算 → int/float

            if isinstance(child, ast.BinOp) and isinstance(child.op, (ast.Add, ast.Sub, ast.Mult)):

                if isinstance(child.left, ast.Constant) and isinstance(child.left.value, int):

                    type_hints.setdefault('return', 'int')

            

            # 字符串连接 → str

            if isinstance(child, ast.BinOp) and isinstance(child.op, ast.Mod):

                if isinstance(child.left, ast.Constant) and isinstance(child.left.value, str):

                    type_hints.setdefault('return', 'str')

            

            # return 语句分析

            if isinstance(child, ast.Return) and child.value:

                if isinstance(child.value, ast.Name) and child.value.id in type_hints:

                    type_hints['return'] = type_hints[child.value.id]

                elif isinstance(child.value, ast.Constant):

                    if isinstance(child.value.value, int):

                        type_hints.setdefault('return', 'int')

                    elif isinstance(child.value.value, str):

                        type_hints.setdefault('return', 'str')

                    elif isinstance(child.value.value, bool):

                        type_hints['return'] = 'bool'

        

        # 添加返回类型注解

        if 'return' in type_hints:

            node.returns = ast.Name(id=type_hints['return'], ctx=ast.Load())

        

        self.generic_visit(node)

        return node



# 测试

source = '''

def add_numbers(a, b):

    return a + b



def greet(name):

    return "Hello, " + name



def is_valid(data):

    return data is not None

'''



tree = ast.parse(source)

transformed = TypeInferrer().visit(tree)

ast.fix_missing_locations(transformed)

print(ast.unparse(transformed))

AST编译与执行的安全考量

使用

将AST编译为代码对象并执行时，有一些重要的安全注意事项：

是一个特别有用的安全函数，它只接受Python字面量（字符串、数字、元组、列表、字典、布尔值和None），会拒绝任何函数调用、属性访问或运算：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import ast



# 安全：只解析字面量

ast.literal_eval("{'a': 1, 'b': [2, 3]}")  # {'a': 1, 'b': [2, 3]}



# 不安全：拒绝执行

class Dangerous(ast.NodeTransformer):

    def visit_Expr(self, node):

        # 永远不要在未验证的AST上使用compile + exec

        return node



# ast.literal_eval 会拒绝这些：

# ast.literal_eval("os.system('rm -rf /')")  # ValueError!

# ast.literal_eval("__import__('os').system('ls')")  # ValueError!

AST验证：防止代码注入

当你需要对AST做

时（比如代码生成场景），必须先验证AST中不包含危险节点：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
SAFE_NODES = {

    ast.Module, ast.FunctionDef, ast.ClassDef, ast.Return,

    ast.Assign, ast.AugAssign, ast.For, ast.While, ast.If,

    ast.Expr, ast.Pass, ast.Break, ast.Continue,

    ast.BinOp, ast.UnaryOp, ast.BoolOp, ast.Compare,

    ast.Call, ast.Constant, ast.Name, ast.List, ast.Dict,

    ast.Tuple, ast.Set, ast.Subscript, ast.Attribute,

    ast.Str, ast.Num, ast.FormattedValue, ast.JoinedStr,

    ast.arg, ast.arguments, ast.Add, ast.Sub, ast.Mult,

    ast.Div, ast.Mod, ast.Pow, ast.Eq, ast.NotEq,

    ast.Lt, ast.LtE, ast.Gt, ast.GtE, ast.And, ast.Or,

    ast.Not, ast.Load, ast.Store, ast.Del

}



def validate_ast(node):

    """递归验证AST中只包含安全节点"""

    for child in ast.walk(node):

        if type(child) not in SAFE_NODES:

            raise ValueError(f"不安全的AST节点: {type(child).__name__}")

    

    # 额外检查：禁止import和危险函数调用

    for child in ast.walk(node):

        if isinstance(child, (ast.Import, ast.ImportFrom)):

            raise ValueError("禁止import语句")

        if isinstance(child, ast.Call):

            if isinstance(child.func, ast.Name):

                if child.func.id in ('eval', 'exec', 'compile', '__import__', 'open'):

                    raise ValueError(f"禁止调用: {child.func.id}")

    return True



# 使用

try:

    tree = ast.parse(user_provided_code)

    validate_ast(tree)

    code = compile(tree, '<validated>', 'exec')

    exec(code, {'__builtins__': {}})  # 限制内置函数

except ValueError as e:

    print(f"安全检查失败: {e}")

性能优化与高级技巧

AST缓存与增量分析

对于大型项目，每次全量解析所有文件会很慢。我们可以利用

的结果做缓存，只在文件修改时重新解析：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import ast, hashlib, os, pickle

from pathlib import Path



class CachedAnalyzer:

    def __init__(self, cache_dir='.ast_cache'):

        self.cache_dir = Path(cache_dir)

        self.cache_dir.mkdir(exist_ok=True)

    

    def get_ast(self, filepath):

        """获取文件的AST，优先使用缓存"""

        content = Path(filepath).read_text()

        content_hash = hashlib.sha256(content.encode()).hexdigest()

        cache_file = self.cache_dir / f"{content_hash}.pkl"

        

        if cache_file.exists():

            with open(cache_file, 'rb') as f:

                return pickle.load(f)

        

        tree = ast.parse(content, filename=filepath)

        with open(cache_file, 'wb') as f:

            pickle.dump(tree, f)

        return tree

    

    def analyze_project(self, project_dir):

        """增量分析整个项目"""

        results = []

        for py_file in Path(project_dir).rglob('*.py'):

            tree = self.get_ast(py_file)

            checker = SecurityChecker()

            checker.visit(tree)

            results.extend([

                {**issue, 'file': str(py_file)}

                for issue in checker.issues

            ])

        return results

多文件AST分析

实际项目分析需要跨文件理解依赖关系。我们可以先用AST收集所有import信息，构建依赖图，再进行跨文件分析：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
from collections import defaultdict



class DependencyGraphBuilder(ast.NodeVisitor):

    """构建Python项目的模块依赖图"""

    

    def __init__(self):

        self.dependencies = defaultdict(set)

        self.current_module = None

    

    def analyze_file(self, filepath, module_name=None):

        self.current_module = module_name or Path(filepath).stem

        tree = ast.parse(Path(filepath).read_text())

        self.visit(tree)

    

    def visit_Import(self, node):

        for alias in node.names:

            self.dependencies[self.current_module].add(alias.name)

        self.generic_visit(node)

    

    def visit_ImportFrom(self, node):

        if node.module:

            self.dependencies[self.current_module].add(node.module)

        self.generic_visit(node)

    

    def get_dependents(self, module):

        """获取所有依赖指定模块的模块"""

        return {m for m, deps in self.dependencies.items() if module in deps}

    

    def get_dependency_order(self):

        """拓扑排序，返回分析顺序"""

        visited = set()

        order = []

        

        def dfs(module):

            if module in visited:

                return

            visited.add(module)

            for dep in self.dependencies.get(module, set()):

                dfs(dep)

            order.append(module)

        

        for module in self.dependencies:

            dfs(module)

        return order

生态工具与框架

Python AST生态中有许多优秀的工具和框架，了解它们可以帮助你在合适的场景选择合适的工具，避免重复造轮子：

一个重要的区别是AST vs CST（具体语法树）。Python标准库的

模块生成的是抽象语法树——它丢弃了注释、空行、括号位置等格式信息。如果你需要保留这些信息（比如做代码格式化工具），应该使用Instagram的LibCST库，它生成的是具体语法树，能够精确地保留源码的每一个细节。

1
2
3
4
5
6
7
8
9
10
11
12
# LibCST 保留格式信息

import libcst as cst



source = """

# 这是一个重要的注释

def hello():

    x = 1    # 行内注释

    return x

"""



tree = cst.parse_module(source)

print(tree.code)  # 完整保留注释和格式

实战总结与最佳实践

通过上面的实战示例，我们已经覆盖了AST的核心应用场景。这里总结一些最佳实践和常见陷阱：

• 优先使用

  1	ast.literal_eval()

  ——如果你只需要解析JSON-like的配置数据，

  1	literal_eval

  是安全且高效的选择，永远不要对用户输入使用

  1

  eval()

• 修改AST后必须调用

  1	ast.fix_missing_locations()

  ——否则

  1

  compile()

  会报

  1	ValueError: malformed node

  错误

• 使用

  1	ast.copy_location()

  保留位置信息——替换节点时，将原节点的位置信息复制到新节点上，有助于后续的错误报告和调试

• 不要忽略

  1	generic_visit()

  ——在

  1	NodeVisitor

  中，如果你忘记调用

  1	generic_visit(node)

  ，子节点将不会被遍历

• NodeTransformer可以返回列表——如果一个

  1

  visit_*

  方法返回一个节点列表，这些节点将替换原节点。这在展开循环或内联函数时很有用

• 注意Python版本差异——AST节点类型在不同Python版本间有变化。例如Python 3.8将

  1

  ast.Str

  /

  1

  ast.Num

  统一为

  1	ast.Constant

  ；Python 3.12引入了

  1	ast.TypeAlias

  等新节点

• 复杂重构考虑使用LibCST——当你需要保留注释和格式时，标准库的

  1

  ast

  模块会丢失这些信息，LibCST是更好的选择

Python的AST是一个强大但常被低估的工具。掌握它不仅能让你深入理解Python的运行机制，还能让你构建出强大的代码分析、转换和生成工具——从简单的命名规范检查器到复杂的自动重构引擎，AST都是最可靠的基础设施。希望本文的实战示例能帮助你将AST技术应用到自己的项目中。