Arch

class understand.Arch

Bases: object

An Understand architecture

An architecture groups entities into a 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

automatic_arch	Return the AutomaticArch and Options used to generate this architecture, if any.
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 graph output
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
name	Return the short name of the architecture.
parent	Return the parent of the arch or None if it is a root.
report	Generate a report for the architecture.

Methods Documentation

automatic_arch() → tuple[understand.AutomaticArch, understand.Options] | None

Return the AutomaticArch and Options used to generate this architecture, if any.

Return type:

tuple[understand.AutomaticArch, understand.Options] or None

children() → list[understand.Arch]

Return the children of the architecture.

Return type:

list[understand.Arch]

Returns:

the child architectures

contains(ent, recursive=False) → bool

Return true if the entity is contained in the architecture.

Parameters:

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

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

depends(recursive=True, group=False) → 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=True, group=False) → 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=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

View More.

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

metric(metric, format='auto') → 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.

metrics() → list[str]

Return a list of metric names defined for the architecture.

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

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

Generate a report for the architecture.

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

View More.