Skip to content

Write a plugin

A plugin is a Python script that Understand loads and runs from inside the GUI — a graph, an interactive report, a CodeCheck check, a metric, or an automatic architecture. Plugins use the same Python API as standalone scripts; the difference is that Understand calls your functions at the right moments.

One model, five types

A plugin is a plain Python file with the .upy extension. There is no base class — you just import understand and define top-level functions. Understand decides what kind of plugin it is from the one entry-point function you define:

If your script defines… It is a… How-to
draw(graph, target) Graph plugin Write a graph plugin
value(metric, target) Metric plugin Write a metric plugin
check(check, file) CodeCheck check Write a custom CodeCheck
generate(report, target, page) Interactive report (IReport) Write a report plugin
build(arch, db) Automatic architecture Write an architecture plugin

That's the whole taxonomy — there are exactly these five kinds. Each type also supports optional helper functions (name, description, tags, test_entity, test_global, init, …) documented on its how-to page, and each has a generated API guide with the full function contract: Graphs, Metrics, CodeCheck, Interactive Reports, and Architectures. A script that somehow defines more than one entry point is classified by the first match in the order above (check → draw → value → build → generate).

Python only

Write new plugins in Python (.upy). CodeCheck, Graph, and Report plugins were historically also available in Perl (.upl), but the Perl API is deprecated.

Where plugin files go

Understand discovers plugins by scanning two locations recursively for .upy (and legacy .upl) files:

  1. The plugins shipped with Understand (the app's plugins directory) — the large built-in library you enable in the Plugin Manager.

  2. Your per-user plugin directory, organized by type. Understand writes here automatically when you install a plugin (drag-and-drop or the Plugin Manager), so you rarely place files by hand:

    OS Per-user plugin base
    Windows %APPDATA%\SciTools\plugin\<Type>
    macOS ~/Library/Application Support/SciTools/plugin/<Type>
    Linux ~/.config/SciTools/plugin/<Type>

    <Type> is the subfolder for the plugin kind: Graph, Metric, Codecheck, IReport, or Arch.

The easiest way to install: drag the .upy onto the Understand main window and click Install when prompted — Understand detects the type and copies it into the right per-user subfolder. See Install & run plugins.

A typical workflow

Most people start from a working template rather than a blank file:

  1. In the Plugin Manager (Tools → Plugin Manager), find a template near what you want (filter by the Sample Template tag) and Customize it to get an editable copy.
  2. Make small changes and test as you go — run the plugin from its GUI menu, then Rescan Plugins after each edit to reload it.

Graph and report plugins render in the GUI, so develop them there. For plugins whose core logic is just data — metrics and CodeCheck checks — you can prototype that logic in a standalone Python script with upython first, then wrap it in the entry-point function. (Automatic architectures can go either way.)

Follow the type-specific how-to for the full function contract and a worked example, and the script cookbook for more samples.

Plugin gotchas

These apply to every plugin type — graphs, metrics, checks, reports, and architectures alike.

  • A broken plugin silently disappears. If the script has a syntax or import error, Understand can't classify it and it won't show up in the menus or the Plugin Manager.
  • You can't run a .upy from the command line. understand.open() refuses to open a database when the calling script is a .upy ("plugins must not open a database"), so a plugin can't be run standalone with upython. Prototype non-GUI logic in a plain .py (which can open a database), and test the plugin itself in the GUI.
  • Reload after every on-disk edit. Understand caches loaded plugins, so an edited file doesn't take effect until you click Rescan Plugins in the Plugin Manager — no restart needed for the plugin file itself.
  • Shared helper modules need a full restart. Rescan reloads the plugin file, but a separate .py module it imports is cached by Python for the session; editing that dependency requires restarting Understand.
  • Plugins run in a per-interpreter-GIL sub-interpreter. Each plugin runs in its own Python sub-interpreter with its own GIL, so any C-extension package it imports must support the per-interpreter GIL (multi-phase initialization) or the import fails. Pure-Python dependencies are unaffected.