0
# Core Parsing and Building
1
2
Primary functions and classes for converting Python source code and objects into astroid AST trees. These functions serve as the main entry points for creating astroid representations from various sources.
3
4
## Capabilities
5
6
### Source Code Parsing
7
8
Parse Python source code strings into astroid AST trees with full inference capabilities.
9
10
```python { .api }
11
def parse(code: str, module_name: str = "", path: str | None = None, apply_transforms: bool = True) -> nodes.Module:
12
"""
13
Parse Python source code into an astroid Module.
14
15
Parameters:
16
- code: Python source code to parse
17
- module_name: Name to assign to the created module
18
- path: File path for the source (used in error messages)
19
- apply_transforms: Whether to apply registered transforms
20
21
Returns:
22
Module node representing the parsed code
23
24
Raises:
25
AstroidSyntaxError: If the code contains syntax errors
26
"""
27
```
28
29
Usage example:
30
```python
31
import astroid
32
33
code = '''
34
def add(a, b):
35
return a + b
36
37
x = add(1, 2)
38
'''
39
40
module = astroid.parse(code, module_name="example")
41
print(f"Module name: {module.name}")
42
print(f"Number of statements: {len(module.body)}")
43
```
44
45
### Node Extraction
46
47
Extract specific nodes from source code using special markers, useful for testing and focused analysis.
48
49
```python { .api }
50
def extract_node(code: str, module_name: str = "") -> nodes.NodeNG | list[nodes.NodeNG]:
51
"""
52
Extract nodes from code using #@ markers or __() wrappers.
53
54
Parameters:
55
- code: Source code with extraction markers
56
- module_name: Name for the containing module
57
58
Returns:
59
Single node or list of nodes marked for extraction
60
61
Raises:
62
AstroidSyntaxError: If extraction markers are malformed
63
"""
64
```
65
66
Usage example:
67
```python
68
import astroid
69
70
# Using #@ marker
71
code_with_marker = '''
72
def func():
73
return 42 #@
74
'''
75
76
node = astroid.extract_node(code_with_marker)
77
print(f"Extracted node: {type(node).__name__}")
78
79
# Using __() wrapper
80
code_with_wrapper = '''
81
def func():
82
return __(42)
83
'''
84
85
node = astroid.extract_node(code_with_wrapper)
86
print(f"Extracted constant value: {node.value}")
87
```
88
89
### AstroidBuilder Class
90
91
Core builder class for creating astroid trees from various sources including files, strings, modules, and classes.
92
93
```python { .api }
94
class AstroidBuilder:
95
"""Builder for astroid AST trees from various sources."""
96
97
def __init__(self, manager: AstroidManager | None = None, apply_transforms: bool = True) -> None:
98
"""Initialize builder with optional manager and transform settings."""
99
100
def file_build(self, path: str, modname: str | None = None) -> nodes.Module:
101
"""
102
Build astroid tree from a Python file.
103
104
Parameters:
105
- path: Path to Python source file
106
- modname: Name for the module (defaults to filename)
107
108
Returns:
109
Module node representing the file contents
110
111
Raises:
112
AstroidBuildingError: If file cannot be read or parsed
113
"""
114
115
def string_build(self, data: str, modname: str = "", path: str | None = None) -> nodes.Module:
116
"""
117
Build astroid tree from source string.
118
119
Parameters:
120
- data: Python source code
121
- modname: Name for the module
122
- path: Optional file path for error reporting
123
124
Returns:
125
Module node representing the source code
126
127
Raises:
128
AstroidSyntaxError: If source contains syntax errors
129
"""
130
131
def module_build(self, module: Any, modname: str | None = None) -> nodes.Module:
132
"""
133
Build astroid tree from a live Python module.
134
135
Parameters:
136
- module: Python module object
137
- modname: Name for the astroid module
138
139
Returns:
140
Module node representing the live module
141
142
Raises:
143
AstroidBuildingError: If module cannot be introspected
144
"""
145
```
146
147
### Raw Building Functions
148
149
Low-level functions for building astroid nodes from runtime Python objects.
150
151
```python { .api }
152
def build_module(name: str, doc: str | None = None) -> nodes.Module:
153
"""Create a new Module node."""
154
155
def build_class(name: str, basenames: list[str] | None = None, doc: str | None = None) -> nodes.ClassDef:
156
"""Create a new ClassDef node."""
157
158
def build_function(name: str, args: list[str] | None = None, posonlyargs: list[str] | None = None,
159
defaults: list[Any] | None = None, doc: str | None = None) -> nodes.FunctionDef:
160
"""Create a new FunctionDef node."""
161
```
162
163
## Error Handling
164
165
The parsing system raises specific exceptions for different error conditions:
166
167
- **AstroidSyntaxError**: Malformed Python syntax
168
- **AstroidBuildingError**: General building failures (file access, module import)
169
- **AstroidImportError**: Import resolution failures
170
171
## Advanced Usage
172
173
### Custom Transforms
174
175
Register transforms that modify AST nodes during building:
176
177
```python
178
from astroid import MANAGER
179
180
def remove_docstrings(node):
181
"""Remove docstring nodes."""
182
if isinstance(node, astroid.Expr) and isinstance(node.value, astroid.Const):
183
if isinstance(node.value.value, str):
184
return None
185
return node
186
187
MANAGER.register_transform(astroid.Expr, remove_docstrings)
188
```
189
190
### Module Building from Files
191
192
```python
193
import astroid
194
195
# Build from file
196
try:
197
module = astroid.parse(open('mymodule.py').read(), 'mymodule')
198
print(f"Successfully parsed {module.name}")
199
except astroid.AstroidSyntaxError as e:
200
print(f"Syntax error: {e}")
201
```