Getting Started with the Python API

Understand fully supports Python 3 access to its underlying database. 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.

Getting Started

  1. The Python API requires a 3.x installation of Python (Python 3.8 and newer require the user add a call to os.add_dll_directory(“SciTools/bin/“) before importing understand. See the example below), you can grab Python from here if you need to install it. It 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 SciTools/bin//Python. For Mac users, the python module is in Understand.app/Contents/MacOS/Python
  3. If you did not add Understand to the Path variable during installation, you will need to add the SciTools/bin/ directory to PATH.
  4. On non-Windows systems, you may need to create an STIHOME environment variable that points to the directory.
  5. To use the API you will need to put ‘import understand’ in your script.
  6. Test the API Setup by running the test script included with Understand:
    python “c:\Program Files\SciTools\python\api_install_test.py”
  7. Optional: To run a Python script from inside of Understand, use Tools->Run a Command, and the path to the Python executable goes in the Command field and the script is the first parameter. This is because Understand does not have a built in Python install shipped with Understand.
  8. The Draw Command has some unique linking requirements. To make it work on Linux and other platforms you may need to set LD_LIBRARY_PATH to scitools/bin/ otherwise the Python script will crash.

Checkout the API tutorials for more help writing your own scripts.

Unfortunately we are not able to support Cygwin’s python due to the unique way it links everything together from the Linux and Windows worlds.

Documentation
The most up-to-date documentation is accessible from the Help menu in Understand. You can also read it from the Python Console with:

import understand

help (understand)

We also try to keep a current version of the Python documentation online.

Python 3.8 and newer

>>> import os
>>> with os.add_dll_directory(“C:/sti/bin/pc-win64”):
… import understand

>>> understand.version()
1017
>>>

Sample Scripts
The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/python folder.

Happy Scripting!

Troubleshooting
The official python distribution from python.org includes a python3.dll which implements the stable ABI That’s what allows us to target python 3.2 – 3.5 with the same module. Essentially it’s just a wrapper that forwards to the python3x.dll. Some other distributions of Python such as Anaconda may not have the python3.dll, you may be able to copy in python3.dll from the official distribution.