LibCST

Warnings

• breaking LibCST transitioned to a new, Rust-based parser by default in version 1.0.0. The old pure-Python parser, previously accessible via `LIBCST_PARSER_TYPE=pure` environment variable, is scheduled for removal in future non-patch releases.
  Fix: Ensure your environment is set up to use the default native parser. If you encounter parsing issues or rely on the old parser, update your setup to use the native implementation. Install with pre-built binary wheels when possible to avoid Rust toolchain dependencies.
• gotcha When programmatically modifying a CST, directly re-assigning nodes or performing in-place modifications can lead to unexpected loss of formatting (whitespace, comments). LibCST nodes are immutable.
  Fix: Always return `updated_node` (or a modified copy of it) from `leave_` methods in `CSTTransformer`. Utilize `with_changes()` for modifying existing nodes and `FlattenSentinel` for inserting or removing multiple nodes to preserve formatting. Avoid `isinstance` for traversal; prefer visitor methods like `visit_<NodeType>` or matchers.
• gotcha Building LibCST from source (e.g., if a binary wheel is not available for your specific Python version or OS architecture) requires a recent Rust toolchain, including `cargo`, to be installed and available in your PATH.
  Fix: The easiest way to install Rust is via `rustup`. If you frequently build Python packages with native extensions, consider using an environment where Rust is pre-configured.
• gotcha Forking and renaming a project that internally uses absolute imports from `libcst` can lead to conflicts if both the original `libcst` and your renamed fork are installed in the same environment.
  Fix: Consider using `sys.modules` checks at runtime to prevent co-installation, or implement a build-time script using a LibCST transformer to rewrite internal import paths in your fork. Explicitly declare conflicts in `pyproject.toml` if such a feature becomes available in package managers.
• gotcha When debugging CST structures, simply `print(tree)` might provide an overwhelming amount of detail including all whitespace and token information.
  Fix: Use `from libcst.tool import dump` and then `print(dump(tree))` for a more concise and readable representation of the CST's essential elements, which is often more useful for understanding the tree's structure.

Install

• pip install libcst Install latest stable release

Imports

• libcst

  import libcst as cst

• CSTVisitor

  from libcst import CSTVisitor

• CSTTransformer

  from libcst import CSTTransformer

• parse_module

  from libcst import parse_module

• dump

  from libcst.tool import dump

  While `libcst.display.dump` was shown in older examples, `libcst.tool.dump` is the more consistent and often demonstrated path for displaying a concise CST representation.

Quickstart

This quickstart demonstrates parsing Python code, applying a `CSTTransformer` to modify a variable name (`old_var` to `new_var`), and then generating the modified code. It also shows how to use `libcst.tool.dump` for a concise representation of the CST and how to incorporate metadata providers.

import libcst as cst
from libcst import CSTTransformer, parse_module
from libcst.tool import dump # For pretty-printing the CST
from libcst.metadata import MetadataWrapper, QualifiedNameProvider

class MyTransformer(CSTTransformer):
    METADATA_DEPENDENCIES = {QualifiedNameProvider}

    def leave_Name(self, original_node, updated_node):
        # Example: change all instances of 'old_var' to 'new_var'
        if updated_node.value == 'old_var':
            print(f"Changing '{original_node.value}' to 'new_var' at {self.get_metadata(QualifiedNameProvider, original_node)}")
            return updated_node.with_changes(value='new_var')
        return updated_node


source_code = """
import os

def my_function(old_var):
    x = old_var + 1
    return x

old_var = 10
"""

# Parse the module into a CST
tree = parse_module(source_code)

# Wrap the tree with metadata providers
wrapper = MetadataWrapper(tree)

# Apply the transformer
modified_tree = wrapper.visit(MyTransformer())

# Generate the modified code
modified_code = modified_tree.code

print("Original Code:\n" + source_code)
print("\nModified Code:\n" + modified_code)
print("\nCST of Modified Code (dump):\n" + dump(modified_tree))