ast-comments

Common errors

• AttributeError: 'Comment' object has no attribute 'lineno' (or 'col_offset', etc.)

  cause Attempting to compile an AST that includes `Comment` nodes directly using Python's built-in `compile()` function or processing it with standard `ast` module utilities that expect only standard AST nodes.
  fix Before compiling or passing the AST to `ast.unparse()` (from the standard library), use `ast_comments.pre_compile_fixer(tree)` to create a new AST without `Comment` nodes. Then, compile this 'fixed' tree.

• ModuleNotFoundError: cannot import name '_Unparser' from 'ast_comments.ast_analyzer' (or similar import errors on Python 3.14)

  cause Running an older version of `ast-comments` on Python 3.14, where internal `ast` module structures and imports have changed.
  fix Upgrade `ast-comments` to version 1.2.3 or later: `pip install --upgrade ast-comments`.

• Comments are lost when I parse and then unparse my code.

  cause You are likely using the standard `ast.parse()` and `ast.unparse()` functions, which do not preserve comments.
  fix Ensure you are using the `parse` and `unparse` functions provided by `ast_comments`: `from ast_comments import parse, unparse`.

Warnings

• breaking Version 1.1.1 was released with critical errors and subsequently removed from PyPI. Any projects that attempted to install or use 1.1.1 would have encountered issues.
  Fix: Ensure your `requirements.txt` or `pyproject.toml` does not specify version `==1.1.1`. Upgrade to 1.1.2 or later.
• gotcha The standard `ast` module does not include comments in its AST representation. Directly using functions like `compile()` or `ast.unparse()` from the built-in `ast` module on an `ast-comments` parsed tree (which contains `Comment` nodes) will fail or produce unexpected results.
  Fix: Use `ast_comments.parse` and `ast_comments.unparse` for parsing and unparsing. If compilation is required, first process the tree with `ast_comments.pre_compile_fixer` to strip `Comment` nodes before passing it to `compile()` or other standard `ast` functions.
• breaking Older versions of `ast-comments` (pre-1.2.3) may fail on Python 3.14 due to changes in internal `_Unparser` imports within the CPython standard library.
  Fix: Upgrade to `ast-comments` version 1.2.3 or newer to ensure compatibility with Python 3.14.

Install

• pip install ast-comments Install stable version

Imports

• parse

  from ast_comments import parse

  Imports the specialized parse function that includes comments.
• unparse

  from ast_comments import unparse

  Imports the specialized unparse function that attempts to reconstruct comments.

Quickstart

Demonstrates parsing Python code to include comments in the AST, walking the tree to find `Comment` nodes, and unparsing it back to code. It also shows how to prepare the tree for Python's built-in `compile()` function by stripping comment nodes.

from ast_comments import parse, unparse, Comment, pre_compile_fixer
import ast

code = """\
def greet(name): # Function to greet a user
    # This is an inline comment
    message = f"Hello, {name}!" # Greeting message
    return message

# Call the function
result = greet("World")
"""

# Parse the code, preserving comments
tree = parse(code)

# You can now walk the tree and find Comment nodes
comments_found = []
for node in ast.walk(tree):
    if isinstance(node, Comment):
        comments_found.append(node.value)

print("Comments found:")
for comment in comments_found:
    print(f"- {comment}")

# Unparse the tree back to code (with comments)
# Note: formatting might differ from original, but comments are preserved
reconstructed_code = unparse(tree)
print("\nReconstructed code:")
print(reconstructed_code)

# To compile the AST, comment nodes must be removed first
fixed_tree = pre_compile_fixer(tree)
compiled_code = compile(fixed_tree, '<string>', 'exec')
# You can then exec(compiled_code) if needed