IReport¶

class understand.IReport¶

Bases: object

IReport plugin report object

This object is provided to an IReport plugin’s init and generate functions. Use options to define and lookup custom options. The remaining methods control the report output.

Methods Summary

`align`	Alignment for blocks of text: left, right, or center.
`arch`	Begin or end an architecture link.
`bgcolor`	Set the report background color.
`bold`	Set the bold attribute.
`breadcrumbs`	Set the breadcrumbs that appear in the report header.
`cache`	Return a `cache` that can be used to store, retrieve, and share data.
`compare`	Begin or end an entity comparison link.
`db`	Return the database associated with this report.
`draw`	Draw the requested graph.
`entity`	Begin or end an entity link.
`fontbgcolor`	Set font background color attribute.
`fontcolor`	Set font foreground color attribute.
`heading`	Begin or end a heading text range.
`hover`	Begin or end hover text range.
`is_aborted`	Return True if an abort has been requested.
`italic`	Set the italic attribute.
`nobold`	Disable the bold attribute.
`noitalic`	Disable the italic attribute.
`options`	Return the Options object associated with this report.
`pagelink`	For reports with pages, begin or end a link to a page.
`print`	Print text to the report with the currently set attributes.
`progress`	Report progress value in percent and optional message.
`syncfile`	Begin or end a file link.
`table`	Begin or end a table.
`tablecell`	Move to the next cell in the table.
`tree`	Begin or end a tree branch.
`underline`	Set the underline attribute.

Methods Documentation

align(alignment) → None¶

Alignment for blocks of text: left, right, or center.

Parameters:: color (str) – left, right, center, or None for default
Return type:: None

arch([arch]) → None¶

Begin or end an architecture link.

Links do not stack. Link priority is entity or compare, arch, syncfile, and then pagelink.

Parameters:: arch (understand.Arch or None) – optional, the arch to link to or None to end the link
Return type:: None

bgcolor(color) → None¶

Set the report background color.

Parameters:: color (str) – the new background color
Return type:: None

bold(bold=True) → None¶

Set the bold attribute.

Parameters:: bold (bool) – optional, turn bold on or off. True (on) by default.
Return type:: None

breadcrumbs(pages, idx[, names]) → None¶

Set the breadcrumbs that appear in the report header.

This only has an effect if it appears before all other report output calls (like print, tree, table, etc).

Parameters:

pages (list(str) or tuple(str)) – The list of pages to show in the breadcrumb trail
idx (int) – the index in the list of the current page
names (list(str) or tuple(str)) – Optional, display names for the page ids in pages

Return type:

None

cache([id]) → understand.Cache¶

Return a cache that can be used to store, retrieve, and share data. If id is not given, it will be a script-specific identifier. This function may return None if caching is not available.

Return type:: understand.Cache
Returns:: a cache object or None

compare([left_ent[, right_ent]]) → None¶

Begin or end an entity comparison link.

Links do not stack. Link priority is entity or compare, arch, syncfile, and then pagelink.

Parameters:

left_ent (understand.Ent or None) – optional, the entity that will appear in the left panel of a diff view.
right_ent (understand.Ent or None) – optional, the entity that will appear in the right panel of a diff view.

Return type:

None

db() → understand.Db¶

Return the database associated with this report.

Return type:: understand.Db
Returns:: the database

draw(target, graph[, options[, variant[, title]]]) → None¶

Draw the requested graph.

See the draw methods for entities, architectures and databases for more information on available graphs, and the graph, options, and variant arguments. Unlike those methods, this method renders the image in Understand instead of to a file. The image will end any in-progress tree or table.

Parameters:

target (understand.Ent or understand.Arch or understand.Db.) – the object to draw the graph for.
graph (str) – the name of the graph to generate
options (str or None) – optional, graph options
variant (str or None) – the variant of the graph to generate
title (str) – the title to display, defaults to the graph title

Return type:

None

entity([entity]) → None¶

Begin or end an entity link.

Links do not stack. Link priority is entity or compare, arch, syncfile, and then pagelink.

Parameters:: entity (understand.Ent or None) – optional, the entity to link to or None to end the link
Return type:: None

fontbgcolor([color]) → None¶

Set font background color attribute.

Parameters:: color (str or None) – the background color
Return type:: None

fontcolor([color]) → None¶

Set font foreground color attribute.

Parameters:: color (str or None) – the foreground color
Return type:: None

heading([level]) → None¶

Begin or end a heading text range.

Parameters:: level – optional, a level between 1 and 6 inclusive. None or 0 to end the range
Return type:: None

hover([text]) → None¶

Begin or end hover text range.

Parameters:: text (str) – optional, the hover text or None to end the range
Return type:: None

is_aborted() → bool¶

Return True if an abort has been requested.

Return type:: bool
Returns:: True if an abort has been requested

italic(italic=True) → None¶

Set the italic attribute.

Parameters:: italic (bool) – optional, turn italic on or off. True (on) by default.
Return type:: None

nobold() → None¶

Disable the bold attribute.

This is equivalent to:

report.bold(False)

noitalic() → None¶

Disable the italic attribute.

This is equivalent to:

report.italic(False)

options() → understand.Options¶

Return the Options object associated with this report.

Return type:: understand.Options
Returns:: the options object

pagelink([pageId]) → None¶

For reports with pages, begin or end a link to a page.

Links do not stack. Link priority is entity or compare, arch, syncfile, and then pagelink.

Parameters:: pageId (str) – the page identifier to link or None to end the link
Return type:: None

print(text) → None¶

Print text to the report with the currently set attributes.

Parameters:: text (str) – the text to print
Return type:: None

progress(value[, msg]) → None¶

Report progress value in percent and optional message.

Parameters:

value (int) – the current progress
msg (str or None) – optional, text describing the current state/progress

Return type:

None

syncfile([file[, line[, column]]]) → None¶

Begin or end a file link.

Links do not stack. Link priority is entity or compare, arch, syncfile, and then pagelink.

Parameters:

file (str or None) – the file path
line (int or None) – the line number
column (int or None) – the column number

Return type:

None

Line and column numbers are 1-based.

table(cols) → None¶

Begin or end a table.

Parameters:: cols (json str or list(str) or tuple(str) or None) – column information. If empty or none, ends the table.
Return type:: None

Tables and trees do not mix. Calling this function will end a tree.

The parameter, cols, should be None to end the table.

For a simple table, cols is a list(str) or tuple(str) with the column names. The length determines the number of columns in the table. For example:

report.table(["Column Name 1","Column Name 2"])

for a table with two columns.

Tables displayed in the Understand GUI can be interactively sorted and filtered. To create a interactive table, the cols parameter should be a json array of json objects. Each object contains key/value settings for a column. The supported key/values are:

“name”: the name of the column
“filtertype”: required. The value can be the string literal “string” for text data, or the string literal “numeric” for numeric data, or a json array of strings for a choices filter (displayed as a combo box).
“filtervalue”: optional, an initial filter value. For a numeric filter, this value should be a number, not the string representation of a number.
“filteroperation”: optional, the initial operation for a numeric filter. The value should be a string matching one of the options in the numeric filter dropdown (“>”, “=” and so on)
“sort”: optional, set the initial column sorted by. Interactive tables are always sorted. The default is the first column. The value for this key should be either “ascending” or “descending” for the direction of the sort. Setting this key on more than one column has undefined behavior.

An example of a filtered table json argument is

[{
  "name" : "Column 1",
  "filtertype": "string"
 },{
  "name" : "Column 2",
  "filtertype": "numeric",
  "filteroperation": ">",
  "filtervalue": 10,
  "sort": "ascending"
 },{
  "name" : "Column 3",
  "filtertype" : ["Yes", "No"]
}]

Note that the report writer is responsible for populating a filtered table with appropriate values. The API provides no type checking on the values provided to each table cell.

tablecell() → None¶

Move to the next cell in the table.

There must be a call to table to define the number of columns in the table. Then this function move to the next cell in the table, creating a new row if necessary.

Return type:: None

tree([level[, state]]) → None¶

Begin or end a tree branch.

Parameters:

level (int or None) – the level of the tree or 0 to end the tree. Defaults to 0.
state (bool or None) – the open (True) or closed (False) state of this branch. Defaults to False (closed).

Return type:

None

underline(underline=True) → None¶

Set the underline attribute.

Parameters:: underline (bool) – optional, turn underline on or off. True (on) by default.
Return type:: None

IReport¶

Understand Python API

Navigation

Related Topics