{"id":7011,"library":"ast-comments","title":"ast-comments","description":"ast-comments is an extension to Python's built-in `ast` module that preserves comments in the Abstract Syntax Tree. It finds comments in source code and includes them as nodes in the parsed AST, which the standard `ast` module discards. The library is currently active, at version 1.3.0, and maintains a regular release cadence to support new Python features and address issues.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/t3rn0/ast-comments","tags":["AST","parser","comments","code analysis","refactoring"],"install":[{"cmd":"pip install ast-comments","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Imports the specialized parse function that includes comments.","symbol":"parse","correct":"from ast_comments import parse"},{"note":"Imports the specialized unparse function that attempts to reconstruct comments.","symbol":"unparse","correct":"from ast_comments import unparse"}],"quickstart":{"code":"from ast_comments import parse, unparse, Comment, pre_compile_fixer\nimport ast\n\ncode = \"\"\"\\\ndef greet(name): # Function to greet a user\n    # This is an inline comment\n    message = f\"Hello, {name}!\" # Greeting message\n    return message\n\n# Call the function\nresult = greet(\"World\")\n\"\"\"\n\n# Parse the code, preserving comments\ntree = parse(code)\n\n# You can now walk the tree and find Comment nodes\ncomments_found = []\nfor node in ast.walk(tree):\n    if isinstance(node, Comment):\n        comments_found.append(node.value)\n\nprint(\"Comments found:\")\nfor comment in comments_found:\n    print(f\"- {comment}\")\n\n# Unparse the tree back to code (with comments)\n# Note: formatting might differ from original, but comments are preserved\nreconstructed_code = unparse(tree)\nprint(\"\\nReconstructed code:\")\nprint(reconstructed_code)\n\n# To compile the AST, comment nodes must be removed first\nfixed_tree = pre_compile_fixer(tree)\ncompiled_code = compile(fixed_tree, '<string>', 'exec')\n# You can then exec(compiled_code) if needed","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your `requirements.txt` or `pyproject.toml` does not specify version `==1.1.1`. Upgrade to 1.1.2 or later.","message":"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.","severity":"breaking","affected_versions":"1.1.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `ast-comments` version 1.2.3 or newer to ensure compatibility with Python 3.14.","message":"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.","severity":"breaking","affected_versions":"<1.2.3"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"AttributeError: 'Comment' object has no attribute 'lineno' (or 'col_offset', etc.)"},{"fix":"Upgrade `ast-comments` to version 1.2.3 or later: `pip install --upgrade ast-comments`.","cause":"Running an older version of `ast-comments` on Python 3.14, where internal `ast` module structures and imports have changed.","error":"ModuleNotFoundError: cannot import name '_Unparser' from 'ast_comments.ast_analyzer' (or similar import errors on Python 3.14)"},{"fix":"Ensure you are using the `parse` and `unparse` functions provided by `ast_comments`: `from ast_comments import parse, unparse`.","cause":"You are likely using the standard `ast.parse()` and `ast.unparse()` functions, which do not preserve comments.","error":"Comments are lost when I parse and then unparse my code."}]}