The Understand Python API gives scripts access to everything Understand knows about your code — entities, references, metrics, and dependencies — and powers custom checks, graphs, and reports.

Python API: getting started · Sample & solution scripts

Options#

class understand.Options#

Bases: object

An options object

Understand graphs, reports, and other plugins support options. This class is the interface for defining and retrieving options.

Setting options#

Methods such as draw and report accept an options argument. That argument can be either a str or an options object.

When an options string is used, the format of the string is “name=value”. Multiple options are seperated with a semicolon. spaces are allowed and are significant between multi-word field names, whereas, case is not significant. The valid names and values are the same as appear in that GUI. They may be abbreviated to any unique prefix of their full names. Some examples are:

“Layout=Crossing; name=Fullname;Level=AllLevels”
“Comments=On;Show Entity Name=On”

An Option object can be used instead of an option string. Retrieve an Option object for the specific graph or report being requested using Graph.options and Report.options respectively. Then use list to discover existing options. Set option values with the set.

Important: Note that the option string format uses the option text, not the option name, whereas the set method uses the option name, not the text. Cast the option object to a string to get the option string format (showing only non-default option values).

Defining options#

Plugins use this class to define options that users can change. Find the value of an option with lookup.

In builds before 7.1 (1221) Graph plugins only support defining options with the define method and ReportContext and CheckContext plugins only support defining options with checkbox, checkbox_horiz, checkbox_vert, choice, file, integer, radio_horiz, radio_vert, or text.

In builds 7.1 (1221) and later Graph plugins may use any option method because options are displayed in the graph sidebar. The define method is equivalent to the choice method with the text and name set to the name. However, the context menu only supports checkbox, checkbox_horiz, checkbox_vert, choice, radio_horiz and radio_vert options The integer method can appear in the context menu when given a range (builds 1225+).

Methods Summary

`checkbox`	Create a checkbox option.
`checkbox_horiz`	Create a horizontal group of checkbox options.
`checkbox_vert`	Create a vertical group of checkbox options.
`choice`	Create a choice option.
`define`	Define a context menu option.
`file`	Create a file option.
`integer`	Create an integer option.
`label`	Create a label.
`list`	Return a list of this Options object's option definitions.
`lookup`	Lookup an option value by name.
`radio_horiz`	Create a horizontal radio box option.
`radio_vert`	Create a vertical radio box option.
`set`	Set an option value by name.
`text`	Create a text option.

Methods Documentation

checkbox(name, text, default=False) → None#

Create a checkbox option.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the check box
default (bool or None) – optional, the check state. False (unchecked) by default

Return type:

None

This method was not available for Graph options before 7.1 (build 1221).

checkbox_horiz(name, text, choices, default=[]) → None#

Create a horizontal group of checkbox options.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the check boxes
choices (list[str]) – the options to choose from
default (list[str] or None) – optional, the list of options currently checked

Return type:

None

This method was not available for Graph options before 7.1 (build 1221). When lookup is called, a list[str] containing the options that were checked is returned:

# Create option with three checkboxes where items 2 and 3 are initally checked
option.checkbox_horiz("HorizCheck","Displayed Text",["Item1","Item2","Item3"],["Item2","Item3"])
# Lookup option later
option.lookup("HorizCheck")
# Returns None if nothing checked, or list of checked items such as
# ["Item1","Item2","Item3"]

checkbox_vert(name, text, choices, default=[]) → None#

Create a vertical group of checkbox options.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the check boxes
choices (list[str]) – the options to choose from
default (list[str] or None) – optional, the list of options currently checked

Return type:

None

This method was not available for Graph options before 7.1 (build 1221). When lookup is called, a list[str] containing the options that were checked is returned:

# Create option with three checkboxes where items 2 and 3 are initally checked
option.checkbox_vert("VertCheck","Displayed Text",["Item1","Item2","Item3"],["Item2","Item3"])
# Lookup option later
option.lookup("VertCheck")
# Returns None if nothing checked, or list of checked items such as
# ["Item1","Item2","Item3"]

choice(name, text, choices, default='') → None#

Create a choice option.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the choices combination box
choices (list[str]) – the options to choose from
default (str or None) – optional, the default choice

Return type:

None

This method was not available for Graph options before 7.1 (build 1221).

define(name, values, value='') → None#

Define a context menu option.

Parameters:

name (str) – the option name. This appears as a graph menu option.
values (list[str]) – the possible values for the option. These appear in a submenu beneath the option name.
value (str or None) – the default value for the option.

Return type:

None

Before 7.1 (build 1121) this method was not valid for CheckContext or ReportContext plugins. Now it is the equivalent of choice with id and text both set to the name.

file(name, text, default) → None#

Create a file option.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the file entry field
default (str or None) – optional, the default file. “” if not provided

Return type:

None

This method was not available for Graph options before 7.1 (build 1221).

integer(name, text, default) → None#

Create an integer option.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the integer entry field
default (int or None) – optional, the default value. 0 if not provided
min (int) – optional, the minimum value of the spin box. 0 if not provided
max (int) – optional, the maximum value of the spin box. 1000000 if not provided

Return type:

None

This method was not available for Graph options before 7.1 (build 1221). The min and max parameters were added in build 1225.

label(name, text) → None#

Create a label.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display

Return type:

None

This method was not available for Graph options before 7.1 (build 1221).

list() → list[dict[str, Any]]#

Return a list of this Options object’s option definitions.

Returns:: one dictionary per option definition. Dictionary keys: “name” (str), “type” (str), “text” (str), and optional keys “default_value”, “choices”, “min”, and “max” when applicable.
Return type:: list[dict[str, Any]]

lookup(name) → Any#

Lookup an option value by name.

Parameters:: name (str) – the option name
Returns:: the value. The type of the value depends on the type of the option. For example, checkbox options will be True or False, integer options are int, other option types are str.

radio_horiz(name, text, choices, default='') → None#

Create a horizontal radio box option.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the radio boxes
choices (list[str]) – the options to choose from
default (str or None) – optional, the default choice

Return type:

None

This method was not available for Graph options before 7.1 (build 1221).

radio_vert(name, text, choices, default='') → None#

Create a vertical radio box option.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the radio boxes
choices (list[str]) – the options to choose from
default (str or None) – optional, the default choice

Return type:

None

This method was not available for Graph options before 7.1 (build 1221).

set(name, value) → None#

Set an option value by name.

Parameters:

name (str) – the option name
value – the new option value

Return type:

None

Using this method from a plugin implementation outside init()/define_options() has undefined behavior. The intended use case is for Options objects retrieved from plugin catalog objects (for example, Report.options).

text(name, text, default) → None#

Create a text option.

Parameters:

name (str) – the internal name to use with lookup
text (str) – the text to display next to the text entry field
default (str or None) – optional, the default text. “” if not provided

Return type:

None

This method was not available for Graph options before 7.1 (build 1221).