Understand plugins are Python scripts run by Understand. There’s a tutorial for the Understand’s Python API that also includes writing an interactive report plugin. The Python API documentation also includes templates and information on writing plugins.
Creating a plugin file
Understand finds plugins by searching for files with “.upy” extensions in the plugins repository shipped with Understand and in the user’s application data directory. The plugin kind is determined by the presence of specific functions. So, the first step in creating a plugin is to create a file ending in “.upy” with the required functions. It’s easiest to start from the existing templates.
Creating a Plugin from the Plugin Manager
Most of the plugin templates shown in the Python API documentation are available in Understand’s plugin manager. Open the Plugin Manager from Tools -> Plugin Manager and select any type of plugin. Then set the filter to `Tags:"Sample Template"` (including the double quotes).
Select the template for the kind of plugin and then click customize. This creates a copy of the file in the editor with the file path set to the application data directory so Understand will be able to find the plugin. The file is not created until you save it.
Creating a Plugin Manually
Most templates are part of Understand’s plugin repository which is shipped with Understand. You can copy the template from the repository or create a file and copy the file contents from the Python API documentation.
| Plugin Kind | Repository Copy | API Documentation |
| Architecture | longname.upy | Architecture Plugins |
| Graph | calls.upy | Graph Plugins |
| Interactive Report | sample.upy | IReport Plugins |
| Metric | compatiability6-3.upy | Metric Plugins |
| Check | CodeCheck Plugins |
Next, your file needs to be in a location it can be found by Understand. The easiest way is to drag and drop your file onto Understand and select install. This will copy the file to the correct location for you. You can also use the “Add Plugin” button in the Plugin Manager. Or, you can manually copy your file to the platform specific location.
- Windows – %APPDATA%\SciTools\plugin
- Mac – /Users/username/Library/Application Support/SciTools/plugin/
- Linux – /home/username/.config/SciTools/plugin/
If your plugin depends on local .py files, those must be manually copied next to the .upy file.
Writing a plugin
The most important thing to be aware of when developing plugins is that Understand caches all plugins. Any time your plugin changes on disk, you MUST manually refresh the plugin cache to see the changes. You can refresh the plugin cache using the refresh button in the Plugin Manager or by setting a keyboard shortcut for the action.
You will also need to manually refresh the cache for Understand to find your plugin for the first time if you manually copied it to AppData or created it by customizing the template from the Plugin Manager.
Requirements
Understand uses the per-interpreter GIL feature that was introduced in Python 3.12 to allow multiple threads to access their own Python interpreter concurrently. The per-interpreter GIL configuration is incompatible with modules that use single-phase initialization. This means that plugins should only import native modules that support multi-phase initialization.
Tips
- If you started from a plugin template, make sure to change any name() and/or id() functions so that your plugin does not clash with the existing template.
- A template that is customized from the plugin manager or manually copied to AppData must be manually enabled through the plugin manager. Plugins added through drag and drop or with “Add Plugin” are enabled automatically.
- Only plugins without syntax errors will be visible in the Plugin Manager and Understand GUI.
- Refreshing the plugin cache will not reload any local .py files. So if you develop a suite of plugins with shared files and the shared .py files change, you must close and reopen the entire application to ensure the changes are loaded.