Understand’s Python API — Understand Python API 0.1 documentation (original) (raw)

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), seeAPI 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 repositoryfor 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 onPYTHONPATH). 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; otherwiseopen 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

Module-level functions are documented on understand.

Indices and tables¶

• Index
• Search Page