0
# CST Node Types
1

2
LibCST provides a comprehensive set of immutable dataclasses representing every element of Python syntax. These nodes preserve all formatting details including comments, whitespace, and punctuation, enabling lossless round-trip transformations.
3

4
## Capabilities
5

6
### Base Node Types
7

8
Foundation classes for all CST nodes.
9

10
```python { .api }
11
class CSTNode:
12
    """Base class for all CST nodes."""
13
    
14
    def visit(self, visitor: CSTVisitor) -> CSTNode:
15
        """
16
        Visit this node with a visitor.
17
        
18
        Parameters:
19
        - visitor: Visitor to apply
20
        
21
        Returns:
22
        CSTNode: Potentially transformed node
23
        """
24
    
25
    def with_changes(self, **changes: Any) -> CSTNode:
26
        """
27
        Create a copy of this node with specified changes.
28
        
29
        Parameters:
30
        - changes: Field values to change
31
        
32
        Returns:
33
        CSTNode: New node with changes applied
34
        """
35
    
36
    @property
37
    def code(self) -> str:
38
        """Generate source code from this node."""
39

40
class BaseExpression(CSTNode):
41
    """Base class for all expression nodes."""
42

43
class BaseStatement(CSTNode):
44
    """Base class for all statement nodes."""
45

46
class BaseCompoundStatement(BaseStatement):
47
    """Base class for compound statements (if, for, while, etc.)."""
48

49
class BaseSmallStatement(BaseStatement):
50
    """Base class for simple statements (assign, return, etc.)."""
51
```
52

53
### Module Structure
54

55
Root node and organizational elements.
56

57
```python { .api }
58
class Module(CSTNode):
59
    """Root node representing a complete Python module."""
60
    body: Sequence[Union[SimpleStatementLine, BaseCompoundStatement]]
61
    header: Sequence[Union[SimpleStatementLine, BaseCompoundStatement]]
62
    footer: Sequence[Union[SimpleStatementLine, BaseCompoundStatement]]
63
    encoding: str
64
    default_indent: str
65
    default_newline: str
66
    has_trailing_newline: bool
67

68
class SimpleStatementLine(BaseStatement):
69
    """Line containing one or more simple statements."""
70
    body: Sequence[BaseSmallStatement]
71
    leading_lines: Sequence[EmptyLine]
72
    trailing_whitespace: TrailingWhitespace
73

74
class SimpleStatementSuite(BaseSuite):
75
    """Suite of simple statements."""
76
    body: Sequence[SimpleStatementLine]
77

78
class IndentedBlock(BaseSuite):
79
    """Indented block of statements."""
80
    body: Sequence[Union[SimpleStatementLine, BaseCompoundStatement]]
81
    indent: str
82
    whitespace_before_colon: SimpleWhitespace
83
```
84

85
### Expression Nodes
86

87
Nodes representing Python expressions.
88

89
```python { .api }
90
# Literals
91
class Name(BaseExpression):
92
    """Variable names and identifiers."""
93
    value: str
94
    lpar: Sequence[LeftParen]
95
    rpar: Sequence[RightParen]
96

97
class Integer(BaseNumber):
98
    """Integer literals."""
99
    value: str
100

101
class Float(BaseNumber):
102
    """Float literals."""
103
    value: str
104

105
class Imaginary(BaseNumber):
106
    """Complex number literals."""
107
    value: str
108

109
class SimpleString(BaseString):
110
    """String literals."""
111
    value: str
112
    quote: str
113

114
class ConcatenatedString(BaseString):
115
    """Adjacent string concatenation."""
116
    left: BaseString
117
    right: BaseString
118

119
class FormattedString(BaseString):
120
    """f-string literals."""
121
    parts: Sequence[BaseFormattedStringContent]
122
    start: str
123
    end: str
124

125
# Collections
126
class List(BaseList):
127
    """List literals [1, 2, 3]."""
128
    elements: Sequence[Element]
129
    lbracket: LeftSquareBracket
130
    rbracket: RightSquareBracket
131

132
class Tuple(BaseExpression):
133
    """Tuple literals (1, 2, 3)."""
134
    elements: Sequence[Element]
135
    lpar: Sequence[LeftParen]
136
    rpar: Sequence[RightParen]
137

138
class Set(BaseSet):
139
    """Set literals {1, 2, 3}."""
140
    elements: Sequence[Element]
141
    lbrace: LeftCurlyBrace
142
    rbrace: RightCurlyBrace
143

144
class Dict(BaseDict):
145
    """Dictionary literals {key: value}."""
146
    elements: Sequence[BaseDictElement]
147
    lbrace: LeftCurlyBrace
148
    rbrace: RightCurlyBrace
149

150
# Operations
151
class BinaryOperation(BaseExpression):
152
    """Binary operations (+, -, *, etc.)."""
153
    left: BaseExpression
154
    operator: BaseBinaryOp
155
    right: BaseExpression
156

157
class UnaryOperation(BaseExpression):
158
    """Unary operations (-, +, ~, not)."""
159
    operator: BaseUnaryOp
160
    expression: BaseExpression
161

162
class BooleanOperation(BaseExpression):
163
    """Boolean operations (and, or)."""
164
    left: BaseExpression
165
    operator: BaseBooleanOp
166
    right: BaseExpression
167

168
class Comparison(BaseExpression):
169
    """Comparison operations."""
170
    left: BaseExpression
171
    comparisons: Sequence[ComparisonTarget]
172

173
# Function calls and access
174
class Call(BaseExpression):
175
    """Function calls."""
176
    func: BaseExpression
177
    args: Sequence[Arg]
178
    lpar: Sequence[LeftParen]
179
    rpar: Sequence[RightParen]
180

181
class Attribute(BaseExpression):
182
    """Attribute access obj.attr."""
183
    value: BaseExpression
184
    attr: Name
185
    dot: Dot
186

187
class Subscript(BaseExpression):
188
    """Subscription operations obj[key]."""
189
    value: BaseExpression
190
    slice: Sequence[SubscriptElement]
191
    lbracket: LeftSquareBracket
192
    rbracket: RightSquareBracket
193

194
# Comprehensions
195
class ListComp(BaseExpression):
196
    """List comprehensions [x for x in iterable]."""
197
    elt: BaseExpression
198
    for_in: CompFor
199

200
class SetComp(BaseExpression):
201
    """Set comprehensions {x for x in iterable}."""
202
    elt: BaseExpression
203
    for_in: CompFor
204

205
class DictComp(BaseExpression):
206
    """Dict comprehensions {k: v for k, v in iterable}."""
207
    key: BaseExpression
208
    value: BaseExpression 
209
    for_in: CompFor
210

211
class GeneratorExp(BaseExpression):
212
    """Generator expressions (x for x in iterable)."""
213
    elt: BaseExpression
214
    for_in: CompFor
215

216
# Advanced expressions
217
class IfExp(BaseExpression):
218
    """Conditional expressions (x if test else y)."""
219
    test: BaseExpression
220
    body: BaseExpression
221
    orelse: BaseExpression
222

223
class NamedExpr(BaseExpression):
224
    """Named expressions/walrus operator (x := y)."""
225
    target: Name
226
    value: BaseExpression
227

228
class Yield(BaseExpression):
229
    """Yield expressions."""
230
    value: Optional[BaseExpression]
231

232
class YieldFrom(BaseExpression):
233
    """Yield from expressions."""
234
    value: BaseExpression
235

236
class Await(BaseExpression):
237
    """Await expressions."""
238
    expression: BaseExpression
239

240
class Lambda(BaseExpression):
241
    """Lambda expressions."""
242
    params: Parameters
243
    body: BaseExpression
244

245
# Literals and constants
246
class Ellipsis(BaseExpression):
247
    """Ellipsis literal (...)."""
248
```
249

250
### Statement Nodes
251

252
Nodes representing Python statements.
253

254
```python { .api }
255
# Assignments
256
class Assign(BaseSmallStatement):
257
    """Assignment statements (x = y)."""
258
    targets: Sequence[AssignTarget]
259
    value: BaseExpression
260

261
class AnnAssign(BaseSmallStatement):
262
    """Annotated assignments (x: int = y)."""
263
    target: BaseAssignTargetExpression
264
    annotation: Annotation
265
    value: Optional[BaseExpression]
266

267
class AugAssign(BaseSmallStatement):
268
    """Augmented assignments (x += y)."""
269
    target: BaseAssignTargetExpression
270
    operator: BaseAugOp
271
    value: BaseExpression
272

273
# Function and class definitions
274
class FunctionDef(BaseCompoundStatement):
275
    """Function definitions."""
276
    name: Name
277
    params: Parameters
278
    body: BaseSuite
279
    decorators: Sequence[Decorator]
280
    returns: Optional[Annotation]
281
    asynchronous: Optional[Asynchronous]
282

283
class ClassDef(BaseCompoundStatement):
284
    """Class definitions."""
285
    name: Name
286
    args: Sequence[Arg]
287
    body: BaseSuite
288
    decorators: Sequence[Decorator]
289
    bases: Sequence[Arg]
290
    keywords: Sequence[Arg]
291

292
# Control flow
293
class If(BaseCompoundStatement):
294
    """If statements."""
295
    test: BaseExpression
296
    body: BaseSuite
297
    orelse: Optional[Union[If, Else]]
298

299
class For(BaseCompoundStatement):
300
    """For loops."""
301
    target: BaseAssignTargetExpression
302
    iter: BaseExpression
303
    body: BaseSuite
304
    orelse: Optional[Else]
305
    asynchronous: Optional[Asynchronous]
306

307
class While(BaseCompoundStatement):
308
    """While loops."""
309
    test: BaseExpression
310
    body: BaseSuite
311
    orelse: Optional[Else]
312

313
class Try(BaseCompoundStatement):
314
    """Try statements."""
315
    body: BaseSuite
316
    handlers: Sequence[ExceptHandler]
317
    orelse: Optional[Else]
318
    finalbody: Optional[Finally]
319

320
# Exception handling
321
class ExceptHandler(CSTNode):
322
    """Except clauses."""
323
    type: Optional[BaseExpression]
324
    name: Optional[AsName]
325
    body: BaseSuite
326

327
class Raise(BaseSmallStatement):
328
    """Raise statements."""
329
    exc: Optional[BaseExpression]
330
    cause: Optional[BaseExpression]
331

332
# Imports
333
class Import(BaseSmallStatement):
334
    """Import statements."""
335
    names: Sequence[ImportAlias]
336

337
class ImportFrom(BaseSmallStatement):
338
    """From-import statements."""
339
    module: Optional[Union[Attribute, Name]]
340
    names: Union[ImportStar, Sequence[ImportAlias]]
341
    relative: Sequence[Dot]
342

343
class ImportAlias(CSTNode):
344
    """Import aliases (as clauses)."""
345
    name: Union[Attribute, Name]
346
    asname: Optional[AsName]
347

348
# Pattern matching (Python 3.10+)
349
class Match(BaseCompoundStatement):
350
    """Match statements."""
351
    subject: BaseExpression
352
    cases: Sequence[MatchCase]
353

354
class MatchCase(CSTNode):
355
    """Match case clauses."""
356
    pattern: MatchPattern
357
    guard: Optional[BaseExpression]
358
    body: BaseSuite
359

360
class MatchAs(MatchPattern):
361
    """As patterns in match statements."""
362
    pattern: Optional[MatchPattern]
363
    name: Optional[Name]
364

365
class MatchClass(MatchPattern):
366
    """Class patterns in match statements."""
367
    cls: BaseExpression
368
    patterns: Sequence[MatchPattern]
369
    kwds: Sequence[MatchKeywordElement]
370

371
class MatchKeywordElement(CSTNode):
372
    """Keyword elements in class patterns."""
373
    key: Name
374
    pattern: MatchPattern
375

376
class MatchList(MatchPattern):
377
    """List patterns in match statements."""
378
    patterns: Sequence[MatchSequenceElement]
379

380
class MatchMapping(MatchPattern):
381
    """Mapping patterns in match statements."""
382
    elements: Sequence[MatchMappingElement]
383
    rest: Optional[Name]
384

385
class MatchMappingElement(CSTNode):
386
    """Mapping elements in match patterns."""
387
    key: BaseExpression
388
    pattern: MatchPattern
389

390
class MatchOr(MatchPattern):
391
    """Or patterns in match statements."""
392
    patterns: Sequence[MatchOrElement]
393

394
class MatchOrElement(CSTNode):
395
    """Elements in or patterns."""
396
    pattern: MatchPattern
397

398
class MatchSequence(MatchPattern):
399
    """Sequence patterns in match statements."""
400
    patterns: Sequence[MatchSequenceElement]
401

402
class MatchSequenceElement(CSTNode):
403
    """Elements in sequence patterns."""
404
    pattern: MatchPattern
405

406
class MatchSingleton(MatchPattern):
407
    """Singleton patterns (None, True, False)."""
408
    value: BaseExpression
409

410
class MatchStar(MatchPattern):
411
    """Star patterns in match statements."""
412
    name: Optional[Name]
413

414
class MatchTuple(MatchPattern):
415
    """Tuple patterns in match statements."""
416
    patterns: Sequence[MatchSequenceElement]
417

418
class MatchValue(MatchPattern):
419
    """Value patterns in match statements."""
420
    value: BaseExpression
421

422
class MatchPattern(CSTNode):
423
    """Base class for match patterns."""
424
```
425

426
### Operator Nodes
427

428
Nodes representing Python operators.
429

430
```python { .api }
431
# Arithmetic operators
432
class Add(BaseBinaryOp):
433
    """+ operator."""
434

435
class Subtract(BaseBinaryOp):
436
    """- operator."""
437

438
class Multiply(BaseBinaryOp):
439
    """* operator."""
440

441
class Divide(BaseBinaryOp):
442
    """/ operator."""
443

444
class FloorDivide(BaseBinaryOp):
445
    """// operator."""
446

447
class Modulo(BaseBinaryOp):
448
    """% operator."""
449

450
class Power(BaseBinaryOp):
451
    """** operator."""
452

453
class MatrixMultiply(BaseBinaryOp):
454
    """@ operator."""
455

456
# Augmented assignment operators
457
class AddAssign(BaseAugOp):
458
    """+= operator."""
459

460
class SubtractAssign(BaseAugOp):
461
    """-= operator."""
462

463
class MultiplyAssign(BaseAugOp):
464
    """*= operator."""
465

466
class DivideAssign(BaseAugOp):
467
    """/= operator."""
468

469
class FloorDivideAssign(BaseAugOp):
470
    """//= operator."""
471

472
class ModuloAssign(BaseAugOp):
473
    """%= operator."""
474

475
class PowerAssign(BaseAugOp):
476
    """**= operator."""
477

478
class MatrixMultiplyAssign(BaseAugOp):
479
    """@= operator."""
480

481
class LeftShiftAssign(BaseAugOp):
482
    """<<= operator."""
483

484
class RightShiftAssign(BaseAugOp):
485
    """>>= operator."""
486

487
class BitAndAssign(BaseAugOp):
488
    """&= operator."""
489

490
class BitOrAssign(BaseAugOp):
491
    """|= operator."""
492

493
class BitXorAssign(BaseAugOp):
494
    """^= operator."""
495

496
# Comparison operators  
497
class Equal(BaseCompOp):
498
    """== operator."""
499

500
class NotEqual(BaseCompOp):
501
    """!= operator."""
502

503
class LessThan(BaseCompOp):
504
    """< operator."""
505

506
class LessThanEqual(BaseCompOp):
507
    """<= operator."""
508

509
class GreaterThan(BaseCompOp):
510
    """> operator."""
511

512
class GreaterThanEqual(BaseCompOp):
513
    """>= operator."""
514

515
class Is(BaseCompOp):
516
    """is operator."""
517

518
class IsNot(BaseCompOp):
519
    """is not operator."""
520

521
class In(BaseCompOp):
522
    """in operator."""
523

524
class NotIn(BaseCompOp):
525
    """not in operator."""
526

527
# Boolean operators
528
class And(BaseBooleanOp):
529
    """and operator."""
530

531
class Or(BaseBooleanOp):  
532
    """or operator."""
533

534
class Not(BaseUnaryOp):
535
    """not operator."""
536

537
# Bitwise operators
538
class BitAnd(BaseBinaryOp):
539
    """& operator."""
540

541
class BitOr(BaseBinaryOp):
542
    """| operator."""
543

544
class BitXor(BaseBinaryOp):
545
    """^ operator."""
546

547
class LeftShift(BaseBinaryOp):
548
    """<< operator."""
549

550
class RightShift(BaseBinaryOp):
551
    """>> operator."""
552

553
class BitInvert(BaseUnaryOp):
554
    """~ operator."""
555
```
556

557
### Whitespace and Formatting
558

559
Nodes preserving formatting details.
560

561
```python { .api }
562
class SimpleWhitespace(CSTNode):
563
    """Spaces and tabs."""
564
    value: str
565

566
class Comment(CSTNode):
567
    """Code comments."""
568
    value: str
569

570
class Newline(CSTNode):
571
    """Line breaks."""
572
    indent: Optional[str]
573
    whitespace_before_newline: SimpleWhitespace
574
    comment: Optional[Comment]
575

576
class EmptyLine(CSTNode):
577
    """Empty lines with whitespace."""
578
    indent: Optional[str]
579
    whitespace: SimpleWhitespace
580
    comment: Optional[Comment]
581

582
class TrailingWhitespace(CSTNode):
583
    """Whitespace at end of lines."""
584
    whitespace: SimpleWhitespace
585
    comment: Optional[Comment]
586

587
class ParenthesizedWhitespace(CSTNode):
588
    """Whitespace in parentheses."""
589
    first_line: TrailingWhitespace
590
    empty_lines: Sequence[EmptyLine]
591
    indent: Optional[str]
592
    whitespace_before_newline: SimpleWhitespace
593
    comment: Optional[Comment]
594
```
595

596
## Usage Examples
597

598
### Node Creation
599

600
```python
601
import libcst as cst
602

603
# Create nodes programmatically
604
name_node = cst.Name("variable")
605
integer_node = cst.Integer("42")
606
string_node = cst.SimpleString('"hello"')
607

608
# Create complex expressions
609
binary_op = cst.BinaryOperation(
610
    left=cst.Name("x"),
611
    operator=cst.Add(),
612
    right=cst.Integer("1")
613
)
614

615
# Create function call
616
call_node = cst.Call(
617
    func=cst.Name("print"),
618
    args=[cst.Arg(value=cst.SimpleString('"hello"'))]
619
)
620
```
621

622
### Node Inspection
623

624
```python
625
import libcst as cst
626

627
source = '''
628
def example(x, y=10):
629
    """Example function."""
630
    return x + y
631
'''
632

633
module = cst.parse_module(source)
634
func_def = module.body[0].body[0]  # Get the function definition
635

636
print(f"Function name: {func_def.name.value}")
637
print(f"Parameter count: {len(func_def.params.params)}")
638
print(f"Has docstring: {isinstance(func_def.body.body[0].body[0], cst.Expr)}")
639
print(f"Return statement: {isinstance(func_def.body.body[1].body[0], cst.Return)}")
640
```
641

642
### Node Modification
643

644
```python
645
import libcst as cst
646

647
# Parse original code
648
module = cst.parse_module("x = 42")
649
assign = module.body[0].body[0]
650

651
# Modify the assignment value
652
new_assign = assign.with_changes(value=cst.Integer("100"))
653

654
# Create new module with modified assignment
655
new_module = module.with_changes(
656
    body=[cst.SimpleStatementLine(body=[new_assign])]
657
)
658

659
print(new_module.code)  # "x = 100"
660
```
661

662
### Pattern Matching with Nodes
663

664
```python
665
import libcst as cst
666
import libcst.matchers as m
667

668
source = '''
669
def process():
670
    x = [1, 2, 3]
671
    y = {"a": 1, "b": 2}
672
    return x, y
673
'''
674

675
module = cst.parse_module(source)
676

677
# Find all list literals
678
lists = m.findall(module, cst.List())
679
print(f"Found {len(lists)} list literals")
680

681
# Find all dictionary literals  
682
dicts = m.findall(module, cst.Dict())
683
print(f"Found {len(dicts)} dictionary literals")
684

685
# Find assignments to list literals
686
list_assignments = m.findall(module, cst.Assign(value=cst.List()))
687
print(f"Found {len(list_assignments)} assignments to lists")
688
```
689

690
## Types
691

692
```python { .api }
693
# Base node hierarchy
694
class CSTNode:
695
    """Base class for all CST nodes."""
696

697
class BaseExpression(CSTNode):
698
    """Base for expression nodes."""
699

700
class BaseStatement(CSTNode):
701
    """Base for statement nodes."""
702

703
class BaseCompoundStatement(BaseStatement):
704
    """Base for compound statements."""
705

706
class BaseSmallStatement(BaseStatement):
707
    """Base for simple statements."""
708

709
# Expression base classes
710
class BaseAssignTargetExpression(BaseExpression):
711
    """Base for assignment target expressions."""
712

713
class BaseDelTargetExpression(BaseExpression):
714
    """Base for deletion target expressions."""
715

716
class BaseNumber(BaseExpression):
717
    """Base for numeric literals."""
718

719
class BaseString(BaseExpression):
720
    """Base for string literals."""
721

722
class BaseDict(BaseExpression):
723
    """Base for dict-like containers."""
724

725
class BaseList(BaseExpression):
726
    """Base for list-like containers."""
727

728
class BaseSet(BaseExpression):
729
    """Base for set-like containers."""
730

731
# Operator base classes
732
class BaseBinaryOp(CSTNode):
733
    """Base for binary operators."""
734

735
class BaseUnaryOp(CSTNode):
736
    """Base for unary operators."""
737

738
class BaseBooleanOp(CSTNode):
739
    """Base for boolean operators."""
740

741
class BaseCompOp(CSTNode):
742
    """Base for comparison operators."""
743

744
class BaseAugOp(CSTNode):  
745
    """Base for augmented assignment operators."""
746

747
# Suite types
748
class BaseSuite(CSTNode):
749
    """Base for statement suites."""
750

751
# Exception types
752
class CSTValidationError(Exception):
753
    """Raised when CST node validation fails."""
754

755
# Type variables
756
CSTNodeT = TypeVar("CSTNodeT", bound=CSTNode)
757
```