0
# Astroid
1

2
An abstract syntax tree for Python with inference support. Astroid provides a common base representation of Python source code that extends the built-in `_ast` module with additional methods, attributes, and static inference capabilities. It serves as the foundational library powering pylint's static code analysis capabilities.
3

4
## Package Information
5

6
- **Package Name**: astroid
7
- **Language**: Python
8
- **Installation**: `pip install astroid`
9
- **Python Version**: 3.9+
10

11
## Core Imports
12

13
```python
14
import astroid
15
```
16

17
Most common usage patterns:
18

19
```python
20
from astroid import parse, MANAGER
21
from astroid.nodes import NodeNG, Module, ClassDef, FunctionDef
22
```
23

24
## Basic Usage
25

26
```python
27
import astroid
28

29
# Parse Python source code into an astroid AST
30
source_code = '''
31
def greet(name):
32
    return f"Hello, {name}!"
33

34
class Person:
35
    def __init__(self, name):
36
        self.name = name
37
'''
38

39
# Parse the source code
40
module = astroid.parse(source_code)
41

42
# Navigate the AST
43
for node in module.body:
44
    print(f"Node type: {type(node).__name__}")
45
    if hasattr(node, 'name'):
46
        print(f"Name: {node.name}")
47

48
# Use inference capabilities
49
function_node = module.body[0]  # The greet function
50
for inferred in function_node.infer():
51
    print(f"Inferred type: {type(inferred).__name__}")
52
```
53

54
## Architecture
55

56
Astroid's architecture consists of several key components:
57

58
- **Parser/Builder**: Converts Python source code or living objects into astroid AST nodes
59
- **Node Classes**: Extended AST nodes with inference and analysis methods
60
- **Manager**: Caches parsed modules and manages the building process
61
- **Inference Engine**: Provides static type inference capabilities
62
- **Brain Modules**: Extend inference for standard library and popular packages
63
- **Transform System**: Allows modification of AST nodes during building
64

65
The node hierarchy is based on Python's `_ast` module but with enhanced capabilities for static analysis, making it ideal for linting tools, code analysis utilities, and development tools that need deep understanding of Python code structure and semantics.
66

67
## Capabilities
68

69
### Core Parsing and Building
70

71
Primary functions for converting Python source code and objects into astroid AST trees, with support for files, strings, modules, and classes.
72

73
```python { .api }
74
def parse(code: str, module_name: str = "", path: str | None = None, apply_transforms: bool = True) -> nodes.Module
75
def extract_node(code: str, module_name: str = "") -> nodes.NodeNG | list[nodes.NodeNG]
76
```
77

78
[Core Parsing](./parsing.md)
79

80
### AST Node Classes
81

82
Comprehensive set of node classes representing all Python language constructs, from expressions and statements to scoped nodes like classes and functions.
83

84
```python { .api }
85
class NodeNG:
86
    def infer(self, context: InferenceContext | None = None) -> Iterator[InferenceResult]
87
    def as_string(self) -> str
88
    def accept(self, visitor) -> Any
89

90
class Module(LocalsDictNodeNG):
91
    name: str
92
    def wildcard_import_names(self) -> list[str]
93

94
class ClassDef(LocalsDictNodeNG):
95
    name: str
96
    bases: list[NodeNG]
97
    def mro(self) -> list[ClassDef]
98
    def ancestors(self) -> Iterator[ClassDef]
99
```
100

101
[AST Nodes](./nodes.md)
102

103
### Manager and Building System
104

105
Central management system for building, caching, and retrieving astroid AST trees from various sources including files, modules, and living objects.
106

107
```python { .api }
108
class AstroidManager:
109
    def ast_from_file(self, filepath: str, modname: str | None = None, fallback: bool = True, source: bool = False) -> Module
110
    def ast_from_string(self, data: str, modname: str = "", filepath: str | None = None) -> Module
111
    def ast_from_module_name(self, modname: str, context_file: str | None = None, use_cache: bool = True) -> Module
112
    def clear_cache(self) -> None
113
```
114

115
[Manager System](./manager.md)
116

117
### Inference System
118

119
Advanced static inference capabilities that determine types and values of expressions, supporting complex Python features like descriptors, metaclasses, and dynamic attributes.
120

121
```python { .api }
122
class InferenceContext:
123
    nodes_inferred: int
124
    callcontext: CallContext | None
125
    boundnode: NodeNG | None
126
    def clone(self) -> InferenceContext
127

128
def inference_tip(func: Callable) -> Callable
129
```
130

131
[Inference](./inference.md)
132

133
### Exception Handling
134

135
Comprehensive exception hierarchy for handling various error conditions during AST building, inference, and analysis operations.
136

137
```python { .api }
138
class AstroidError(Exception): ...
139
class AstroidBuildingError(AstroidError): ...
140
class InferenceError(AstroidError): ...
141
class NameInferenceError(InferenceError): ...
142
class AttributeInferenceError(InferenceError): ...
143
```
144

145
[Exceptions](./exceptions.md)
146

147
### Base Classes and Objects
148

149
Foundation classes for instances, methods, and other inferred objects that represent runtime Python objects within the static analysis context.
150

151
```python { .api }
152
class BaseInstance:
153
    def infer(self, context: InferenceContext | None = None) -> Iterator[BaseInstance]
154

155
class Instance(BaseInstance):
156
    def getattr(self, name: str, context: InferenceContext | None = None) -> list[NodeNG]
157

158
class BoundMethod:
159
    bound: NodeNG
160
    proxy: UnboundMethod
161
```
162

163
[Base Classes](./bases.md)
164

165
## Types
166

167
```python { .api }
168
from typing import Iterator, Any, Callable
169
from enum import Enum
170

171
class Context(Enum):
172
    Load = 1
173
    Store = 2
174
    Del = 3
175

176
InferenceResult = NodeNG | BaseInstance | type[Uninferable]
177
```