Many new features are coming to the Python API with the release of Understand 8.0. These amazing new features do come with a few growing pains. If you’re maintaining existing scripts, you might need to make a few updates.


1. For the built-in documentation, the Metric class was changed so that the Metric.list class method returns a list of understand.Metric options instead of a list of string metric ids. This brings it into alignment with the existing understand.Kind class, and the new understand.Graph, understand.AutomaticArch, and understand.Report documentation classes. So


  • Any calls to understand.Metric.description(id) or understand.Metric.name(id) need to be replaced with understand.Metric.lookup(id).description() and understand.Metric.lookup(id).name(), because the description and name are now instance methods.
  • Check any calls to understand.Metric.list to ensure they will work with understand.Metric instance objects instead of strings. Note that Ent.metric, Arch.metric, and Db.metric accept string ids or understand.Metric objects, but uses the input as keys in the output. So “ent.metric(understand.Metric.list())” call will still work, but the code using the result may need to be updated since the dictionary key in that case would be the understand.Metric instance objects passed in, rather than the id string.


2. For both the built-in documentation and the web documentation, any class that is only available when it is passed into a plugin script has been renamed to end with Context. This will likely only impact scripts that use type annotations since referring to these classes by name isn’t common. This name change makes it clearer which is the user facing object and which is the plugin author object, and freed up names for the built in documentation objects. The name changes are:

  • understand.MetricId -> understand.MetricContext
  • understand.Graph -> understand.GraphContext
  • understand.AutomaticArch -> understand.AutomaticArchContext
  • understand.IReport -> understand.ReportContext
  • understand.Check -> understand.CheckContext
  • understand.CheckViolation -> understand.ViolationContext


3. We've added a new 'Begin Body' reference making it easier to select just the body or just the declaration without having to use a lexer to walk to the right place. If you're currently querying "begin" references then it will now return both the "Begin" and "Begin Body" references.