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

`annotations`	Return a list of annotations for the database.
`archs`	Return a list of architectures that contain the entity
`automatic_arch`	Create a temporary architecture from an automatic architecture
`close`	Close the database.
`comparison_db`	Return the comparison database associated with this database.
`draw`	Generate graph output
`ent_from_id`	Return the ent associated with the id.
`ents`	Return a list of 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_treemap`	Export a metrics treemap
`name`	Return the filename of the database.
`relative_file_name`	Return the relative file path.
`report`	Generate a report for the database.
`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, implicit=False) → list[understand.Arch]¶

Return a list of architectures that contain the entity

Parameters:

ent (understand.Ent) – the entity
implicit (bool or None) – optional, if True return architectures that contain any of the entity’s parents. False by default.

Return type:

list[understand.Arch]

Returns:

architectures that contain the entity

Raises:

understand.UnderstandError – if the database is not open

automatic_arch(automatic_arch, options=None, name='') → understand.Arch¶

Create a temporary architecture from an automatic architecture

The architecture is temporary and lasts until the project is closed.

Parameters:

automatic_arch (str or understand.AutomaticArch) – plugin to run, by display name or AutomaticArch object
options (str or understand.Options or None) – optional, options string or Options
name (str or None) – optional, root name. Defaults to the AutomaticArch name.

Return type:

understand.Arch

Raises:

understand.UnderstandError – if the database is not open, the plugin is unknown, it is not valid for this project, options fail to load, or generation fails

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=None, variant='', format='') → bytes | understand.GraphContext | None¶

Generate graph output

Parameters:

graph (str or understand.Graph) – the graph to generate
filename (str or None) – output path when writing to disk; omit when using format
options (str or understand.Options or None) – optional, graph options
variant (str or None) – the variant of the graph to generate
format (str or None) – in-memory export format

Return type:

bytes or understand.GraphContext or None

Returns:

None after a successful export when filename is given; a read-only GraphContext when format is “raw”; otherwise graph bytes for the requested in-memory format.

Raises:

understand.UnderstandError – if an error occurs

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 of 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

For example, get a list of all the functions in the project:

import understand

# Open Database
db = understand.open("test.und")

for func in db.ents("Function"):
    # print qualified name (ex: Namespace::ClassName::methodName)
    print(func.longname())

files() → list[understand.Ent]¶

Return the list of file entities in the database.

Returns:: a list of entities
Return type:: list[understand.Ent]

language() → tuple[str]¶

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 an 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 understand
import re

db = understand.open("test.und")

# Create a regular expression that is case insensitive
searchstr = re.compile(r"test.*\.cpp", re.I)
for file in db.lookup(searchstr, "File"):
    print(file)

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='auto') → dict[str | understand.Metric, metric value]¶

metric(metric, format='auto') → metric value

Return the metric value for each item in metriclist

Parameters:

metriclist (list[str] or tuple[str] or list[understand.Metric] or tuple[understand.Metric]) – a list or tuple of metric ids
metric (str or understand.Metric) – a metric id
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 | understand.Metric, metric value] for metriclist or metric value for metric

When metriclist is used, the result is a dict keyed by the exact metric ids or Metric objects that were provided. When a single metric id/object is used, the result is a single value.

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

Raises:: understand.UnderstandError – if the database is not open

metrics() → list[str]¶

Return a list of project level metric names.

Note:: Prefer understand.Metric.list(target) for new code. It returns Metric objects with metadata and follows the same list(target) pattern as Graph/Report/AutomaticArch APIs.
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) → 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 database is not open

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

report(name, filename, options=None, pages=None, format='') → None¶

Generate a report for the database.

Parameters:

name (str or understand.Report) – the report to generate (same name as in the GUI), or a catalog object from Report.list
filename (str) – output directory or output file name (pdf only)
options (str or understand.Options or None) – optional, report options
pages (list[str] or tuple[str] or None) – optional, report page ids to output. None or empty means all pages.
format (str or None) – optional, comma separated output format(s) for directory output

Return type:

None

Raises:

understand.UnderstandError – if an error occurs

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

Db¶

Understand Python API

Navigation

Related Topics