0
# Core Parsing Functions
1

2
Main entry points for parsing Python code. These functions provide the simplest interface to parso's parsing capabilities and handle the most common use cases without requiring detailed knowledge of the grammar system.
3

4
## Capabilities
5

6
### High-Level Parsing
7

8
The main parsing function that provides a simple interface for parsing Python code without needing to explicitly manage grammars.
9

10
```python { .api }
11
def parse(code=None, **kwargs):
12
    """
13
    Parse Python code using a default grammar.
14
    
15
    Args:
16
        code (str | bytes, optional): Python source code to parse
17
        version (str, optional): Python version for grammar (e.g., "3.9")
18
        error_recovery (bool): Enable error recovery (default: True)
19
        path (str | Path, optional): File path for caching
20
        cache (bool): Enable caching (default: False)
21
        diff_cache (bool): Enable differential caching (default: False)
22
        cache_path (str | Path, optional): Custom cache directory
23
        file_io (FileIO, optional): File I/O handler
24
        start_symbol (str, optional): Grammar start symbol
25
        
26
    Returns:
27
        Module: Parsed syntax tree module
28
        
29
    Raises:
30
        ParserSyntaxError: If parsing fails and error_recovery is False
31
        TypeError: If neither code nor path provided
32
    """
33
```
34

35
#### Usage Examples
36

37
```python
38
import parso
39

40
# Parse string code
41
module = parso.parse('x = 1 + 2')
42
expr_stmt = module.children[0]
43
print(expr_stmt.get_code())  # 'x = 1 + 2'
44

45
# Parse with specific Python version
46
module = parso.parse('match x:\n    case 1: pass', version="3.10")
47

48
# Parse from file path
49
module = parso.parse(path="/path/to/script.py")
50

51
# Parse with caching enabled
52
module = parso.parse('def foo(): pass', cache=True, path="example.py")
53

54
# Parse with error recovery disabled (raises on syntax errors)
55
try:
56
    module = parso.parse('invalid syntax here', error_recovery=False)
57
except parso.ParserSyntaxError as e:
58
    print(f"Syntax error: {e.message}")
59
```
60

61
### Grammar Loading
62

63
Function to load Python grammars for specific versions, enabling more control over the parsing process and access to advanced features.
64

65
```python { .api }
66
def load_grammar(*, version=None, path=None):
67
    """
68
    Load a Python grammar for a specific version.
69
    
70
    Args:
71
        version (str, optional): Python version string (e.g., "3.8", "3.10")
72
                               Defaults to current Python version
73
        path (str, optional): Path to custom grammar file
74
        
75
    Returns:
76
        PythonGrammar: Grammar instance for parsing
77
        
78
    Raises:
79
        NotImplementedError: If Python version is not supported
80
        FileNotFoundError: If custom grammar file not found
81
    """
82
```
83

84
#### Usage Examples
85

86
```python
87
import parso
88

89
# Load grammar for current Python version
90
grammar = parso.load_grammar()
91

92
# Load grammar for specific version
93
grammar38 = parso.load_grammar(version="3.8")
94
grammar310 = parso.load_grammar(version="3.10")
95

96
# Parse with loaded grammar
97
module = grammar310.parse('match x:\n    case 1: print("one")')
98

99
# Check for syntax errors
100
errors = list(grammar.iter_errors(module))
101
if errors:
102
    for error in errors:
103
        print(f"Error at {error.start_pos}: {error.message}")
104

105
# Load custom grammar from file
106
custom_grammar = parso.load_grammar(path="/path/to/custom.txt")
107
```
108

109
### Supported Python Versions
110

111
Parso supports Python grammar versions from 3.6 to 3.14:
112

113
- **3.6**: f-strings, variable annotations
114
- **3.7**: dataclasses syntax support
115
- **3.8**: positional-only parameters, walrus operator (:=)
116
- **3.9**: dictionary union operators, type hinting improvements
117
- **3.10**: match statements, union types (X | Y)
118
- **3.11**: exception groups, async comprehensions improvements
119
- **3.12**: f-string improvements, type parameter syntax
120
- **3.13**: type parameter syntax refinements
121
- **3.14**: latest supported version
122

123
#### Version-Specific Parsing
124

125
```python
126
import parso
127

128
# Python 3.8 features - walrus operator
129
grammar38 = parso.load_grammar(version="3.8")
130
module = grammar38.parse('if (n := len(items)) > 5: pass')
131

132
# Python 3.10 features - match statements
133
grammar310 = parso.load_grammar(version="3.10")
134
module = grammar310.parse('''
135
match value:
136
    case 1:
137
        print("one")
138
    case 2 | 3:
139
        print("two or three")
140
    case _:
141
        print("other")
142
''')
143

144
# Use newer version for backwards compatibility
145
future_grammar = parso.load_grammar(version="4.0")  # Uses 3.14 grammar
146
```
147

148
## Error Handling
149

150
### Parse Errors
151

152
When `error_recovery=False`, parsing failures raise `ParserSyntaxError`:
153

154
```python
155
import parso
156

157
try:
158
    # This will raise because of invalid syntax
159
    module = parso.parse('def (invalid): pass', error_recovery=False)
160
except parso.ParserSyntaxError as e:
161
    print(f"Syntax error: {e.message}")
162
    print(f"Error location: {e.error_leaf.start_pos}")
163
    print(f"Error token: {e.error_leaf.value}")
164
```
165

166
### Error Recovery Mode
167

168
With `error_recovery=True` (default), parso can parse invalid code:
169

170
```python
171
import parso
172

173
# Parse invalid code - still returns a tree
174
module = parso.parse('def broken(: pass')  # Missing parameter name
175

176
# Check for errors using grammar
177
grammar = parso.load_grammar()
178
module = grammar.parse('for x in: pass')  # Missing iterable
179
errors = list(grammar.iter_errors(module))
180

181
for error in errors:
182
    print(f"Error: {error.message} at {error.start_pos}")
183
```
184

185
## Performance Considerations
186

187
### Caching
188

189
Enable caching for better performance when parsing the same files repeatedly:
190

191
```python
192
import parso
193

194
# Enable pickle caching (saves parsed trees to disk)
195
module = parso.parse(
196
    path="/path/to/large_file.py",
197
    cache=True,
198
    cache_path="/custom/cache/directory"  # Optional custom location
199
)
200

201
# Enable differential caching (only re-parse changed parts)
202
module = parso.parse(
203
    path="/path/to/file.py",
204
    diff_cache=True,
205
    cache=True  # Also enable regular caching
206
)
207
```
208

209
### Memory Management
210

211
For processing many files, consider clearing the cache periodically:
212

213
```python
214
import parso.cache
215

216
# Clear all caches
217
parso.cache.clear_cache()
218

219
# Clear only inactive cache files
220
parso.cache.clear_inactive_cache()
221
```
222

223
## Integration Patterns
224

225
### File Processing
226

227
```python
228
import parso
229
from pathlib import Path
230

231
def process_python_files(directory):
232
    """Process all Python files in a directory."""
233
    for py_file in Path(directory).glob("**/*.py"):
234
        try:
235
            module = parso.parse(path=str(py_file), cache=True)
236
            # Process the parsed module
237
            yield py_file, module
238
        except Exception as e:
239
            print(f"Error parsing {py_file}: {e}")
240

241
# Usage
242
for file_path, module in process_python_files("/path/to/project"):
243
    print(f"Parsed {file_path}: {len(module.children)} top-level statements")
244
```
245

246
### Code Analysis
247

248
```python
249
import parso
250

251
def analyze_code(source_code, version="3.9"):
252
    """Analyze Python code for basic metrics."""
253
    grammar = parso.load_grammar(version=version)
254
    module = grammar.parse(source_code)
255
    
256
    # Count different node types
257
    functions = list(module.iter_funcdefs())
258
    classes = list(module.iter_classdefs())
259
    imports = list(module.iter_imports())
260
    
261
    # Check for syntax errors
262
    errors = list(grammar.iter_errors(module))
263
    
264
    return {
265
        'functions': len(functions),
266
        'classes': len(classes),
267
        'imports': len(imports),
268
        'errors': len(errors),
269
        'lines': len(module.get_code().splitlines())
270
    }
271

272
# Usage
273
stats = analyze_code('''
274
import os
275
import sys
276

277
class Example:
278
    def method(self):
279
        return 42
280

281
def function():
282
    pass
283
''')
284
print(stats)  # {'functions': 2, 'classes': 1, 'imports': 2, 'errors': 0, 'lines': 9}
285
```