Arch

class understand.Arch

Bases: object

An Understand architecture

An architecture groups entities into tree-like structure. There are built-in architectures such as the “Directory Structure” architecture. The “Directory Structure” architecture groups file entities by path. Custom architectures can also be created. An architecture can contain entities and/or child architectures. These are retrieved with ents and children respectively. Dependencies, metrics, and graphs are available at an architecture level.

Methods Summary

children	Return the children of the architecture.
contains	Return true if the entity is contained in the architecture.
depends	Return the dependencies of the architecture
dependsby	Return the architectures depended on by this architecture.
draw	Generate a graphics file for the architecture
ents	Return the entities within the architecture.
longname	Return the long name of the architecture.
metric	Return the metric value for each item in metriclist
metrics	Return a list of metric names defined for the architecture.
name	Return the short name of the architecture.
parent	Return the parent of the arch or None if it is a root.

Methods Documentation

children() → list[understand.Arch]

Return the children of the architecture.

Return type:

list[understand.Arch]

Returns:

the child architectures

contains(entity[, recursive]) → bool

Return true if the entity is contained in the architecture.

Parameters:

• entity (understand.Ent) – the entity to search for

• recursive (bool or None) – optional, if True search children architectures as well. False by default.

depends([recursive [,group]]) -> dict(understand.Arch, list[understand.Ref])

Return the dependencies of the architecture

Parameters:

• recursive (bool or None) – optional, if True include child architecture dependencies. True by default.

• group (bool or None) – optional, if True, group the returned keys into as few keys as possible. False by default.

Return type:

dict(understand.Arch,list[understand.Ref])

Returns:

the dependencies as a dictionary

Each architecture this architecture depends on is a key in the dict. The value is a list of references that cause the dependency. For example, given the architecture structure:

• All

  • Bob

    • Lots of entities

  • Sue

    • Current

      • Lots of entities

    • Old

      • Lots of entities

calling sue.depends(recursive=false) would return an empty dictionary since sue’s children (current and old) are not considered. Calling bob.depends(group=true) would result in a single key in the dictionary (Sue), as opposed to two keys (Sue/Current and Sue/Old) since all the entities were grouped together.

dependsby([recursive [,group]]) -> dict(understand.Arch, list[understand.Ref])

Return the architectures depended on by this architecture.

Parameters:

• recursive (bool or None) – optional, if True include child architecture dependencies. True by default.

• group (bool or None) – optional, if True, group the returned keys into as few keys as possible. False by default.

Return type:

dict(understand.Arch,list[understand.Ref])

Returns:

the dependencies to this architecture as a dictionary

See understand.Arch.depends() for an example.

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

Generate a graphics file for the architecture

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 language and entity, but the name will be the same as the name in the Understand GUI. Some examples are:

• “Graph Architecture”

• “Dependencies”

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

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

Return the entities within the architecture.

Parameters:

recursive (bool or None) – optional, if True, child architectures are considered. False by default.

Return type:

list[understand.Ent]

Returns:

the entities within the architecture.

longname() → str

Return the long name of the architecture.

Return type:

str

Returns:

the long name

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

metric(metric[, format]) → 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

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

metrics() → list[str]

Return a list of metric names defined for the architecture.

Return type:

list[str]

Returns:

a list of metric names defined for the architecture.

name() → str

Return the short name of the architecture.

Return type:

str

Returns:

the name of the architecture

parent() → understand.Arch

Return the parent of the arch or None if it is a root.

Return type:

understand.Arch

Returns:

the architecture’s parent or None if this is a root architecture.