Db

class understand.Db

Bases: object

An Understand database

With the exception of understand.Db.close(), all methods require an open database. A database is opened with the module function understand.open(). Once opened, the database can be used to retrieve entities and architectures. Project level metrics are also available.

Methods Summary

add_annotation_file
annotations	Return a list of annotations for the database.
archs	Return a list of architectures that contain the entity
close	Close the database.
comparison_db	Return the comparison database associated with this database.
draw	Generate a graphics file for the database
ent_from_id	Return the ent associated with the id.
ents	Return a list entities in the database.
files	Return the list of file entities in the database.
language	Return a tuple with project languages
lexer	Open a lexer for a file or its contents.
lookup	Return a list of entities that match the specified name.
lookup_arch	Return the architecture with the given longname, or None if not found.
lookup_uniquename	Return the entity identified by uniquename.
metric	Return the metric value for each item in metriclist
metrics	Return a list of project level metric names.
metrics_treemap	Export a metrics treemap
name	Return the filename of the database.
relative_file_name	Return the relative file path.
root_archs	Return the root architectures for the database.
violations	Return a list of violations for the database.

Methods Documentation

add_annotation_file() → None

Deprecated since version 6.0.

annotations() → list[understand.Atn]

Return a list of annotations for the database.

Return type:

list[understand.Atn]

Returns:

all the annotations in the database.

Raises:

understand.UnderstandError – if the database is not open

archs(ent) → list[understand.Arch]

Return a list of architectures that contain the entity

Parameters:

ent (understand.Ent) – the entity

Return type:

list[understand.Arch]

Returns:

architecture that contain the entity

Raises:

understand.UnderstandError – if the database is not open

close() → None

Close the database.

This allows a new database to be opened. It will never throw an error and is safe to call even if the database is already closed. After the database is closed, accessing objects associated with the database (ents, refs, …) can cause Python to crash.

comparison_db() → understand.Db

Return the comparison database associated with this database.

Return type:

understand.Db

Returns:

the comparison database if set, None otherwise.

Raises:

understand.UnderstandError – if the database is not open

draw(graph, filename[, options[, variant]]) → None

Generate a graphics file for the database

Parameters:

• graph (str) – the name of the graph to generate

• filename (str) – the output file

• options (str or None) – optional, graph options

• variant (str or None) – the variant of the graph to generate

Return type:

None

Raises:

understand.UnderstandError – if an error occurs

Available graphs vary by database, but the name will be the same as the name in the Understand GUI.

The output format is determined by the file name extension. Supported extensions are jpg, png, svg, vsdx, and vdx. Some graphs support dot file format.

The parameter options is used to specify parameters to generate the graphics. The format of the options string is “name=value”. Multiple options are seperated with a semicolon. spaces are allowed and are significant between multi-word field names, whereas, case is not significant. The valid names and values are the same as appear in that graph’s right click menu and vary by view. They may be abbreviated to any unique prefix of their full names.

The parameter variant is used to select from the available variants for the graph. If a variant is not specified, then a default variant will be used.

If an error occurs, an UnderstandError will be raised. Some possible errors are:

• Draw Too Large - failed to allocate memory for the image

• Unknown Graph - the graph name did not match a known graph

• Unsupported File Type - unsupported file format

ent_from_id(id) → understand.Ent

Return the ent associated with the id.

Parameters:

id (int) – the id

Return type:

understand.Ent

Returns:

the associated entity

Raises:

understand.UnderstandError – if the database is not open

The id is obtained using understand.Ent.id(). This should only be called for identifiers that have been obtained while the database has remained open. When a database is reopened, the identifier is not guaranteed to remain consistent and refer to the same entity.

ents([kindstring]) → list[understand.Ent]

Return a list entities in the database.

Parameters:

kindstring (str or None) – optional, a language-specific entity filter string

Returns:

a list of entities

Return type:

list[understand.Ent]

Raises:

understand.UnderstandError – if the database is not open

files() → list[understand.Ent]

Return the list of file entities in the database.

Returns:

a list of entities

Return type:

list[understand.Ent]

language()

Return a tuple with project languages

Return type:

tuple(str)

Returns:

the languages enabled in the project

Raises:

understand.UnderstandError – if the database is not open

Possible language names are: “Ada”, “C++”, “C#”, “Fortran”, “Java”, “Jovial”, “Pascal”, “Python”, “VHDL”, or “Web”. C is included with “C++” This will throw a UnderstandError if the database has been closed.

lexer(filename[, contents]) → understand.Lexer

Open a lexer for a file or its contents.

Parameters:

• filename (str) – the source file name

• contents (str) – optional, contents of the file to lex

Return type:

understand.Lexer

Returns:

a lexer for the file or its contents

Lexer properties are read from project settings. The optional contents parameter may be specified instead of reading the whole file.

lookup(name[, kindstring]) → list[understand.Ent]

Return a list of entities that match the specified name.

Parameters:

• name (re.Pattern or str) – a regular expression, either compiled or as a string. By default, regular expressions are case sensitive. See below for a case insensitive example.

• kindstring (str or None) – optional, a language-specific entity filter string

Return type:

list[understand.Ent]

Returns:

a list of matching entities

Raises:

understand.UnderstandError – if the database is not open

An example of a case insensitive search:

import re
db.lookup(re.compile("searchstring",re.I))

The re.I flag is for case insensitivity. Otherwise, the lookup command can be run simply:

db.lookup("searchstring")

An example with a kindstring is:

db.lookup(".Test.","File")

which would return a list of file entities containing “Test” (case sensitive) in their names.

lookup_arch(longname) → understand.Arch

Return the architecture with the given longname, or None if not found.

Parameters:

longname (str) – the architecture’s long name

Return type:

understand.Arch or None

Returns:

the architecture if found, None otherwise

Raises:

understand.UnderstandError – if the database is not open

lookup_uniquename(uniquename) → understand.Ent

Return the entity identified by uniquename.

Parameters:

uniquename (str) – the unique name of the entity, returned by understand.Ent.uniquename()

Return type:

understand.Ent or None

Returns:

the entity if found or None

Raises:

understand.UnderstandError – if the database is not open

metric(metriclist [,format]) -> dict(str, metric value)

metric(metric[, format]) → metric value

Return the metric value for each item in metriclist

Parameters:

• metriclist (list(str) or tuple(str)) – a list or tuple of metric names

• metric (str) – a metric name

• format (str) – optional, a string equal to “auto”, “raw” or “string”. It defaults to “auto” which returns integer values as integers and real values as formatted strings. Use “raw” to get real values as floats. Use “string” to get integer values as formatted strings.

Return type:

dict(str, metric value) for metriclist or metric value for metric

Raises:

understand.UnderstandError – if the database is not open

Metric values can be ints, floats, formatted strings, or None if the metric is not available.

metrics() → list[str]

Return a list of project level metric names.

Return type:

list[str]

Returns:

a list of project level metric names.

Raises:

understand.UnderstandError – if the database is not open

metrics_treemap(file, sizemetric, colormetric[, enttype[, arch]]) → None

Export a metrics treemap

Parameters:

• file (str) – the output file name. This must end in .jpg or .png

• sizemetric (str) – the API metric name of the metric determining size.

• colormetric (str) – the API metric name of the metric determining color.

• enttype (str) – optional, the type of entities to use. This must be “file” “class” or “function”. “file” is the default.

• arch (understand.Arch) – optional, an architecture to group by. If not specified the graph will be flat.

Return type:

None

Raises:

understand.UnderstandError – if the database is not open

name() → str

Return the filename of the database.

Return type:

str

Returns:

the filename of the database

Raises:

understand.UnderstandError – if the database is not open

relative_file_name(absolute_path) → str

Return the relative file path.

Parameters:

absolute_path (str) – the file path

Return type:

str

Returns:

the relative file path

Raises:

understand.UnderstandError – if the databaes is not open

This is like undrstand.Ent.relname() but for an arbitrary path.

root_archs() → list[understand.Arch]

Return the root architectures for the database.

Return type:

list[understand.Arch]

Returns:

the root architectures

Raises:

understand.UnderstandError – if the database is not open

violations() → list[understand.Violation]

Return a list of violations for the database.

Return type:

list[understand.Violation]

Returns:

all the violations in the database.

Raises:

understand.UnderstandError – if the database is not open