Beniget: Static Python Code Analysis

0.5.0 · active · verified Mon Apr 13

Beniget is a static analyzer for Python code, providing compile-time analyses on Python Abstract Syntax Tree (AST). It offers over-approximation of global and local definitions and can compute def-use chains. It serves as a foundational building block for writing static analyzers or compilers for Python, relying on `gast` for cross-version AST abstraction and also supporting the standard library `ast` since version 0.5.0. It is actively maintained with periodic updates.

Warnings

gotcha Beniget performs static analysis and cannot fully account for dynamic Python constructs like `eval()`, `exec()`, or direct manipulation of `globals()` or `locals()` dictionaries. Such code patterns may lead to incomplete or misleading analysis results.
Fix: Be aware of the limitations of static analysis when interpreting results from code that heavily relies on dynamic features.
breaking Prior to version 0.5.0, `beniget` exclusively relied on the `gast` library for Abstract Syntax Tree (AST) representation, which provided a unified interface across different Python 3 versions. As of `beniget` 0.5.0, it gained the ability to directly utilize Python's standard `ast` module. Code written for older `beniget` versions might implicitly expect `gast`'s AST structure, requiring adjustment for direct `ast` module usage post-0.5.0.
Fix: For `beniget >= 0.5.0`, you can use either `gast` or the standard `ast` module. Ensure your AST parsing logic aligns with the version of `beniget` and `ast` library you are using. If targeting older Python versions or cross-version compatibility, `gast` is still recommended.
gotcha The `gast` library is a mandatory runtime dependency for `beniget`, even though `beniget` v0.5.0 now supports the standard `ast` module. `gast` ensures consistent AST behavior across a wide range of Python 3 versions (>=3.6). Failure to install `gast` will lead to import errors if `beniget` (or your code) tries to use it.
Fix: Always include `gast` in your project's dependencies and ensure it is installed alongside `beniget` (`pip install beniget gast`).

Install

pip install beniget Install latest version

Imports

Ancestors
```
from beniget import Ancestors
```
One of the core analysis classes for building the ancestor tree.
DefUseChains
```
from beniget import DefUseChains
```
One of the core analysis classes for computing definition-use chains.
UseDefChains
```
from beniget import UseDefChains
```
One of the core analysis classes for computing use-definition chains.
ast
```
import beniget, gast as ast
```
While beniget 0.5.0 supports the standard `ast` module, `gast` (aliased as `ast`) is recommended for broader cross-version AST compatibility, especially with older Python versions, as `gast` is a core dependency.

Quickstart

This quickstart demonstrates how to use `beniget.DefUseChains` to identify unused imports in a Python code snippet. It parses the code into an AST (using `gast` for cross-version compatibility), computes def-use chains, and then checks if any imported names have no users.

import beniget
import gast as ast # Use 'import ast' for Python >= 3.6 and beniget >= 0.5.0

# Example: Detect unused imports
code = """from math import cos, sin
print(cos(3))"""
module = ast.parse(code)

duc = beniget.DefUseChains()
duc.visit(module)

# Assuming the first body element is an ImportFrom statement
imported_names = module.body[0].names

for name in imported_names:
    # Find the corresponding definition-use chain for the imported name
    # Note: `name.name` gives the imported symbol, e.g., 'cos' or 'sin'
    ud_chain = duc.chains.get(name)
    if ud_chain and not ud_chain.users():
        print(f"Unused import: {ud_chain.name()}")

view raw JSON →