feat: Anticipate IDs usage

capella_rm_bridge/changeset/__init__.py

@@ -74,8 +74,7 @@ def calculate_change_set(
         dismissed.
     gather_logs
         If ``True`` all error messages are gathered in
-        :attribute:`~capella_rm_bridge.changeset.change.TrackerChange.errors`
-        instead of being immediately logged.
+        `TrackerChange.errors` instead of being immediately logged.
 
     Returns
     -------

capella_rm_bridge/changeset/actiontypes.py

@@ -10,9 +10,12 @@
 import typing_extensions as te
 
 Primitive = t.Union[int, float, str, list[str], bool, datetime.datetime]
+"""Type alias for primitive values."""
 
 
 class WorkitemTypeConfig(te.TypedDict):
+    """A configeration for workitem types."""
+
     name: str
     fields: te.NotRequired[cabc.Sequence[str]]
 
@@ -25,9 +28,12 @@ class WorkitemTypeConfig(te.TypedDict):
         "id": str,
     },
 )
+"""A configuration of an RM module."""
 
 
 class Config(te.TypedDict):
+    """A configuration of an RM synchronization plan."""
+
     modules: cabc.Sequence[TrackerConfig]
     trackers: cabc.Sequence[TrackerConfig]
 
@@ -37,6 +43,8 @@ class InvalidTrackerConfig(Exception):
 
 
 class WorkItem(te.TypedDict, total=False):
+    """A workitem from the snapshot."""
+
     id: te.Required[int]
     long_name: str
     text: str
@@ -45,13 +53,31 @@ class WorkItem(te.TypedDict, total=False):
     children: cabc.Sequence[WorkItem]
 
 
+class DataType(te.TypedDict):
+    """A data_type from the snapshot."""
+
+    long_name: str
+    values: list[DataTypeValue]
+
+
+class DataTypeValue(te.TypedDict):
+    """An enum value/option from the snapshot."""
+
+    id: str
+    long_name: str
+
+
 class MetaData(te.TypedDict):
+    """Metadata of a snapshot."""
+
     tool: str
     revision: str
     connector: str
 
 
 class TrackerSnapshot(te.TypedDict):
+    """A snapshot of a whole module from the RM tool."""
+
     id: int
     version: int | float
     data_types: cabc.Mapping[str, cabc.Sequence[str]]
@@ -60,22 +86,31 @@ class TrackerSnapshot(te.TypedDict):
 
 
 class Snapshot(te.TypedDict):
+    """A whole snapshot from the RM tool that may have multiple modules."""
+
     metadata: MetaData
     modules: cabc.Sequence[TrackerSnapshot]
 
 
-class AttributeDefinition(te.TypedDict):
-    type: str
-
-
 class RequirementType(t.TypedDict):
+    """A requirement type from the snapshot."""
+
     long_name: str
     attributes: cabc.Mapping[
         str, t.Union[AttributeDefinition, EnumAttributeDefinition]
     ]
 
 
+class AttributeDefinition(te.TypedDict):
+    """An attribute definition from the snapshot."""
+
+    long_name: str
+    type: str
+
+
 class EnumAttributeDefinition(AttributeDefinition, total=False):
+    """An attribute definition with `type == enum` from the snapshot."""
+
     values: list[str]
     multi_values: bool