Include/internal/pycore_ast.h

This header is machine-generated by Parser/asdl_c.py from Parser/Python.asdl. It declares every AST node type used by the compiler front end, the sequence allocation helpers, and the public validation entry point. Hand-editing it is not meaningful; regenerate it via make regen-ast.

Map

Lines	Symbol	Purpose
1-10	guard + includes	Include guard, pycore_asdl.h pull-in
11-20	mod_ty, stmt_ty, expr_ty	Top-level node typedefs (pointer-to-struct)
21-35	mod_kind, stmt_kind, expr_kind	Enums listing every node variant
36-55	pattern_ty, pattern_kind	Structural-pattern match node types (3.10+)
56-70	arg, arguments, keyword typedefs	Function argument descriptor structs
71-85	alias, withitem, match_case	Import alias and compound-statement helpers
86-100	_Py_asdl_seq, _Py_asdl_int_seq	Generic sequence types used throughout
101-110	_PyAST_* constructor prototypes	One constructor per node kind, arena-allocated
111-115	PyAST_Validate	Public validation entry point
116-120	AST_IDENTIFIER, AST_STRING macros	Field-type tags for reflection

Reading

Node type hierarchy

Every AST node is a tagged union. The kind enum selects the active arm; all arms live in a single anonymous union inside the struct. The typedef collapses the struct pointer so callers write stmt_ty not struct _stmt *.

// CPython: Include/internal/pycore_ast.h:22 stmt_kind
typedef enum _stmt_kind {
    FunctionDef_kind=1, AsyncFunctionDef_kind=2,
    ClassDef_kind=3, Return_kind=4,
    /* ... */
} stmt_kind;

The corresponding node struct holds the kind tag and the union:

// CPython: Include/internal/pycore_ast.h:48 _stmt
struct _stmt {
    stmt_kind kind;
    union {
        struct { identifier name; arguments_ty args; asdl_stmt_seq *body;
                 asdl_expr_seq *decorator_list; expr_ty returns; } FunctionDef;
        /* ... one arm per kind ... */
    } v;
    int lineno, col_offset, end_lineno, end_col_offset;
};

The lineno/col_offset fields are present on every stmt and expr node; they are filled in by the parser and used by the compiler to emit SET_LINENO instructions and to produce accurate tracebacks.

Sequence helpers

ASDL sequences are typed wrappers around a length and a void ** element array. Two variants exist: _Py_asdl_seq for pointer elements (node pointers, identifier strings) and _Py_asdl_int_seq for Py_ssize_t integers.

// CPython: Include/internal/pycore_ast.h:88 _Py_asdl_seq
typedef struct {
    Py_ssize_t size;
    void **elements;
} _Py_asdl_seq;

All sequences are arena-allocated. The arena is threaded through every constructor call so that freeing the arena releases the entire AST without reference-counting overhead.

AST_IDENTIFIER and AST_STRING field tags

These macros tag field types in the generated attribute tables used by ast.py and the ast C module for reflection. They do not affect the C struct layout; they exist solely for the Python-level ast module to build _fields tuples correctly.

// CPython: Include/internal/pycore_ast.h:117 AST_IDENTIFIER
#define AST_IDENTIFIER() &_Py_ID(identifier)
#define AST_STRING()     &_Py_ID(string)

The PyAST_Validate prototype at line 115 takes a mod_ty root and a PyArena *; it is the single entry point for the validation pass described in Python/ast.c.

gopy notes

Status: not yet ported.

Planned package path: compile/ast (struct definitions) and compile/asdl (sequence helpers). The Go port will replace C tagged unions with Go interface types, one concrete struct per node kind, satisfying a common Node interface that carries Lineno, ColOffset, EndLineno, and EndColOffset fields.