Astroid: Python Abstract Syntax Tree with Inference

4.1.2 · active · verified Sat Mar 28

Astroid is a Python library that provides an extended abstract syntax tree (AST) with inference capabilities, primarily used by Pylint for static code analysis. It reconstructs Python's built-in `_ast` module's tree, adding richer nodes with methods and attributes for static inference and local scope analysis. It can also build partial ASTs from live Python objects. As of version 4.1.2, it supports Python 3.10 and newer.

Warnings

breaking Astroid v3.0.0 and later removed support for Python 3.7.
Fix: Upgrade your Python environment to 3.8 or newer. Current Astroid versions (4.x) require Python >=3.10.0.
breaking In Astroid v4.0.0, the `manager` argument to `AstroidBuilder()` became required to alleviate circular import issues.
Fix: Ensure you pass a manager instance, typically `astroid.MANAGER`, when initializing `AstroidBuilder`. E.g., `builder = AstroidBuilder(manager=astroid.MANAGER)`.
deprecated Importing node classes directly from the top-level `astroid` package (e.g., `from astroid import FunctionDef`) is deprecated.
Fix: Import node classes from `astroid.nodes` instead (e.g., `from astroid.nodes import FunctionDef`).
gotcha Deeply nested code structures or complex transformations can lead to `RecursionError` during AST processing.
Fix: Increase Python's recursion limit if encountering such errors: `import sys; sys.setrecursionlimit(YOUR_HIGHER_LIMIT)`.
breaking Astroid v3.3.0 and later removed support for Python 3.8.
Fix: Upgrade your Python environment to 3.9 or newer. Current Astroid versions (4.x) require Python >=3.10.0.
breaking Internal functions `infer_numpy_member`, `name_looks_like_numpy_member`, and `attribute_looks_like_numpy_member` were removed from `astroid.brain.brain_numpy_utils`.
Fix: Avoid using these internal functions directly, as they are no longer part of the public API. Adapt code to use public inference methods.

Install

pip install astroid Install latest version

Imports

parse
```
from astroid import parse
```
Entry point for parsing Python code into an astroid AST.
MANAGER
```
from astroid import MANAGER
```
While 'AstroidManager' exists, 'MANAGER' is the common singleton instance for managing ASTs and inference.
FunctionDef
```
from astroid.nodes import FunctionDef
```
Direct import of node classes from the top-level `astroid` package is deprecated since v4.1.0 and will be removed in v5. Import from `astroid.nodes` instead.
AstroidBuilder
```
from astroid.builder import AstroidBuilder
```
Used to build ASTs, particularly when custom options or manager instances are needed.

Quickstart

This quickstart demonstrates parsing a Python code string into an Astroid AST. It then iterates through the top-level nodes of the module to identify function definitions and their arguments. It also shows a basic traversal within a function to find specific name usages (e.g., 'print').

from astroid import parse
from astroid.nodes import Module, FunctionDef, Name

code = """
def greet(name):
    return f"Hello, {name}!"

def farewell(name):
    print(f"Goodbye, {name}.")
"""

# Parse the code into an Astroid module
module_node: Module = parse(code)

print(f"Module name: {module_node.name}")

# Iterate over nodes to find functions
for node in module_node.body:
    if isinstance(node, FunctionDef):
        print(f"  Found function: {node.name}")
        # Access arguments
        for arg in node.args.args:
            print(f"    Argument: {arg.name}")
        # Example: Find 'print' calls (simple traversal)
        for child_node in node.body:
            if isinstance(child_node, Name) and child_node.name == 'print':
                print(f"      Function '{node.name}' uses 'print'.")

view raw JSON →