astroid

astroid builds an abstract syntax tree from Python source code and wraps it in its own node classes that layer static inference on top of the raw AST — attempting to determine what a name, attribute, or call actually resolves to without executing the code. It re-implements Python’s ast module’s tree shape closely enough that it can be treated as a drop-in enriched alternative for many use cases, while adding the inference machinery that pure ast doesn’t provide.

It exists primarily as the analysis engine underneath pylint, giving pylint the ability to understand things like class hierarchies, imported names, and probable return types well enough to flag real bugs and style issues; a wide ecosystem of other static-analysis tools, IDE plugins, and code-intelligence features also builds on astroid directly. Professional support is available through a Tidelift subscription for teams that need it, though the project itself is fully open source.

What You Get

• An AST builder (astroid.builder) producing a tree of astroid-specific node classes closely mirroring Python’s ast module structure
• A static inference engine (inference_tip.py, protocols.py, constraint.py) that resolves names, attributes, and calls to their probable values/types without executing code
• “Brain” modules — a large astroid/brain/ directory of hand-written inference rules for popular libraries and stdlib modules whose behavior is too dynamic to infer generically
• A manager.py/astroid_manager.py caching layer for building and reusing ASTs across a project without re-parsing unchanged modules
• Raw object introspection (raw_building.py) for building astroid trees from already-imported Python objects, not just source files
• An interpreter/ subpackage modeling Python’s object model (bases, MRO, scoping) closely enough to reason about class hierarchies and inheritance

Common Use Cases

• Serving as pylint’s core analysis engine for detecting undefined names, type mismatches, and style violations
• Powering IDE and language-server features (autocomplete, go-to-definition, type hints) that need to infer what a Python expression resolves to
• Building custom static-analysis or refactoring tools that need an AST richer than Python’s built-in ast module
• Static security or quality scanners that need to trace attribute/call resolution across a codebase without executing it

Under The Hood

Architecture - astroid/builder.py and rebuilder.py convert Python’s native ast module output into astroid’s own node hierarchy (astroid/nodes/), while astroid/manager.py and astroid_manager.py cache built module trees across a project to avoid redundant parsing; inference itself is spread across bases.py, protocols.py, constraint.py, and inference_tip.py, which implement the rules for resolving what a node’s value or type is likely to be, with arguments.py handling call-argument binding and filter_statements.py handling scope/statement filtering during inference. A large astroid/brain/ directory holds hand-written inference plugins for specific standard-library and third-party modules (e.g. dataclasses, six, numpy-style patterns) whose runtime behavior is too dynamic for the generic inference rules to handle correctly. Tech Stack - Pure Python, with an interpreter/ subpackage modeling Python’s object model (class bases, MRO/method resolution, scoping rules) separately from the AST layer itself; the project supports building trees both from source files and from already-imported live objects via raw_building.py, and requirements_full.txt shows opt-in support for inferring behavior of numpy, six, and other common dependencies. Code Quality - The tests/ directory contains 169 test files against roughly 30,000 lines of library code, codecov.yml and a codecov badge in the README track coverage, and the repo uses pre-commit.ci for automated formatting/lint checks (black code style) on every push; a documented ChangeLog and tbump.toml version-bump tooling indicate a disciplined release process. API Design - The primary entry points (astroid.parse(), Module.body, and .inferred() on nodes) mirror the shape of the standard ast module closely enough that developers already familiar with ast can pick it up quickly, though the inference API’s need to return possibly-multiple or Uninferable results adds real complexity once you go beyond simple tree traversal.