GraphContext

class understand.GraphContext

Bases: object

Graph plugin graph object

A graph object is provided to a graph plugin’s init(graph) and draw(graph, target) functions and represents the root of a graph. Clusters are also represented as Graph objects. Use the root graph to set default Graphviz attributes, define and retrieve custom options and provide a legend. Use any graph object (the root or clusters) to add a node, an edge and a cluster. You can also set graphviz attributes for the graph object.

GraphContext objects are hashable and compare equal when they refer to the same underlying Graphviz subgraph.

A read-only Graph object can be returned from draw.

Methods Summary

attributes	Return Graphviz attributes set on this graph or cluster.
cache	Return a cache that can be used to store, retrieve, and share data.
cluster	Add a cluster subgraph to the graph.
clusters	Return the clusters (subgraphs) directly contained in this graph.
db	Return the database associated with this graph.
default	Set graph defaults.
edge	Add an edge between two nodes in the graph.
edge_defaults	Return default edge attributes in effect for this graph.
edges	Return edges directly attached to this graph or cluster.
id	Return this graph or cluster's id (Graphviz graph name).
is_aborted	Return True if an abort has been requested.
legend	Return the Legend object associated with this graph.
node	Add a node to the graph.
node_defaults	Return default node attributes in effect for this graph.
nodes	Return nodes directly contained in this graph or cluster.
options	Return the Options object associated with this graph.
set	Set graph attribute.
sync	Sync graph or cluster to a reference, entities, or file location.
synced_data	Return this graph or cluster's current sync data.

Methods Documentation

attributes() → dict[str, str]

Return Graphviz attributes set on this graph or cluster.

Return type:

dict[str, str]

cache(id) → understand.Cache

Return a cache that can be used to store, retrieve, and share data. Caches are globally accessible and modifiable from all plugins so graph plugins would normally use this only to access built-in caches. This function may return None if caching is not available.

Return type:

understand.Cache

Returns:

a cache object or None

Raises:

RuntimeError – on read-only graphs returned from draw (raw graph format)

cluster(label='', arch=None) → understand.GraphContext

Add a cluster subgraph to the graph.

Parameters:

• label (str or None) – optional, a label for the cluster

• arch (understand.Arch or None) – an architecture to sync

Return type:

understand.GraphContext

Returns:

the new cluster

Raises:

RuntimeError – on read-only graphs returned from draw (raw graph format)

clusters() → list[understand.GraphContext]

Return the clusters (subgraphs) directly contained in this graph.

Return type:

list[understand.GraphContext]

db() → understand.Db

Return the database associated with this graph.

Return type:

understand.Db

Returns:

the database

default(name, value, kinds='') → None

Set graph defaults.

Parameters:

• name (str) – the attribute name

• value (str) – the attribute value

• kinds (str or None) – optional, the kinds this applies to. Valid kinds are “graph”, “node”, and “edge”. This defaults to “graph,node,edge” when not provided, applying to all three kinds.

Return type:

None

Raises:

RuntimeError – on read-only graphs returned from draw (raw graph format)

Reference Graphviz for available attributes.

# set the default color for nodes and graphs but not edges
graph.default("color","blue","node,graph")

edge(node1, node2, label='') → understand.Edge

Add an edge between two nodes in the graph.

Parameters:

• node1 (understand.Node) – the tail (source) node of the edge

• node2 (understand.Node) – the head (destination) node of the edge

• label (str or None) – optional, a label for the edge

Return type:

understand.Edge

Returns:

the new edge

Raises:

RuntimeError – on read-only graphs returned from draw (raw graph format)

edge_defaults() → dict[str, str]

Return default edge attributes in effect for this graph.

Return type:

dict[str, str]

edges() → list[understand.Edge]

Return edges directly attached to this graph or cluster.

Return type:

list[understand.Edge]

id() → str

Return this graph or cluster’s id (Graphviz graph name).

Return type:

str

is_aborted() → bool

Return True if an abort has been requested.

Return type:

bool

Returns:

True if an abort has been requested

Raises:

RuntimeError – on read-only graphs returned from draw (raw graph format)

legend() → understand.Legend

Return the Legend object associated with this graph.

Return type:

understand.Legend

Returns:

the legend object for the graph

Raises:

RuntimeError – if the graph was not created in a plugin context

Defining a legend is optional. Legends are only visible in the Understand GUI and can be toggled on and off from the graph toolbar.

node(label='', ent=None) → understand.Node

Add a node to the graph.

Parameters:

• label (str) – The node’s label

• ent (understand.Ent or None) – an entity to sync

Return type:

understand.Node

Returns:

the new node

Raises:

RuntimeError – on read-only graphs returned from draw (raw graph format)

Providing an ent argument is equivalent to calling sync on the returned node object:

node = graph.node("label")
node.sync(ent)

node_defaults() → dict[str, str]

Return default node attributes in effect for this graph.

Return type:

dict[str, str]

nodes() → list[understand.Node]

Return nodes directly contained in this graph or cluster.

Return type:

list[understand.Node]

options() → understand.Options

Return the Options object associated with this graph.

Return type:

understand.Options

Returns:

the associated options

Raises:

RuntimeError – if the graph was not created in a plugin context

Defined options will appear in the context menu of the graph. Retrieve the values using lookup. Note that graph options only support define, not any of the ui Option methods such as <understand.Options.checkbox>().

set(name, value) → None

Set graph attribute.

Parameters:

• name (str) – the attribute name

• value (str) – the attribute value

Return type:

None

Raises:

RuntimeError – on read-only graphs returned from draw (raw graph format)

Refer to Graphviz for available attributes. Unlike default, this sets the attribute for this graph object only.

sync(ref) → None

sync(arch) → None

sync(ent) → None

sync(ent, comparison_ent) → None

sync(file, line=0, column=0) → None

Sync graph or cluster to a reference, entities, or file location.

Parameters:

• ref (understand.Ref) – a reference to sync

• arch (understand.Arch) – an architecture to sync

• ent (understand.Ent) – an entity to sync

• comparison_ent (understand.Ent or None) – an entity from the comparison database

• file (understand.Ent or str) – a file entity or file path

• line (int or None) – optional, a line number

• column (int or None) – optional, a column number

Return type:

None

Raises:

RuntimeError – on read-only graphs returned by draw (raw graph format)

Line and column numbers are 1-based.

For entity comparison, ent or comparison_ent may be None to show added/removed entities.

synced_data() → object

Return this graph or cluster’s current sync data.

Return type:

understand.Ref or understand.Arch or understand.Ent or tuple[understand.Ent | None, understand.Ent | None] or dict[str, str | int | understand.Ent] or list[understand.Ref] or None

Returns:

sync data currently associated with this object

Locations are returned as dictionaries with a “file” key and optional keys: “entity”, “line”, “column”, “end_line”, and “end_column”. Line and column numbers are 1-based.

Entity comparisons are returned as a tuple with left and right entities. Either entity may be None, usually representing an added/removed entity.

Built-in graphs have more sync types than supported from plugins. Specifically, locations can have end_line and end_column (Control Flow graphs are an example) and edges often sync a list of references.