What is the Understand Python API?


The Python 3 API allows you to write your own scripts that can create custom reports, generate your own metrics, and in general make Understand deliver exactly what you want it to. To learn more about the possibilities this powerful tool provides, checkout our blog: A Toolsmith’s Guide to the Understand API


The full list of API commands can always be found in Understand under Help > Python API Documentation.



Using Understand's Python (uPython)


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. 


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()
'6.5.1200'
>>>c:\Program Files\SciTools\bin\pc-win64>upython >>> import understand >>> understand.version()'6.5.1200'>>>c:\Program Files\SciTools\bin\pc-win64>upython >>> import understand >>> understand.version()'6.5.1200'>>>
Generic


uPython can also be used from any directory after adding it to your path. On Windows go to Edit the System Variables > Environment Variables, under User variables click on Path and then Edit..., click New and paste the following path: C:\Program Files\SciTools\bin\pc-win64. You may need to reboot for the change to take affect.



Custom Python Installation

This tutorial will be using uPython but you can use custom Python libraries instead, you will need to add Understand to your own Python installation following these steps:


  1. Understand 6.5 and newer requires Python 3.12 or newer. Understand 6.4 and older can use older versions of Python 3. Python needs to be the same bitness as Understand, so if you have a 64 bit version of Understand you’ll need a 64 bit version of Python 3.
  2. Modify the PYTHONPATH environment variable to include the module location, which is c:\Program Files\SciTools\bin\pc-win64\Python.
  3. Edit the PATH environment variable to 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:
    python “c:\Program Files\SciTools\plugins\Scripts\Python\api_install_test.py”
    For older versions of Understand, use this command:
    python “c:\Program Files\SciTools\scripts\python\api_install_test.py” 
  6. In your script add import understand
  7. 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:


c:\python39>python >>> import os >>> os.add_dll_directory("C:\\Program Files\\Scitools\\bin\\pc-win64\\") >>> import understand >>> understand.version() 1055 >>>



Setting up an Understand Project

The Understand API requires a valid Understand project. You can easily import your code into Understand by following the Setup Wizard when first installing Understand or by going to File > New > Project. For additional help setting up your project checkout our support article: Building an Accurate Understand Project


Now that you have Python ready to run our Understand API, continue with the tutorial to learn how to access entities and references, apply filters, use lexers, create graphs, and custom reports.


Continue to API Tutorial 2: Writing Your First API Script -> 



Need help? Contact support@scitools.com or visit our About the Understand Python API page.