gast: Generic Python AST

Warnings

• breaking For Python 3.8 and later, several `ast` node types like `ast.Num`, `ast.Str`, `ast.Bytes`, `ast.Ellipsis`, and `ast.NamedConstant` are replaced by `gast.Constant` in `gast` ASTs (since `gast >= 0.3.0`). Code that directly inspects or creates these specific node types must be updated to use `gast.Constant` for cross-version compatibility.
  Fix: Replace usages of `gast.Num`, `gast.Str`, etc., with `gast.Constant(value=..., kind=None)` when working with GAST trees, especially when targeting Python 3.8+.
• gotcha The representation of certain AST nodes changes in Python 3.9+. For instance, `ast.arg` nodes are represented as `ast.Name` with an `ast.Param` context, and `ExceptHandler.name` is an `ast.Name` with an `ast.Store` context instead of a simple string.
  Fix: When traversing or manipulating GASTs, be aware of these structural changes and use appropriate attribute access or type checks, or rely on `gast`'s conversion functions (`gast.gast_to_ast`, `gast.ast_to_gast`) to handle discrepancies.
• gotcha The interpretation of literals like `None`, `True`, and `False` differs between Python 2 and Python 3. In Python 3, they are parsed as `gast.Constant`, while in Python 2, they are parsed as `gast.Name`.
  Fix: When writing tools that target both Python 2 and Python 3 via `gast`, ensure your code can handle these literals potentially being either `gast.Constant` or `gast.Name`.
• gotcha While `gast` provides an API compatible with `ast`, directly importing or using classes from the standard `ast` module when you intend to work with `gast`'s cross-version AST can lead to unexpected behavior or `AttributeError` if the underlying `ast` module's structure for that node differs from `gast`'s harmonized representation.
  Fix: Always import and use node types directly from `gast` (e.g., `gast.Name`, `gast.Constant`) when building or manipulating GAST trees to ensure full compatibility and abstraction across Python versions.
• gotcha The `_field_types` attribute, which exists for each AST class in standard `ast` modules, is always empty in `gast` for Python versions before 3.10. Relying on this field for introspection might yield incomplete information on older Python versions.
  Fix: Avoid relying on `_field_types` for critical logic if your tool needs to function correctly across a wide range of Python versions. Consider alternative introspection methods or conditional logic based on Python version.

Install

• pip install gast Install with pip

Imports

• gast

  import gast

• Node

  from gast import Name, Constant

  gast provides all standard `ast` nodes, but some might be harmonized across versions (e.g., `gast.Constant`).
• parse

  gast.parse(code)

  gast.parse directly produces a GAST node, unlike ast.parse which produces a standard AST node.

Quickstart

This quickstart demonstrates how to parse Python code into a `gast` AST, convert a `gast` AST to a standard `ast` module AST, and convert a standard `ast` to a `gast` AST. The `gast.dump` function is used for easy inspection of the GAST structure.

import gast
import ast

code = """def foo(x):
    return x + 1"""

# Parse code into a GAST (Generic AST) node
gast_tree = gast.parse(code)
print("GAST Tree (using gast.dump):\n" + gast.dump(gast_tree))

# Convert the GAST tree to a standard AST tree for the current Python version
std_ast_tree = gast.gast_to_ast(gast_tree)
print("\nStandard AST Tree (from GAST, using ast.dump):\n" + ast.dump(std_ast_tree))

# Example of converting a standard AST to a GAST tree
std_ast_input = ast.parse("a = 'hello'")
gast_from_std = gast.ast_to_gast(std_ast_input)
print("\nGAST Tree (from standard AST input, using gast.dump):\n" + gast.dump(gast_from_std))