beniget

library0.5.0pypypi✓ verified 22d ago

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.

testing devops

pip install beniget

github ↗package ↗

INSTALL

IMPORT

SIG · BENIGET

beniget

testingpythonv0.5.0

Install

1.7s avg

Import

28ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.030s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.026s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✗ import beniget, 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.

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()}")

Debug

Known issues

gotchaBeniget 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.

affects: All versions

breakingPrior 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.

affects: < 0.5.0

gotchaThe `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`).

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'gast'

The 'beniget' library relies on 'gast' for Abstract Syntax Tree (AST) abstraction across Python versions, and 'gast' is a mandatory runtime dependency that has not been installed.

fix

Install the 'gast' library using pip: `pip install gast` or `pip install beniget gast`

AttributeError: module 'gast' has no attribute 'MatchStar'

An older version of the 'gast' library is installed which does not support newer Python AST nodes, such as 'MatchStar' (introduced with structural pattern matching in Python 3.10), while 'beniget' attempts to process them.

fix

Upgrade 'gast' to a version compatible with your Python version and 'beniget' (e.g., `gast>=0.5.4` for Python 3.10+): `pip install --upgrade gast`

TypeError: 'str' object has no attribute 'body'

A `beniget` analysis function, such as `DefUseChains().visit()`, was called with a plain string or an object that is not a valid Python Abstract Syntax Tree (AST) node, which it expects to traverse.

fix

Ensure that the input to `beniget`'s analysis functions is a properly parsed AST object, typically obtained from `ast.parse()` or `gast.parse()`. For example:
```python
import ast
import beniget

code = """def func(x):\n    return x + 1"""
ast_tree = ast.parse(code)
duc = beniget.DefUseChains()
duc.visit(ast_tree)
```

Upgrade

Version history

0.5.0latest on PyPI · released Nov 29, 2025

Audit

Dependencies

gastrequiredProvides a consistent Python AST abstraction across various Python 3 versions, although beniget v0.5.0 now also supports the standard `ast` module. It is a direct dependency for the package.

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/serge-sans-paille/beniget ↗

packagehttps://pypi.org/project/beniget/ ↗