Skip to content

Python API tutorial 6: interactive reports

An Interactive Report (IReport) opens a text window in Understand that displays information you choose. It can target the whole project (Db), an architecture (Arch), or a single entity (Ent), and can be as simple or as rich as you like.

See one that ships

Right-click any entity in your project and choose Interactive Reports → API Info to see a built-in IReport that dumps all the API information available for that entity.

The generate hook

IReport plugins are upython scripts with the same plugin structure as the graph plugin in tutorial 5. The one required function is generate, where the report logic lives. A basic template:

import understand

def name():
    return "Tutorial: Basic Report"

# Report generation
def generate(report, target):
    """
    Required — generate the report.
    """
    # If the report can target multiple object types, use isinstance to branch.
    if isinstance(target, understand.Arch):
        report.print("arch: ")
    if isinstance(target, understand.Ent):
        report.print("ent: ")
    if isinstance(target, understand.Db):
        report.print("db: ")

    report.bold()
    # name() exists on entities, architectures, and databases.
    report.print(target.name())
    report.nobold()
    report.print("\n")

    # Retrieve an option defined in an optional init(report, target) hook:
    option = report.options().lookup("test")
    report.print("option: {}\n".format(option))
  • report is the IReport object — an understand.ReportContext — and you write output through its methods. The full IReport reference is the Interactive Report API guide.
  • target is what the user selected: a Db, Arch, or Ent. Use isinstance to handle each.
  • report.print(text) writes text; report.bold() / report.nobold() toggle bold.
  • report.options().lookup("test") reads an option value (options are declared in an optional init(report, target) hook).

Optional pageId parameter

generate may take an optional third parameter, def generate(report, target, pageId), used for multi-page (paginated) reports. It's an empty string on the first generation. The two-parameter form shown here is fine for a report that doesn't paginate.

Next

You've built a graph plugin and a report plugin. In the final tutorial you'll pull CodeCheck violations into a report.

← Tutorial 5: graphs  ·  → Tutorial 7: retrieving violations