0
# Astor
1

2
A Python library for reading, rewriting, and writing Python Abstract Syntax Trees (ASTs). Astor enables programmatic manipulation of Python source code through AST transformations, providing round-trip conversion between source code and AST representations while preserving code readability.
3

4
## Package Information
5

6
- **Package Name**: astor
7
- **Language**: Python
8
- **Installation**: `pip install astor`
9

10
## Core Imports
11

12
```python
13
import astor
14
```
15

16
Most commonly used functions:
17

18
```python
19
from astor import to_source, parse_file, dump_tree
20
```
21

22
## Basic Usage
23

24
```python
25
import ast
26
import astor
27

28
# Parse Python source code into an AST
29
source_code = """
30
def hello(name):
31
    print(f"Hello, {name}!")
32
    return name.upper()
33
"""
34

35
# Parse source to AST
36
tree = ast.parse(source_code)
37

38
# Convert AST back to source code
39
generated_source = astor.to_source(tree)
40
print(generated_source)
41

42
# Parse a file directly
43
tree = astor.parse_file('example.py')
44

45
# Pretty-print AST structure for debugging
46
print(astor.dump_tree(tree))
47
```
48

49
## Architecture
50

51
Astor provides a comprehensive AST manipulation framework with several key components:
52

53
- **Source Generation**: Core functionality for converting AST nodes back to readable Python source code
54
- **Tree Walking**: Efficient recursive and non-recursive AST traversal mechanisms
55
- **Node Utilities**: Tools for inspecting, comparing, and modifying AST structures
56
- **File Operations**: High-level interfaces for parsing files and managing code objects
57
- **Operator Handling**: Utilities for working with Python operators and precedence rules
58

59
The library is designed for maximum utility in code generation tools, static analysis frameworks, refactoring utilities, and any application requiring programmatic Python code manipulation.
60

61
## Capabilities
62

63
### AST to Source Conversion
64

65
Core functionality for converting Python AST nodes back to readable source code with customizable formatting options and pretty-printing capabilities.
66

67
```python { .api }
68
def to_source(node, indent_with=' ' * 4, add_line_information=False, 
69
              pretty_string=pretty_string, pretty_source=pretty_source, 
70
              source_generator_class=None):
71
    """Convert AST node tree to Python source code."""
72
```
73

74
[AST to Source](./ast-to-source.md)
75

76
### Tree Manipulation
77

78
Tools for walking, inspecting, dumping, and modifying AST structures. Includes utilities for tree traversal, node comparison, and AST pretty-printing.
79

80
```python { .api }
81
def dump_tree(node, name=None, initial_indent='', indentation='    ', 
82
              maxline=120, maxmerged=80):
83
    """Dump AST in pretty-printed format with indentation."""
84

85
def iter_node(node, name='', unknown=None):
86
    """Iterate over AST node attributes or list items."""
87

88
def strip_tree(node):
89
    """Strip AST by removing all attributes not in _fields."""
90
```
91

92
[Tree Manipulation](./tree-manipulation.md)
93

94
### File Operations
95

96
High-level interfaces for parsing Python files into ASTs and managing code objects with caching support.
97

98
```python { .api }
99
def parse_file(fname):
100
    """Parse Python file into AST."""
101

102
class CodeToAst:
103
    """Convert modules/functions to AST with caching support."""
104
```
105

106
[File Operations](./file-operations.md)
107

108
### Operator Utilities
109

110
Utilities for working with Python operators, including symbol extraction and precedence handling for proper expression formatting.
111

112
```python { .api }
113
def get_op_symbol(obj, fmt='%s'):
114
    """Return symbol string for AST operator node."""
115

116
def get_op_precedence(obj):
117
    """Return precedence value for AST operator node."""
118
```
119

120
[Operator Utilities](./operator-utilities.md)
121

122
## Version Information
123

124
```python { .api }
125
__version__: str = "0.8.1"
126
```