AST Unparser for Python

1.6.3 · active · verified Sun Apr 05

astunparse is a Python library that provides an Abstract Syntax Tree (AST) unparser, allowing conversion of ASTs back into Python source code. It is a standalone, factored-out version of the `unparse` utility originally found within the Python source distribution itself. In addition to unparsing, it offers a `dump` function for pretty-printing AST structures. The current version is 1.6.3, released in December 2019, and it has a low-frequency release cadence, primarily updating for compatibility with newer Python AST changes.

Warnings

gotcha Python 3.9+ includes `ast.unparse` natively. The standalone `astunparse` library is primarily useful for projects targeting Python versions prior to 3.9 or when specific behaviors of this library are preferred over the built-in one. For newer Python versions, `ast.unparse` is generally the recommended approach.
Fix: For Python 3.9 and newer, prefer `ast.unparse(node)` directly. For older versions or specific `astunparse` features, continue using the library.
breaking While `astunparse` aims for broad compatibility (Python 2.6 through 3.8 as per its last update), the underlying Python AST structure can change significantly between major Python versions. For example, Python 3.12 introduced changes (PEP 695) to AST node attributes, which could affect code relying on specific AST node structures or the exact output for constructs like f-strings. This means strict round-trip compatibility across different Python versions cannot always be guaranteed by any AST unparser.
Fix: Test your unparsing logic thoroughly against target Python versions. When targeting newer Python versions, consider if the built-in `ast.unparse` might be more up-to-date with recent AST changes than the standalone library.
gotcha `astunparse` (and the standard `ast` module it derives from) does not preserve or unparse PEP 484 type comments. If your project's code includes type annotations and you need them preserved after unparsing, `astunparse` will discard them.
Fix: For use cases requiring the preservation of type comments, consider alternative libraries like `typed-astunparse`, which are built to work with `typed-ast` (an AST variant that includes type comment nodes).

Install

pip install astunparse Install stable version

Imports

unparse

import astunparse
# ...
astunparse.unparse(my_ast_node)

dump
```
import astunparse
# ...
astunparse.dump(my_ast_node)
```
Used for pretty-printing an AST, similar to `ast.dump` but with custom formatting.

Quickstart

This quickstart demonstrates how to parse Python source code into an AST using the built-in `ast` module, then use `astunparse.unparse` to convert the AST back into source code, and `astunparse.dump` to get a pretty-printed representation of the AST.

import ast
import inspect
import astunparse

# Get the AST of a simple function
def example_func(x, y):
    return x + y

source_code = inspect.getsource(example_func)
parsed_ast = ast.parse(source_code)

# Unparse the AST back to source code
unparsed_code = astunparse.unparse(parsed_ast)
print('--- Unparsed Code ---')
print(unparsed_code)

# Pretty-print the AST
dumped_ast = astunparse.dump(parsed_ast)
print('\n--- Dumped AST ---')
print(dumped_ast)

view raw JSON →