Skip to content

Python API: getting started

The Python API gives you a class-oriented view of an analyzed project — Db, Ent, Ref, Metric, Arch, and more. Use it to write standalone tools or GUI plugins. This page gets you running; the full reference and tutorials live elsewhere (see below).

Run your first script

Understand bundles its own Python interpreter, upython, so you don't have to install or configure anything. import understand and run the script with upython:

upython myscript.py /path/to/myproject.und

upython lives in your Understand bin directory (for example C:\Program Files\SciTools\bin\pc-win64\upython.exe on Windows).

Use your own Python instead

You can run against a system Python 3 of the same bitness as Understand: put the module directory (e.g. .../bin/pc-win64/Python) on PYTHONPATH, add the Understand bin directory to PATH (Windows) or LD_LIBRARY_PATH (Linux), and on Windows call os.add_dll_directory("...\\bin\\pc-win64\\") before import understand. upython avoids all of this, but a system Python is handy when you need extra libraries (matplotlib, pandas, …) that upython doesn't bundle.

Open a database and iterate entities

This minimal script opens a project and lists its functions with their kind:

import understand

db = understand.open("/path/to/myproject.und")

# db.ents() takes an Understand kind-filter string.
for ent in db.ents("function ~unresolved ~unknown"):
    print(f"{ent.longname()}  [{ent.kindname()}]")
  • understand.open(path) returns a Db. The database must be up to date with your Understand version, or open raises understand.UnderstandError.
  • db.ents("<kind filter>") returns the matching entities. The filter string (function, ~unresolved, class, file, …) is the same syntax used throughout Understand — see the Kind Filters reference in the API docs.
  • ent.name() / ent.longname() give the short and qualified names; ent.kindname() returns the kind as a string, and ent.kind() returns a Kind object.

Follow references from an entity — for example, the unique outgoing calls of the first function:

import understand

db = understand.open("/path/to/myproject.und")
fn = next(iter(db.ents("function ~unresolved ~unknown")), None)
if fn:
    for ref in fn.refs("call", "", True):   # kind, entkind filter, unique
        callee = ref.ent()
        print(f"{fn.name()} -> {callee.name()}  ({ref.file().longname()}:{ref.line()})")

Check which build you're running with understand.version().

The full reference and tutorials

You don't need to memorize the API — it's fully documented:

Porting older scripts

If a script written for Understand 7.x throws errors on a newer build, check Breaking API changes in 8.0 — a few classes and metric calls changed.

Where to go next