Python API tutorial 1: getting started¶
This is the first page of a seven-part tutorial series that walks you from a first import understand
to reading entities, lexing source, drawing graphs, building interactive reports, and pulling
CodeCheck violations — all from Python.
What is the Understand Python API?¶
The Python 3 API lets you write your own scripts against an analyzed project: custom reports, custom
metrics, custom graphs, and bulk queries over everything Understand knows about your code. It exposes a
class-oriented view of the project — Db, Ent, Ref, Arch, Metric, and more.
The full reference is in the product
The complete, always-current list of API classes and methods is available in Understand under Help → Python API Documentation, and the same generated reference is browsable as the Python API reference. This tutorial series teaches the concepts; the reference is the authority on exact signatures.
Run Python with the bundled interpreter¶
Understand bundles its own Python interpreter, upython, so you don't have to install or configure
anything. Import the understand module and run your script with upython:
upython myscript.py /path/to/myproject.und
You can also start it interactively to check that everything is wired up:
$ upython
>>> import understand
>>> understand.version()
'8.0.1257'
upython lives in your Understand bin directory (for example
C:\Program Files\SciTools\bin\pc-win64\upython.exe on Windows). Add that directory to your PATH to
run upython from anywhere.
Prefer your own Python?
You can run against a system Python 3 of the same bitness as Understand instead of upython. See
Python API: getting started for the PYTHONPATH /
add_dll_directory setup. upython avoids all of that, but a system Python is handy when you need
extra libraries (matplotlib, pandas, …) that upython doesn't bundle.
What you need before you start¶
The API requires a valid, up-to-date Understand project (a .und database). If you don't have one yet,
create it with File → New → Project in the GUI, or from the command line — see
Create an accurate C/C++ project and
Run Understand from the command line.
Keep the database up to date
understand.open() raises understand.UnderstandError if the .und file was written by a
different Understand build or is out of date. Re-analyze the project (or run und analyze) if you
hit this.
Next¶
You're set up. In the next tutorial you'll write and run a complete script.