Understand’s Python API

Welcome to the Python API of Understand. This interface gives you a class-oriented view of an analyzed project (entities, references, architectures, metrics, graphs, and more).

With the Understand Python API you can write standalone tools or GUI plugins that use:

You can find tutorials on the Support Website and browse the open-source plugin repository for real-world scripts.

Environment Setup

As of build 1054 Understand bundles its own simplified version of Python (upython.exe) so you can easily get started with the API. You can use your own Python installation (instructions below) but uPython will ensure you are always running a version of Python compatible with your local installation of Understand.

Using Understand’s Python (uPython)

To use uPython simply import understand into your script and run the script with the uPython executable:

C:\Program Files\SciTools\bin\pc-win64>upython
>>> import understand
>>> understand.version()
'7.2.1246'

Custom Python Installation

  1. Your custom python installation needs to meet the minimum version requirements below. It also needs to be the same bitness as Understand, so if you have a 64 bit version of Understand you will need a 64 bit version of Python 3.

    Understand Version

    Minimum Python Version

    >= 7.2 (1235)

    Python 3.14

    >= 7.0 (1207)

    Python 3.13

    >= 6.5 (1158)

    Python 3.12

  2. Modify the PYTHONPATH environment variable to include the module location, which is C:\Program Files\SciTools\bin\pc-win64\Python on Windows.

  3. Windows Only: Edit the PATH environment variable to include C:\Program Files\SciTools\bin\pc-win64

  4. Linux Only: Set LD_LIBRARY_PATH to scitools/bin/linux64

  5. Test the API Setup by running the test script included with Understand:

    python3 “C:\Program Files\SciTools\plugins\Scripts\Python\api_install_test.py”

    For older versions of Understand, use this command:

    python3 “C:\Program Files\SciTools\scripts\python\api_install_test.py”

  6. In your script add import understand

  7. Windows Only: Python 3.8 and newer requires specifying the path to the Understand installation inside the script itself using the os.add_dll_directory command, as in the example below:

    >>> import os
>>> os.add_dll_directory("C:\\Program Files\\SciTools\\bin\\pc-win64\\")
>>> import understand
>>> understand.version()
'7.2.1246'

Getting Started

These snippets are for standalone scripts (run with the upython executable shipped with Understand, or with your own Python once understand is on PYTHONPATH). Plugin hooks are described on the feature pages above.

Most snippets in this documentation omit error handling (missing paths, out-of-date databases, empty query results, and so on) to stay short.

Check that the API is available (matches the Understand build you are using):

import understand

print(understand.version())

Open a project database (the path is usually an .und directory). The database must be up to date with your Understand version; otherwise open raises UnderstandError:

import understand

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

List entities with a kind filter string (here, resolved functions, sorted by name):

import understand

db = understand.open("/path/to/myproject.und")
funcs = db.ents("function ~unresolved ~unknown")
for fn in sorted(funcs, key=lambda e: e.name().lower()):
    print(f"{fn.longname()}  [{fn.kindname()}]")

Follow references from an entity—for example, unique outgoing Call references:

import understand

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

List root architectures in the project (manual or automatic):

import understand

db = understand.open("/path/to/myproject.und")
for arch in db.root_archs():
    print(arch.name())

Module summary

Classes

Arch

An Understand architecture

Atn

An Understand annotation

AutomaticArch

Accessors for available automatic architecture generators.

AutomaticArchContext

Automatic architecture plugin object

Cache

A plugin cache object

CFGraph

A control flow graph

CFNode

A node in a control flow graph

CheckContext

CodeCheck plugin check object

Config

A configuration

Db

An Understand database

Edge

Graph plugin edge object

Ent

An Understand entity

Graph

Accessors for available graphs and graph variants.

GraphContext

Graph plugin graph object

Inspection

An inspection

Kind

The kind of an entity or reference.

Legend

Graph plugin legend object

Lexeme

A token recieved from a lexer.

Lexer

A lexical stream generated for a file entity.

Metric

Accessors for available metrics and metric descriptions.

MetricContext

Metric plugin object

Node

Graph plugin node object

Options

An options object

Ref

An Understand reference.

Report

Accessors for available report plugins.

ReportContext

Report plugin object

UnderstandError

An error message from Understand

Violation

A violation

ViolationContext

CodeCheck plugin violation object

ViolationNote

CodeCheck plugin violation note object

Module-level functions are documented on understand.

Indices and tables