OpenUnderstand

OpenUnderstand Logo

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

Understand reads a codebase and lets you ask questions about it -- which methods call this one, what does this class contain, how complex is this function. The API is good. The analysis is closed: the database format is proprietary, the API source is not published, and it needs a licence.

OpenUnderstand reimplements that API on top of an ANTLR4 Java parser and a SQLite database, so the same scripts run without one.

import openunderstand.ounderstand as und

db = und.open("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())

That is Understand's API, unchanged. Same class names, same method signatures, same kind names.

Install

pip install openunderstand

Python 3.9+. On Linux x86_64, macOS arm64 and Windows x64 that wheel carries the C++ parse accelerator, which is 7.8x faster at parsing and takes about 17% off a full analysis. Everywhere else the pure-Python ANTLR runtime is used instead and everything works the same, just slower -- both engines produce byte-identical databases.

Optional extras:

Extra For
openunderstand[speedy] tools to build the C++ parser accelerator from source
openunderstand[mcp] the MCP server, so an assistant can query your code

From a checkout instead:

git clone https://github.com/m-zakeri/OpenUnderstand
cd OpenUnderstand
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

Build a database

Point it at a directory of Java source:

python openunderstand/ounderstand/openunderstand.py \
    -r /path/to/java/project \
    -dba /path/for/database \
    -dbn myproject.udb \
    -l /path/for/app.log
Flag Meaning
-r source directory to analyse
-dba directory to write the database into
-dbn database filename
-e C++ (fast) or Python parser backend
-l log file

Or from Python:

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++",
    log_address="/path/for/app.log",
)

The result is a .udb file. Despite the name it is plain SQLite -- open it with any SQLite tool if you want to poke at the rows directly.

How correct is it?

Honestly measured, not claimed. Every release is compared against a licensed SciTools Understand install on the same source, entity by entity, reference by reference, metric by metric.

Current agreement, over eleven Java systems and 174,260 Understand entities:

pooled range across subjects
Entities recovered -- recall 0.935 0.49 -- 1.00
-- precision 0.943 0.84 -- 0.97
References at the exact position -- recall 0.90 -- 0.98
-- precision 0.62 -- 0.88

Three of the subjects, for comparison with earlier releases:

calculator_app org.json TheAlgorithms
Java files 8 85 228
Reference recall / precision 0.98 / 0.86 0.97 / 0.84 0.96 / 0.83

Both sides are scoped the same way: Understand indexes the whole Java library whether or not a JDK is added to the project, and its dump keeps only entities declared under the fixture root, so this project's placeholders for those same names -- java.lang.String, java.util.ArrayList -- are excluded too. Counting ours while its counterparts were dropped understated entity precision by 5 to 14 points depending on the subject.

docs/parity.md has the per-kind breakdown.

The comparison is the specification: what the real tool outputs is what decides whether a reference is right. Understand must be installed and licensed, so it is not part of this repository -- ask if you want to run it.

tests/ holds unit tests for the pass rules that comparison established. They need no database and run in about a second each:

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

Use it from an assistant

An MCP server ships with the package:

pip install "openunderstand[mcp]"

{"mcpServers": {"openunderstand": {"command": "openunderstand-mcp"}}}

Six tools (analyze, open_database, list_entities, entity_references, entity_metrics, list_kinds), four resources exposing the kind vocabulary and metric names, and three prompts (review_class, complexity_hotspots, trace_callers) -- so an assistant can analyse a Java project and ask what calls what, without knowing the schema. See docs/mcp.md.

Use it from IntelliJ IDEA

idea-plugin/ builds a Java Metrics tool window: analyse the open project, sort by any metric, double-click to jump to the declaration, export CSV. It runs the analysis in a Python subprocess and offers to install the package into a private virtualenv when it cannot find one.

cd idea-plugin && gradle buildPlugin    # then install the zip from disk

See docs/idea-plugin.md.

What it does not do

  • Java 8 only. The grammar predates records, sealed types, var, text blocks and yield.
  • No external resolution. The JDK and third-party jars are not analysed, so java.lang.String exists but has no members.
  • Partial coverage. 90 to 98% of Understand's references are reproduced at the exact position, at 62 to 88% precision. 46 of the 49 public API methods are implemented.
  • Silence, not refusal, on what is missing. The three unimplemented methods -- Db.close, Db.lookup_uniquename, Violation.add_fixit_hint -- return None. Querying a reference kind no pass emits returns an empty list, which reads exactly like an entity that has none. NotImplementedError is not raised anywhere in the query API, whatever this file used to say.

Documentation
Getting started install, build, query
API reference every class and method, and what is missing
Kinds the 237 entity and 106 reference kinds
Architecture how a file becomes rows; how to add a pass
Parity measured agreement with Understand
MCP server query your code from an assistant
IntelliJ IDEA plugin metrics in a tool window

Published at m-zakeri.github.io/OpenUnderstand.

Contributing

Read docs/architecture.md first -- particularly the rule that kind ids are positions and must always be resolved by name.

Changes to the analysis are judged against Understand, not against opinion. If you can run the comparison, report recall and precision before and after -- a change that raises recall by tanking precision is not an improvement. If you cannot, say what you expect to change and it will be measured for you.

Pull requests target the dev branch.

Credits

Started at the IUST Reverse Engineering Research Laboratory. Uses ANTLR4, peewee, and a labelled fork of the grammars-v4 Java grammar.

Project links

Data verified by PyPI on Aug 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for AminHZDEV from gravatar.com AminHZDEV

Credits

Author/Maintainer: Morteza Zakeri

GitHub Statistics

Data verified by PyPI on Aug 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.9

Provides Extra

speedy metrics mcp dev

Tags

understand scitools static-analysis java antlr metrics

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openunderstand-0.3.1.tar.gz (465.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

openunderstand-0.3.1-cp313-cp313-win_amd64.whl (805.6 kB view details)

Uploaded CPython 3.13Windows x86-64

openunderstand-0.3.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openunderstand-0.3.1-cp313-cp313-macosx_11_0_arm64.whl (982.3 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

openunderstand-0.3.1-cp312-cp312-win_amd64.whl (805.6 kB view details)

Uploaded CPython 3.12Windows x86-64

openunderstand-0.3.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openunderstand-0.3.1-cp312-cp312-macosx_11_0_arm64.whl (982.4 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

openunderstand-0.3.1-cp311-cp311-win_amd64.whl (805.5 kB view details)

Uploaded CPython 3.11Windows x86-64

openunderstand-0.3.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openunderstand-0.3.1-cp311-cp311-macosx_11_0_arm64.whl (982.2 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

openunderstand-0.3.1-cp310-cp310-win_amd64.whl (805.5 kB view details)

Uploaded CPython 3.10Windows x86-64

openunderstand-0.3.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openunderstand-0.3.1-cp310-cp310-macosx_11_0_arm64.whl (982.2 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

openunderstand-0.3.1-cp39-cp39-win_amd64.whl (805.5 kB view details)

Uploaded CPython 3.9Windows x86-64

openunderstand-0.3.1-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (3.2 MB view details)

Uploaded CPython 3.9manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

openunderstand-0.3.1-cp39-cp39-macosx_11_0_arm64.whl (982.2 kB view details)

Uploaded CPython 3.9macOS 11.0+ ARM64

File details

Details for the file openunderstand-0.3.1.tar.gz.

File metadata

  • Download URL: openunderstand-0.3.1.tar.gz
  • Upload date:
  • Size: 465.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openunderstand-0.3.1.tar.gz
Algorithm Hash digest
SHA256 daa14197613615d3c0038f2c15f1cc8ed9bb8161a030c15a0f2330798d599633
MD5 adcee47e70e6c6b2abf17fba6050526b
BLAKE2b-256 7ab0f4b0f776754a6d0519d7ab0c06990fa4ec199e91f5de36f9bfdcab2bf82c

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1.tar.gz:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 1fcbf579cd9d4e86e76c7bf460bc8bc967efbaf07caeff142a76e2d2d6b527d6
MD5 d5bfa1ab3d1a2676a03cfc52f6f7d3ef
BLAKE2b-256 d195b49145fdcbdba197820da52bba8d7ea262c67975a2198b9324c792226d75

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp313-cp313-win_amd64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5e18a9f31d556bb03238edb976fd8f46c9d49d85bf1b7a9a6bd41df1730661e2
MD5 a67f312ed851b16c908d87a2c26d3256
BLAKE2b-256 3b041527d4eeef2cb3632fb27fba0d168da59bac24655132ebba7c1f06d98134

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 560dfa246d2763b9b2b2b07c341c46c80312362444149246fe06b89366fca618
MD5 6c99b2e63bc9063ef49a140ed2bcc8a8
BLAKE2b-256 c780ea0a547c9e3ff583bb81aa51855af5c7ad3937f5d1f1da12014c3e78a111

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 59589fb80a0fb62861b8bfb297b57f872f731acb50daa36cdf8da1ace7908a45
MD5 aa5e5ef218e1ac9b08249a5457d3ae61
BLAKE2b-256 b7a445ca9352babf8b9a21b76419c237e56abe27d0a8f5b4600133fb560a3673

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp312-cp312-win_amd64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2771f6b579b60072a0e24dad21882d6d5e1e1c7595bd0be644f8fc36df3002bc
MD5 723e68b79b0402f1e0baa5c5d6ea5dc1
BLAKE2b-256 e2047e992dff909431e9b063d398cb62b39e4fc5e7cfffda0f552e8e749bc636

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a237a7b6006b6cfcbf618027dba9eb87cd9036796c96bab6d1ce2194ca23a7ed
MD5 217b5596746c2b94ee165e0c16a5190e
BLAKE2b-256 a715b4278daa998f8b0f43922cc7fb50900742941741c7cdd2ca69f815539cc8

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp311-cp311-win_amd64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 6fecb54254d596d4dc0f2391827696e09cd8faaf913a695bf006f0bede49e7cb
MD5 8b0ce15a5d3cd630ef346c36ffbd91f7
BLAKE2b-256 3c2b24346a0fbc4098572a26f3f243a20697c4cbd5dbf2551c4a617ff409a7bd

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp311-cp311-win_amd64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e9a5a8631d0133e1db1346c6bba55fb4153a4bcb80907a2103518d65a2d7ccc6
MD5 dfef083524703ff5c49d5acb5abd81cd
BLAKE2b-256 b31b99739a44e03f9636c95b4f0383a33b9538e0816cb2135b888a8559a463cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 87afe4634e0d4db3b30b7aedee6299f02aeeaae8de17e2b69e2397ea4927da2f
MD5 08eeb5b7653db44ab841c92e8931ea1e
BLAKE2b-256 f5f89b76c2355cf1a1c0c056ea3a6ca4a146267a14bd040f0cc57bc626e2bf81

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp310-cp310-win_amd64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 7fdabc5c1df8c53a48e12291210d1f5bd7bd1b856fc158c389ce3932d5ed896d
MD5 194f04180d4a4be529f0343a1bb0c19a
BLAKE2b-256 b44fbd7fd61dafc7f3f75af4246ee0a33153db863da21bb6d799516b5442f91f

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp310-cp310-win_amd64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 14c1c72a6bed88ec3f23283b506f7dbacac06774095c7c979a78d8feb7f7ad6c
MD5 618988bfe2047ce2ffbafa3fb0e39a38
BLAKE2b-256 bcc164fdd54c7683a07c040d39ebcdeb9861b4ce53470bc2d97d5315dc3b78db

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6556bcffc6d546edba160a7b4a47dc56a4c3fbe74e832bfcccb7546f97734a63
MD5 456969f5f9c7eb32029a33d6d86eea42
BLAKE2b-256 387fb913e321ae7899b3bd6b6d468987996f3ba0224c3032b3affd7a366c1f00

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp39-cp39-win_amd64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 a468f14762b78a211a1cca0bddfd3aa3e8e91d7eab5d3ebc3538cd933e1f0099
MD5 e9a31a5b2ce248c117751d70bb4d35db
BLAKE2b-256 a26dd874dfee47b22ccae69e66d20a5fa072df0f0972b4ce4cf1b15cd0e47534

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp39-cp39-win_amd64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 20ad55903ffd74e5e7740307a1119c18490d72a43e79b9598dc7d6a1e182b8f2
MD5 fadc63696d89d78fd9f2d36513a44db9
BLAKE2b-256 9d697e72d81b9dc510ad1f4ea0fde151f4c4a6af9c449cadcd11dd06871a7be4

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file openunderstand-0.3.1-cp39-cp39-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for openunderstand-0.3.1-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2dc491d57b481feb181302f5bbf6c72a264628cae756d8bf9227543eb0a72289
MD5 71a0f667404004fb0baa8d0f8d18526f
BLAKE2b-256 ed7cb71b29d2acde891e1c81ad1821de74740ad8c32ff87bcd65ff324e6e0d1d

See more details on using hashes here.

Provenance

The following attestation bundles were made for openunderstand-0.3.1-cp39-cp39-macosx_11_0_arm64.whl:

Publisher: release.yml on m-zakeri/OpenUnderstand

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.4.0

19 files

This release

0.3.1 This release

16 files

0.3.0

6 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page