0
# Core Parsing Functions
1

2
LibCST provides parsing functions to convert Python source code into concrete syntax trees that preserve all formatting details including comments, whitespace, and parentheses. These functions serve as the primary entry points for code analysis and transformation workflows.
3

4
## Capabilities
5

6
### Module Parsing
7

8
Parse complete Python modules including all statements, comments, and formatting.
9

10
```python { .api }
11
def parse_module(
12
    source: Union[str, bytes],
13
    config: Optional[PartialParserConfig] = None
14
) -> Module:
15
    """
16
    Parse Python source code into a Module CST node.
17
    
18
    Parameters:
19
    - source: Python source code as string or bytes
20
    - config: Parser configuration options
21
    
22
    Returns:
23
    Module: Root CST node representing the entire module
24
    
25
    Raises:
26
    ParserSyntaxError: If the code contains syntax errors
27
    """
28
```
29

30
### Statement Parsing
31

32
Parse individual Python statements for focused analysis or transformation.
33

34
```python { .api }
35
def parse_statement(
36
    source: str,
37
    config: Optional[PartialParserConfig] = None
38
) -> Union[SimpleStatementLine, BaseCompoundStatement]:
39
    """
40
    Parse a single Python statement into CST.
41
    
42
    Parameters:
43
    - source: Python statement source code
44
    - config: Parser configuration options
45
    
46
    Returns:
47
    Union[SimpleStatementLine, BaseCompoundStatement]: Parsed statement node
48
    
49
    Raises:
50
    ParserSyntaxError: If the statement contains syntax errors
51
    """
52
```
53

54
### Expression Parsing
55

56
Parse Python expressions for analysis of individual expressions within larger contexts.
57

58
```python { .api }
59
def parse_expression(
60
    source: str,
61
    config: Optional[PartialParserConfig] = None
62
) -> BaseExpression:
63
    """
64
    Parse a single Python expression into CST.
65
    
66
    Parameters:
67
    - source: Python expression source code
68
    - config: Parser configuration options
69
    
70
    Returns:
71
    BaseExpression: Parsed expression node
72
    
73
    Raises:
74
    ParserSyntaxError: If the expression contains syntax errors
75
    """
76
```
77

78
### Parser Configuration
79

80
Configure parser behavior for specific Python versions and features.
81

82
```python { .api }
83
class PartialParserConfig:
84
    """Configuration for parser behavior."""
85
    
86
    def __init__(
87
        self,
88
        *,
89
        python_version: Union[str, AutoConfig] = AutoConfig.token,
90
        encoding: Union[str, AutoConfig] = AutoConfig.token,
91
        future_imports: Union[FrozenSet[str], AutoConfig] = AutoConfig.token,
92
        default_indent: Union[str, AutoConfig] = AutoConfig.token,
93
        default_newline: Union[str, AutoConfig] = AutoConfig.token
94
    ) -> None:
95
        """
96
        Initialize parser configuration.
97
        
98
        Parameters:
99
        - python_version: Python version for syntax compatibility (e.g., "3.8", "3.7.1")
100
        - encoding: File encoding format (e.g., "utf-8", "latin-1") 
101
        - future_imports: Set of detected __future__ import names
102
        - default_indent: Indentation style (spaces/tabs, e.g., "    ", "\t")
103
        - default_newline: Newline style ("\n", "\r\n", or "\r")
104
        
105
        All parameters default to auto-detection from source code.
106
        """
107

108
class AutoConfig:
109
    """Marker for auto-configuration of parser settings."""
110
    token: ClassVar[AutoConfig]
111
```
112

113
### Utilities
114

115
Helper functions for common parsing operations and version management.
116

117
```python { .api }
118
# Version information
119
LIBCST_VERSION: str
120
KNOWN_PYTHON_VERSION_STRINGS: List[str]
121

122
def ensure_type(node: CSTNode, nodetype: Type[CSTNodeT]) -> CSTNodeT:
123
    """
124
    Type refinement utility for CST nodes (deprecated).
125
    
126
    Parameters:
127
    - node: CST node to check
128
    - nodetype: Expected node type
129
    
130
    Returns:
131
    CSTNodeT: Node cast to expected type
132
    
133
    Raises:
134
    TypeError: If node is not of expected type
135
    """
136
```
137

138
## Usage Examples
139

140
### Basic Module Parsing
141

142
```python
143
import libcst as cst
144

145
source = '''
146
def factorial(n):
147
    """Calculate factorial of n."""
148
    if n <= 1:
149
        return 1
150
    return n * factorial(n - 1)
151
'''
152

153
module = cst.parse_module(source)
154
print(type(module))  # <class 'libcst._nodes.module.Module'>
155
print(module.code)   # Original source with exact formatting
156
```
157

158
### Statement Parsing
159

160
```python
161
import libcst as cst
162

163
# Parse different statement types
164
stmt1 = cst.parse_statement("x = 42")
165
stmt2 = cst.parse_statement("for i in range(10): pass")
166
stmt3 = cst.parse_statement("class MyClass: pass")
167

168
print(type(stmt1))  # <class 'libcst._nodes.statement.SimpleStatementLine'>
169
print(type(stmt2))  # <class 'libcst._nodes.statement.For'>
170
print(type(stmt3))  # <class 'libcst._nodes.statement.ClassDef'>
171
```
172

173
### Expression Parsing
174

175
```python
176
import libcst as cst
177

178
# Parse various expression types
179
expr1 = cst.parse_expression("x + y * z")
180
expr2 = cst.parse_expression("[1, 2, 3]")
181
expr3 = cst.parse_expression("lambda x: x**2")
182

183
print(type(expr1))  # <class 'libcst._nodes.expression.BinaryOperation'>
184
print(type(expr2))  # <class 'libcst._nodes.expression.List'>
185
print(type(expr3))  # <class 'libcst._nodes.expression.Lambda'>
186
```
187

188
### Error Handling
189

190
```python
191
import libcst as cst
192

193
try:
194
    # This will raise a ParserSyntaxError
195
    module = cst.parse_module("def invalid syntax")
196
except cst.ParserSyntaxError as e:
197
    print(f"Parse error: {e}")
198
    print(f"Line: {e.line}, Column: {e.column}")
199
```
200

201
## Types
202

203
```python { .api }
204
# Core module type
205
class Module(CSTNode):
206
    """Root node representing a complete Python module."""
207
    body: Sequence[Union[SimpleStatementLine, BaseCompoundStatement]]
208
    header: Sequence[Union[SimpleStatementLine, BaseCompoundStatement]]
209
    footer: Sequence[Union[SimpleStatementLine, BaseCompoundStatement]]
210
    encoding: str
211
    default_indent: str
212
    default_newline: str
213
    has_trailing_newline: bool
214
    
215
    def code(self) -> str:
216
        """Generate Python source code from the CST."""
217

218
# Parser configuration
219
class PartialParserConfig:
220
    """Configuration options for the parser."""
221
    python_version: str
222
    future_annotations: bool
223
    strict: bool
224

225
# Exception types
226
class ParserSyntaxError(Exception):
227
    """Raised when parser encounters syntax errors."""
228
    message: str
229
    line: int
230
    column: int
231
    
232
class CSTValidationError(Exception):
233
    """Raised when CST node validation fails."""
234
    
235
class CSTLogicError(Exception):  
236
    """Raised for internal logic errors in CST operations."""
237
```