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

For environment setup (bundled uPython, PYTHONPATH, and custom Python), see API Tutorial 1: Getting Started with the Python API. The same guide covers creating a valid Understand project before you call the API.

You can also browse the open-source plugin repository for real-world scripts.

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

• Architectures

• CodeCheck

• Graphs

• Metrics

• Reports

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

• Index

• Search Page