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.
- The Python API requires a 3.x installation of Python (Python 3.8 may not work and may result in an “Error importing API: DLL load failed while importing understand: The specified module could not be found”), you can grab it 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.
- Modify the PYTHONPATH environment variable to include the module location, which is SciTools/bin/<System>/Python. For Mac users, the python module is in Understand.app/Contents/MacOS/Python
- If you did not add Understand to the Path variable during installation, you will need to add the SciTools/bin/<System> directory to PATH.
- On non-Windows systems, you may need to create an STIHOME environment variable that points to the <SciTools> directory.
- To use the API you will need to put ‘import understand’ in your script.
- Test the API Setup by running the test script included with Understand:
python “c:\Program Files\SciTools\python\api_install_test.py”
- 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.
- 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/<system> 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.
The most up-to-date documentation is accessible from the Help menu in Understand. You can also read it from the Python Console with:
We also try to keep a current version of the Python documentation online.
The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/scripts/python folder.
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.