Skip to content

OpenUnderstand

An open-source implementation of the SciTools Understand Python API for Java source code.

Understand analyses a codebase and lets you ask questions about it: which methods call this one, what does this class contain, how complex is this function. Its API is excellent and its analysis is closed -- the database format is proprietary and the API source is not published. OpenUnderstand reimplements that API on top of an ANTLR4 Java parser and a SQLite database, so the same scripts run without a licence.

The goal is that a script written against Understand runs unchanged here. Every class name, method signature and kind name is Understand's, and every change is measured against the real tool -- see Parity for how close it currently is.

Install

pip install openunderstand

Python 3.9 or newer. Extras: [speedy] for the C++ parser accelerator, [mcp] for the MCP server, [dev] for the test and build tooling.

Build a database

Point it at a directory of Java source. It walks the tree, parses every .java file, and writes a .udb -- a SQLite file, despite the name.

python openunderstand/ounderstand/openunderstand.py \
    -r /path/to/java/project \
    -dba /path/for/database \
    -dbn myproject.udb \
    -l /path/for/app.log

Or from Python, which is how CodART uses it:

from openunderstand.ounderstand.openunderstand import start_parsing

start_parsing(
    repo_address="/path/to/java/project",
    db_address="/path/for/database",
    db_name="myproject.udb",
    engine_core="C++",          # or "Python"
    log_address="/path/for/app.log",
)

Query it

import openunderstand.ounderstand as und

db = und.open("/path/for/database/myproject.udb")

for cls in db.ents("Class"):
    print(cls.longname())
    for ref in cls.refs("Define", "Method"):
        print("   ", ref.ent().name(), "at line", ref.line())

The full surface is in the API reference; the vocabulary of kind names is in Kinds.

Check it against Understand

If you have Understand installed and licensed, both databases can be built from the same source and every difference reported:

The result is a ranked defect report. Understand must be installed and licensed, so it is kept outside this repository -- ask if you want to run it.

The comparison is the specification: the only thing that decides whether a reference is right is what the real tool reports for it.

Alongside it, tests/ holds unit tests for the passes whose rules were derived from that comparison -- what counts as a Set against a dereferenced target, where a Modify sits on ++i, which names a type resolves to. Each runs in about a second and needs no database:

for t in tests/test_*.py; do .venv/bin/python -W ignore "$t"; done

They exist to stop a rule regressing between comparison runs, not to replace one -- a pass can satisfy every test here and still disagree with Understand.

Where to go next
API reference Every class and method, and what is not implemented
Kinds The 237 entity and 106 reference kinds
Architecture How a file becomes rows, and how to add a pass
Parity Current measured agreement with Understand
MCP server Query your code from an assistant