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.
As of build 1054 Understand bundles its own simplified version of Python (upython.exe) so you can easily get started with the API. Simply import understand into your script and run the script with the upython executable:
c:\Program Files\SciTools\pc-win64>upython >>> import understand >>> understand.version() 1055 >>>
Tutorials and Examples
There are two concepts that are critical for writing API scripts. Those concepts are entities and references. An entity is a decreet piece of code such as a class, function or object. A reference is a connection between to entities. A function calls another function or a class uses and object. A good explanation of entities, references and how they interact can be found here.
We also have a public Github repository with hundreds of checks and examples. Checkout it out here.
We have a brief tutorial using the Perl API. While the syntax is a little different for Python, the concepts still apply. Checkout the API tutorials for more help writing your own scripts.
Our blog also has several articles on using the API and how to solve various problems. These articles don't just provide the script, but explain how the script works and how it was built.
Documentation
The most up-to-date documentation is accessible from the Help menu in Understand. Select Help->Python API Documentation. You can also access it here.
Sample Scripts
The documentation includes some samples. More detailed example scripts are shipped with Understand in the SciTools/plugins/scripts/python folder ( SciTools/scripts/python in older versions of Understand ).
Let us know if you need help, and Happy Scripting!
Let us Help
Sometimes we need these custom items but we don't have the manpower or the time to get it done and we're just feeling overwhelmed. If you fall into this category, then reach out to us at support@scitools.com and we will work with you to determine exactly what you need, get you a quote, and get the job done for you as quickly as possible.
Custom Python Installation
If you want to use custom Python libraries you will need to add Understand to your own Python installation following these steps:
- Understand 6.5 and newer require a 3.12 or newer installation of Python. 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.
- Modify the PYTHONPATH environment variable to include the module location, which is c:\Program Files\SciTools\bin\pc-win64\Python.
- Edit the PATH environment variable to c:\Program Files\SciTools\bin\pc-win64
- Linux Only: Set LD_LIBRARY_PATH to scitools/bin/linux64
- Test the API Setup by running the test script included with Understand:
python “c:\Program Files\SciTools\python\api_install_test.py” - In your script add import understand
- 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
>>>Cygwin
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.
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+ 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.