capella_rm_bridge.changeset package#

Submodules#

capella_rm_bridge.changeset.actiontypes module#

class capella_rm_bridge.changeset.actiontypes.AttributeDefinition#

Bases: dict

An attribute definition from the snapshot.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

long_name: str#

type: str#

class capella_rm_bridge.changeset.actiontypes.Config#

Bases: dict

A configuration of an RM synchronization plan.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

modules: Sequence[TrackerConfig]#

trackers: Sequence[TrackerConfig]#

class capella_rm_bridge.changeset.actiontypes.DataType#

Bases: dict

A data_type from the snapshot.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

long_name: str#

class capella_rm_bridge.changeset.actiontypes.DataTypeValue#

Bases: dict

An enum value/option from the snapshot.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

id: str#

long_name: str#

class capella_rm_bridge.changeset.actiontypes.EnumAttributeDefinition#

Bases: dict

An attribute definition with type == enum from the snapshot.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

long_name: str#

multi_values: bool#

type: str#

exception capella_rm_bridge.changeset.actiontypes.InvalidAttributeDefinition#

Bases: Exception

Raised if an AttributeDefinition’s data-type isn’t found.

exception capella_rm_bridge.changeset.actiontypes.InvalidFieldValue#

Bases: Exception

Raised if a value isn’t matching the defined type or options.

exception capella_rm_bridge.changeset.actiontypes.InvalidSnapshotModule#

Bases: Exception

Raised if the module snapshot is invalid.

exception capella_rm_bridge.changeset.actiontypes.InvalidTrackerConfig#

Bases: Exception

Raised when the given config is missing a non-optional key.

exception capella_rm_bridge.changeset.actiontypes.InvalidWorkItem#

Bases: Exception

Raised if the work item is faulty, e.g. missing a work-item-type.

exception capella_rm_bridge.changeset.actiontypes.InvalidWorkItemType#

Bases: Exception

Raised if the type isn’t matching any of the defined types.

class capella_rm_bridge.changeset.actiontypes.MetaData#

Bases: dict

Metadata of a snapshot.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

connector: str#

revision: str#

tool: str#

capella_rm_bridge.changeset.actiontypes.Primitive#

Type alias for primitive values.

alias of Union[int, float, str, UUIDReference, Promise, list[str | UUIDReference | Promise], bool, datetime]

class capella_rm_bridge.changeset.actiontypes.RequirementType#

Bases: TypedDict

A requirement type from the snapshot.

attributes: Mapping[str, AttributeDefinition | EnumAttributeDefinition]#

long_name: str#

class capella_rm_bridge.changeset.actiontypes.Snapshot#

Bases: dict

A whole snapshot from the RM tool that may have multiple modules.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

metadata: MetaData#

modules: Sequence[TrackerSnapshot]#

class capella_rm_bridge.changeset.actiontypes.TrackerConfig#

Bases: dict

A configuration of an RM module.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

id: str#

class capella_rm_bridge.changeset.actiontypes.TrackerSnapshot#

Bases: dict

A snapshot of a whole module from the RM tool.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

data_types: Mapping[str, Sequence[str]]#

id: int#

requirement_types: Mapping[str, Sequence[Mapping[str, str]]]#

version: int | float#

class capella_rm_bridge.changeset.actiontypes.WorkItem#

Bases: dict

A workitem from the snapshot.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

attributes: Mapping[str, Any]#

children: Sequence[WorkItem]#

id: Required[str]#

long_name: str#

text: str#

type: str#

class capella_rm_bridge.changeset.actiontypes.WorkitemTypeConfig#

Bases: dict

A configeration for workitem types.

static __new__(cls, _typename, _fields=None, /, **kwargs)#

fields: NotRequired[Sequence[str]]#

name: str#

capella_rm_bridge.changeset.change module#

Functionality for calulcating a ChangeSet.

exception capella_rm_bridge.changeset.change.MissingCapellaModule#

Bases: Exception

A CapellaModule with matching UUID could not be found.

class capella_rm_bridge.changeset.change.TrackerChange#

Bases: object

Unites the calculators for finding actions to sync requirements.

__init__(tracker, model, config, gather_logs=True)#

Construct a TrackerChange.

Parameters:

tracker (Mapping[str, Any]) – Is a mapping that has id, data_types, requirement_types and items defined. Maybe called module in different RM tools.
model (MelodyModel) – An instance of MelodyModel for comparison with the snapshot.
config (TrackerConfig) – A configuration for the module (tracker).
gather_logs (bool) –

Raises:

InvalidTrackerConfig – If the given config is missing any of the mandatory keys (uuid, project and/or title).
MissingCapellaModule – If the model is missing a CapellaModule from the UUID declared in the config.
InvalidWorkItemType – May be raised during TrackerChange.calculate_change() if an unknown ID of a RequirementType is used (i.e. the integrity of the requirement_types section in the snapshot is broken).
InvalidFieldValue – May be raised during TrackerChange.calculate_change() if it is tried to set an unavailable field value (i.e. the integrity of the attributes of a work item is broken).

Return type:

None

actions: list[dict[str, Any]]#: List of action requests for the tracker sync.

attribute_definition_create_action(id, item, req_type_id)#

Return an action for creating AttributeDefinitions.

In case of an AttributeDefinitionEnumeration requires id of possibly promised EnumerationDataTypeDefinition.

Parameters:

id (str) –
item (AttributeDefinition | EnumAttributeDefinition) –
req_type_id (str) –

Return type:

dict[str, Any]

attribute_definition_mod_action(reqtype, identifier, data)#

Return an action for an AttributeDefinition.

If a capellambse.extensions.reqif.AttributeDefinition or capellambse.extensions.reqif.AttributeDefinitionEnumeration can be found via its identifier, it is compared against the snapshot. If any changes are identified an action for modification is returned else None. If the definition can’t be found an action for creation is returned.

Returns:

Either a create-, mod-action or None if nothing changed.

Return type:

action

Parameters:

reqtype (RequirementType) –
identifier (str) –
data (AttributeDefinition | EnumAttributeDefinition) –

attribute_value_create_action(id, value, req_type_id)#

Return an action for creating an AttributeValue.

Requires id of possibly promised AttributeDefinition/AttributeDefinitionEnumeration and checks given value to be of the correct types.

See also

capellambse.extension.reqif.IntegerValueAttribute, capellambse.extension.reqif.StringValueAttribute, capellambse.extension.reqif.RealValueAttribute, capellambse.extension.reqif.DateValueAttribute, capellambse.extension.reqif.BooleanValueAttribute, capellambse.extension.reqif.EnumerationValueAttribute

Parameters:

id (str) –
value (int | float | str | UUIDReference | Promise | list[str | capellambse.decl.UUIDReference | capellambse.decl.Promise] | bool | datetime | RMIdentifier) –
req_type_id (RMIdentifier) –

Return type:

dict[str, Any]

attribute_value_mod_action(req, id, valueid, req_type_id)#

Return an action for modifying an AttributeValue.

If an AttributeValue can be found via definition.identifier it is compared against the snapshot. If any changes to its value/s are identified a tuple of the name and value is returned else None. If the attribute can’t be found an action for creation is returned.

Parameters:

req (CapellaModule | Requirement | Folder) – The ReqIFElement under which the attribute value modification takes place.
id (str) – The identifier of the definition for the attribute value.
valueid (str | list[str | capellambse.decl.UUIDReference | capellambse.decl.Promise]) – The value identifier from the snapshot that is compared against the value on the found attribute if it exists. Else a new AttributeValue with this value is created.
req_type_id (optional) – The identifier of RequirementType for given req if it was changed. If not given or None the identifier req.type.identifier is taken.

Returns:

Either a create-action, the value to modify or None if nothing changed.

Return type:

action

calculate_change()#

Render actions for CapellaModule synchronization.

Handles synchronization of RequirementTypesFolder first and Requirements and Folders afterwards. If no RequirementTypesFolder was found an action for creation will be added to the actions. Work items are searched by the identifier. Location changes of work items will invalidate deletions.

Return type:: None

check_attribute_value_is_valid(id, value, req_type_id)#

Perform various integrity checks on the given attribute value.

Raises:

capella_rm_bridge.changeset.actiontypes.InvalidFieldValue – If the types are not matching, if the used data_type definition is missing in the snapshot or the used options on an EnumerationAttributeValue are missing in the snapshot.

Returns:

A data-class that gathers all needed data for creating the (Enumeration)AttributeValue.

Return type:

builder

Parameters:

id (str) –
value (int | float | str | UUIDReference | Promise | list[str | capellambse.decl.UUIDReference | capellambse.decl.Promise] | bool | datetime) –
req_type_id (RMIdentifier) –

check_requirements_module()#

Return the starting action for the CapellaModule.

Check if a CapellaModule can be found and that the config is valid.

Return type:: dict[str, Any]

config: TrackerConfig#: Config section for the tracker.

data_type_create_action(data_type_id, data_type_definition)#

Return an action for creating an EnumDataTypeDefinition.

See also

capellambse.extensions.reqif.EnumerationDataTypeDefinition: Definition for the data_type attribute of AttributeDefinitionEnumerations.

Parameters:

data_type_id (str) –
data_type_definition (DataType) –

Return type:

dict[str, Any]

data_type_definition_mod_actions()#

Populate with ModActions for the RequirementTypesFolder.

The data type definitions and requirement type are checked via make_datatype_definition_mod_action() and make_reqtype_mod_action() respectively. If there are changes the actions container will be populated.

Return type:: dict[str, Any]

data_type_definitions: Mapping[str, DataType]#: A lookup for DataTypeDefinitions from the tracker snapshot.

data_type_mod_action(id, ddef)#

Return an Action for creating or modifying a DataTypeDefinition.

If a reqif.DataTypeDefinition can be found via id and it differs against the snapshot an action for modification is returned. If it doesn’t differ the returned action is None. If the definition can’t be found an action for creating an EnumerationDataTypeDefinition` is returned.

Returns:

Either an create- or mod-action or None if nothing changed.

Return type:

action

Parameters:

id (str) –
ddef (DataType) –

errors: list[str]#

gather_logs: bool#: Collect error messages in errors instead of immediate logging.

invalidate_deletion(requirement)#

Try to remove requirement from deletions.

Remove empty dictionaries or even whole action if its only delete action was removed.

Parameters:: requirement (Requirement | Folder) –
Return type:: None

model: MelodyModel#: Model instance.

req_delete_actions(visited, attr_name='requirements')#

Return an action for deleting elements under the ReqModule.

Filter all elements from the CapellaModule attribute with name attr_name against visited. These are the elements that are still in the model but not in the snapshot, and have to be deleted.

Parameters:

visited (Iterable[str]) –
attr_name (str) –

Return type:

dict[str, Any]

req_module: CapellaModule#: The corresponding reqif.CapellaModule for the tracker.

reqt_folder: CapellaTypesFolder | None#: The reqif.CapellaTypesFolder storing fields data.

reqtype_fields_filter: Mapping[RMIdentifier, set[str]]#: A mapping for whitelisted fieldnames per RequirementType.

requirement_type_create_action(identifier, req_type)#

Return an action for creating the RequirementType.

See also

capellambse.extensions.reqif.RequirementType: The type attribute of Requirements and RequirementsFolder that enables AttributeDefinitions via the definition attribute.

Parameters:

identifier (RMIdentifier) –
req_type (RequirementType) –

Return type:

dict[str, Any]

requirement_type_delete_actions()#

Populate actions for deleting RequirementTypes.

Return type:: list[capellambse.decl.UUIDReference]

requirement_type_mod_action(identifier, item)#

Parameters:

identifier (RMIdentifier) –
item (RequirementType) –

Return type:

None | dict[str, Any]

requirement_types: Mapping[RMIdentifier, RequirementType]#: A lookup for RequirementTypes from the tracker snapshot.

requirement_types_folder_create_action(base)#

Return an action for creating the CapellaTypesFolder.

See also

capellambse.extensions.reqif.CapellaTypesFolder: Folder for (Data-)Type- and Attribute-Definitions

Parameters:: base (dict[str, Any]) –
Return type:: dict[str, Any]

tracker: Mapping[str, Any]#: Snapshot of tracker, i.e. a reqif.CapellaModule.

yield_data_type_definition_create_actions()#

Yield actions for creating EnumDataTypeDefinitions.

Return type:: Iterator[dict[str, Any]]

yield_requirement_type_create_actions()#

Yield actions for creating RequirementTypes.

Return type:: Iterator[dict[str, Any]]

yield_requirements_create_actions(item)#

Yield actions for creating Requirements or Folders.

The WorkItem is identified as a RequirementsFolder if there are non-empty children or a (Type, "Folder") pair in the attributes exists. Also yields creations or modifications for children.

See also

capellambse.extensions.reqif.Requirement, capellambse.extensions.reqif.RequirementsFolder

Parameters:: item (WorkItem) –
Return type:: Iterator[dict[str, Any]]

yield_requirements_mod_actions(req, item, parent=None)#

Yield an action for modifying given req.

If any modifications to simple attributes (e.g. long_name), attributes or creations/deletions of children (in case of req being a Folder) were identified an action for modification of req is yielded. For modifications of children the method is called recursively and yields actions from it.

Parameters:

req (CapellaModule | Requirement | Folder) –
item (dict[str, Any] | WorkItem) –
parent (CapellaModule | Requirement | Folder | Promise | None) –

Return type:

Iterator[dict[str, Any]]

capella_rm_bridge.changeset.change.make_requirement_delete_actions(req, child_ids, key='requirements')#

Return actions for deleting elements behind req.key.

The returned list is filtered against the identifier from given child_ids.

Parameters:

req (Folder) –
child_ids (Container[RMIdentifier]) –
key (str) –

Return type:

list[capellambse.decl.UUIDReference]

capella_rm_bridge.changeset.find module#

Functionality for finding ReqIF elements in a MelodyModel.

capella_rm_bridge.changeset.find.find_by(model, value, *xtypes, attr='identifier', below=None)#

Parameters:

model (MelodyModel) –
value (Any) –
xtypes (str) –
attr (str) –
below (GenericElement | None) –

Return type:

ReqIFElement | None

capella_rm_bridge.changeset.find.find_by_identifier(model, id, *xtypes, **kw)#

Try to return a model object by its identifier.

Parameters:

model (MelodyModel) –
id (str) –
xtypes (str) –

Return type:

ReqIFElement | None

Module contents#

A ChangeSet is a sequence of actions to be applied to a model.

The calculate_change_set() function calculates these actions from a given snapshot of supported Requirement Management tools and config YAML file. With the declarative modelling feature of capellambse a MelodyModel can be altered with capellambse.decl.apply().

capella_rm_bridge.changeset.calculate_change_set(model, config, snapshot, force=False, safe_mode=True, gather_logs=True)#

Return a list of actions for a given model and snapshot.

The returned list (ChangeSet) stores the needed actions to synchronize the model with the content of the snapshot. The snapshot stores a tracker or live-document which correspond to a reqif.CapellaModule.

Parameters:

model (MelodyModel) – The Capella model to compare the snapshot against.
config (TrackerConfig) – A configuration of the tracker or live-document for the calculated ChangeSet.
snapshot (TrackerSnapshot) – A snapshot of a tracker or live-document from the external tool.
force (bool) – If True a ChangeSet will be rendered even if an error occurred during the change-calculation loop. All related objects will be skipped.
safe_mode (bool) – If True no ChangeSet will be rendered iff atleast one error occurred during the change-calculation loop. If False all change-actions of modules where errors occurred are dismissed.
gather_logs (bool) – If True all error messages are gathered in TrackerChange.errors instead of being immediately logged.

Return type:

ChangeSet, errors

See also

capella_rm_bridge.changeset.actiontypes.TrackerConfig: The expected keys and value types of a module.
capella_rm_bridge.changeset.actiontypes.TrackerSnapshot: The expected keys and value types of a snapshot.