Skip to content

Breaking API changes in 8.0

Understand 8.0 brings new Python API features, and a few of them change existing behavior. If you maintain scripts written for 7.x, review the three items below.

Authoritative migration notes

This page summarizes the known breaking changes. The always-current reference for your build ships in the product — Help → Python API Documentation. Check it before a large port, and confirm behavior against your installed version.

1. Metric is now a class of objects, not id strings

understand.Metric.list() now returns a list of understand.Metric objects instead of metric-id strings — bringing it in line with understand.Kind and the new understand.Graph, understand.AutomaticArch, and understand.Report documentation classes.

  • Name and description are now instance methods. Replace understand.Metric.description(id) / understand.Metric.name(id) with understand.Metric.lookup(id).description() / understand.Metric.lookup(id).name().
  • Ent.metric, Arch.metric, and Db.metric still accept either string ids or Metric objects, but they key the returned dictionary by whatever you passed in. So ent.metric(understand.Metric.list()) still runs, but if you index the result by an id string it may now need a Metric object key instead.

2. Plugin-author-only classes renamed with a Context suffix

Classes that only ever appear as an argument passed into a plugin function have been renamed to end with Context. This clarifies which class is the user-facing object and which is the plugin-author object (and frees the old names for the new documentation classes):

Old name New name
understand.MetricId understand.MetricContext
understand.Graph understand.GraphContext
understand.AutomaticArch understand.AutomaticArchContext
understand.IReport understand.ReportContext
understand.Check understand.CheckContext
understand.CheckViolation understand.ViolationContext

This mostly affects scripts that use type annotations, since these classes are rarely referred to by name otherwise. Update any annotations (e.g. def draw(graph: understand.GraphContext, target): …).

3. New "Begin Body" reference

A new Begin Body reference makes it easy to select just the body (or just the declaration) of an entity without walking there with a lexer. As a consequence, if you query "begin" references you now get both Begin and Begin Body results. Tighten such queries if you meant only one.

Where to go next