Software Implementation

Implementation for mlx.traceability

TraceableItem

Storage classes for traceable item

class mlx.traceability.traceable_item.TraceableItem(item_id, placeholder=False, **kwargs)[source]

Bases: TraceableBaseClass

Storage for a traceable documentation item

add_attribute(attr, value, overwrite=True)[source]

Adds an attribute key-value pair to the traceable item.

Note

The given attribute value is compared against defined attribute possibilities. An exception is thrown when the attribute value doesn’t match the defined regex.

Parameters:

  • attr (str) – Name of the attribute.

  • value (str) – Value of the attribute.

  • overwrite (bool) – Overwrite existing attribute value, if any.

add_target(relation, target, implicit=False)[source]

Adds a relation to another traceable item.

Note: using this API, the automatic reverse relation is not created. Adding the relation through the TraceableItemCollection class performs the adding of automatic reverse relations.

Parameters:

  • relation (str) – Name of the relation.

  • target (str) – Item identification of the targeted traceable item.

  • implicit (bool) – If True, an explicitly expressed relation is added here. If false, an implicite (e.g. automatic reverse) relation is added here.

property all_relations

Yields a relationship and the corresponding targets, both naturally sorted.

Type:

generator

attributes_match(attributes)[source]

Checks if item matches a given set of attributes.

Parameters:

attributes (dict) – Dictionary with attribute-regex pairs to match the given item against.

Returns:

True if the given attributes match the item attributes.

Return type:

bool

static define_attribute(attr)[source]

Defines an attribute that can be assigned to traceable items.

Parameters:

attr (TraceableAttribute) – Attribute to be assigned.

get_attribute(attr)[source]

Gets the value of an attribute from the traceable item.

Parameters:

attr (str) – Name of the attribute.

Returns:

Value matching the given attribute key, or ‘’ if attribute does not exist.

Return type:

str

get_attributes(attrs)[source]

Gets the values of a list of attributes from the traceable item.

Parameters:

attr (list) – List of names of the attribute

Returns:

List of values of the given attributes, ‘’ is used as value for each attribute that does not exist

Return type:

list

has_relations(relations)[source]

Checks if the item has every relationship in given list.

Parameters:

relations (list) – List of relations.

Returns:

True if the item has every relationship in given list of list is empty, False otherwise.

Return type:

bool

is_linked(relationships, target_regex)[source]

Checks if item is linked with any of the forwards relationships to a target matching the regex pattern

Parameters:

  • relationships (iterable) – Forward relationships (str)

  • target_regex (str/re.Pattern) – Regular expression pattern or object

Returns:

True if linked; False otherwise

Return type:

bool

is_match(regex)[source]

Checks if the item matches a given regular expression.

Parameters:

regex (str/re.Pattern) – Regular expression pattern or object to match the given item against.

Returns:

True if the given regex matches the item identification.

Return type:

bool

property is_placeholder

True if this item is a placeholder; False otherwise

Type:

bool

Checks if a given item is related using a list of relationships.

Parameters:

  • relations (list) – List of relations.

  • target_id (str) – Identifier of the target item.

Returns:

True if given item is related through the given relationships, False otherwise.

Return type:

bool

iter_attributes()[source]

Iterates over available attributes.

Sorted as configured by an attribute-sort directive, with the remaining attributes naturally sorted.

Returns:

Sorted list containing available attributes in the item.

Return type:

list

iter_relations(sort=True)[source]

Iterates over available relations: naturally sorted by default.

Parameters:

sort (bool) – True if the relations should be sorted naturally, False if no sorting is needed

Returns:

List containing available relations in the item, naturally sorted by default

Return type:

list

iter_targets(relation, explicit=True, implicit=True, sort=True)[source]

Gets a list of targets to other traceable item(s), naturally sorted by default.

Parameters:

  • relation (str) – Name of the relation.

  • explicit (bool) – If True, explicitly expressed relations are included in the returned list.

  • implicit (bool) – If True, implicitly expressed relations are included in the returned list.

  • sort (bool) – True if the relations should be sorted naturally, False if no sorting is needed

Returns:

List of targets to other traceable item(s), naturally sorted by default

Return type:

list

remove_attribute(attr)[source]

Removes an attribute key-value pair from the traceable item.

Parameters:

attr (str) – Name of the attribute.

remove_targets(target_id, explicit=False, implicit=True, relations={})[source]

Removes any relation to given target item.

Parameters:

  • target_id (str) – Identification of the target items to remove.

  • explicit (bool) – If True, explicitly expressed relations to given target are removed.

  • implicit (bool) – If True, implicitly expressed relations to given target are removed.

  • relations (set) – Set of relations to remove; empty to take all into account.

self_test()[source]

Performs self-test on collection content.

Raises:
to_dict()[source]

Exports item to a dictionary.

Returns:

Dictionary representation of the object.

Return type:

dict

update(other)[source]

Updates item with other object. Stores the sum of both objects.

Parameters:

other (TraceableItem) – Other TraceableItem which is the source for the update.

yield_targets(relation, explicit=True, implicit=True)[source]

Gets an iterable of targets to other traceable items.

Parameters:

  • relation (str) – Name of the relation.

  • explicit (bool) – If True, explicitly expressed relations are included.

  • implicit (bool) – If True, implicitly expressed relations are included.

Returns:

Targets to other traceable items, unsorted

Return type:

generator

yield_targets_sorted(*args, **kwargs)[source]

Gets an iterable of targets to other traceable items, with natural sorting applied.

TraceableCollection

Storage classes for collection of traceable items

class mlx.traceability.traceable_collection.TraceableCollection[source]

Bases: object

Storage for a collection of TraceableItems

add_attribute_sorting_rule(filter_regex, attributes)[source]

Configures how the attributes of matching items should be sorted.

The attributes that are missing from the given list will be sorted alphabetically underneath. The items that already have their attributes sorted will be returned as a list; used to report a warning.

Parameters:

  • filter_regex (str) – Regular expression used to match items to apply the attribute sorting to.

  • attributes (list) – List of attributes (str) in the order they should be sorted on.

Returns:

Items that already have the order of their attributes configured.

Return type:

list

add_intermediate_node(node)[source]

Adds an intermediate node

add_item(item)[source]

Add a TraceableItem to the list

Parameters:

item (TraceableItem) – Traceable item to add

add_relation(source_id, relation, target_id)[source]

Add relation between two items

The function adds the forward and the automatic reverse relation.

Parameters:

  • source_id (str) – ID of the source item

  • relation (str) – Relation between source and target item

  • target_id (str) – ID of the target item

add_relation_pair(forward, reverse='')[source]

Add a relation pair to the collection

Parameters:

  • forward (str) – Keyword for the forward relation

  • reverse (str) – Keyword for the reverse relation, or NO_RELATION_STR for external relations

Check if 2 items are related using a list of relationships

Placeholders are excluded

Parameters:

  • source_id (str) – id of the source item

  • relations (list) – list of relations, empty list for wildcard

  • target_id (str) – id of the target item

Returns:

True if both items are related through the given relationships, false otherwise

Return type:

bool

export(fname)[source]

Exports collection content. The target location of the json file gets created if it doesn’t exist yet.

Parameters:

fname (str) – Path to the json file to export

get_external_targets(regex, relation)[source]

Get all external targets for a given external relation with the IDs of their linked internal items

Parameters:

  • regex (str/re.Pattern) – Regex pattern or object to match the external target

  • relation (str) – External relation

Returns:

Dictionary mapping external targets to the IDs of their linked internal items

Return type:

dict

get_item(itemid)[source]

Get a TraceableItem from the list

Parameters:

itemid (str) – Identification of traceable item to get

Returns:

Object for traceable item; None if the item was not found

Return type:

TraceableItem/None

get_item_objects(regex, attributes=None)[source]

Get all items that match a given regular expression as TraceableItem instances.

Placeholders are excluded.

Parameters:

  • regex (str) – Regex to match the items in this collection against

  • attributes (dict) – Dictionary with attribute-regex pairs to match the items in this collection against

Returns:

An iterable of items matching the given regex.

Return type:

generator

get_items(regex, attributes=None, sortattributes=None, reverse=False, sort=True)[source]

Get all items that match a given regular expression

Placeholders are excluded

Parameters:

  • regex (str/re.Pattern) – Regex pattern or object to match the items in this collection against

  • attributes (dict) – Dictionary with attribute-regex pairs to match the items in this collection against

  • sortattributes (list) – List of attributes on which to sort the items alphabetically, or using a custom sort order if at least one attribute is in attributes_sort

  • reverse (bool) – True for reverse sorting

  • sort (bool) – When sortattributes is falsy: True to enable natural sorting, False to disable sorting

Returns:

A sorted list of item-id’s matching the given regex. Sorting is done naturally when sortattributes is unused.

Return type:

list

get_reverse_relation(forward)[source]

Get the matching reverse relation

Parameters:

forward (str) – Keyword for the forward relation

Returns:

Keyword for the matching reverse relation, or None

Return type:

str

has_item(itemid)[source]

Verify if a item with given id is in the collection

Parameters:

itemid (str) – Identification of item to look for

Returns:

True if the given itemid is in the collection, false otherwise

Return type:

bool

iter_items()[source]

Iterate over items: naturally sorted identification

Returns:

Sorted iterator over identification of the items in the collection

iter_relations()[source]

Iterate over available relations: naturally sorted

Returns:

Naturally sorted list over available relations in the collection

process_intermediate_nodes()[source]

Processes all intermediate nodes in order by calling its apply_effect

self_test(notification_item_id, docname=None)[source]

Perform self test on collection content

Parameters:

  • notification_item_id (str/None) – ID of the configured notification item, None if not configured.

  • docname (str) – Document on which to run the self test, None for all.

TraceabilityException

Exception classes for traceability

exception mlx.traceability.traceability_exception.MultipleTraceabilityExceptions(errors)[source]

Bases: Exception

Multiple exceptions for traceability plugin

exception mlx.traceability.traceability_exception.TraceabilityException(message, docname='')[source]

Bases: Exception

Exception for traceability plugin

mlx.traceability.traceability_exception.report_warning(msg, docname=None, lineno=None)[source]

Convenience function for logging a warning

Parameters:

  • msg (any __str__) – Message of the warning, gets converted to str.

  • docname (str) – Relative path to the document on which the error occurred, without extension.

  • lineno (int) – Line number in the document on which the error occurred.

Design coverage

Trace implementation to design

Statistics: 1 out of 3 covered: 33%

Implementation

Design

IMPL-TRACEABILITY_EXCEPTION

IMPL-TRACEABLE_COLLECTION

IMPL-TRACEABLE_ITEM

DESIGN-ITEMIZEAllow splitting the documentation in parts