ast-comments

What it is and what it does

ast-comments is a thin wrapper around Python's standard `ast` module that adds comment preservation to the Abstract Syntax Tree. When you parse source code with this library, comments appear as `Comment` nodes alongside the normal AST nodes, each carrying the comment text and a flag indicating whether it was inline or block-level. This is useful for tools that need to round-trip source code (parse it, analyze it, and regenerate it) while keeping comments intact.

The library's API mirrors the standard `ast` module exactly — you call `parse()` the same way you would with the built-in module, and the result is a standard `ast.Module` object with the addition of `Comment` nodes in the tree. For Python 3.9+, you can also unparse the tree back to source with comments preserved. The main gotcha is that Python's `compile()` function cannot directly consume the tree; the library provides a `pre_compile_fixer()` function to strip comments when compilation is needed.

Use it for:

• Code refactoring tools that need to preserve developer comments when transforming source.
• Documentation generators that extract and process inline comments as metadata.
• Linters or code analyzers that want to report issues with comment context.
• Source-to-source translators or code formatters that must round-trip comments.
• AST-based code inspection tools that treat comments as semantic information.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Extends Python's built-in `ast` module to preserve comments as nodes in the Abstract Syntax Tree, allowing you to parse and analyze code while retaining inline and block comments.

Yes. The package is actively maintained, has no dependencies, installs cleanly, carries no known vulnerabilities, and solves a real gap in Python's standard library for anyone who needs comments in the AST. Install it if you're building tools that parse and regenerate Python code while preserving comments.

Install

ast-comments on PyPI

pip install ast-comments

uv add ast-comments

poetry add ast-comments

Installing ast-comments

Before you install

Low friction: pure Python wheel with no runtime dependencies. Actively maintained with a recent commit on 2026-02-22 and no known vulnerabilities.

License in practice

MIT license (permissive) — you can use, modify, and distribute this package freely in commercial or private projects with minimal restrictions.

Quickstart

pip install ast-comments

from ast_comments import parse, dump
tree = parse("x = 1  # comment")
print(dump(tree))

Requires Python 3.8 or above; unparsing with comments preserved requires Python 3.9+.

Verify before relying

• Whether the `pre_compile_fixer()` function handles all edge cases for stripping comments before compilation.
• Performance characteristics when parsing very large source files with many comments.

Package facts

Evidence: ast_comments-1.3.0-py3-none-any.whl

Tags

More Software Development packages