feat: added support for the libraries linking and referencing from model

src/capellambse/aird/_common.py

@@ -44,6 +44,14 @@
     "/xmi:XMI/viewpoint:DAnalysis/ownedViews[viewpoint]",
     namespaces=_n.NAMESPACES,
 )
+XP_DANALYSIS = etree.XPath(
+    "/xmi:XMI/viewpoint:DAnalysis",
+    namespaces=_n.NAMESPACES,
+)
+XP_SEMANTIC_RESOURCES = etree.XPath(
+    "/viewpoint:DAnalysis/semanticResources",
+    namespaces=_n.NAMESPACES,
+)
 ELEMENT = builder.ElementMaker(nsmap={"xmi": str(_n.NAMESPACES["xmi"])})
 
 

src/capellambse/extensions/filtering.py

@@ -142,8 +142,10 @@ class IntersectionFilteringResultSet(FilteringResultSet):
 
 
 def init() -> None:
-    capellamodeller.SystemEngineering.filtering_model = m.Single(
-        m.Filter("extensions", (NS, "FilteringModel"))
+    capellamodeller.SystemEngineering.filtering_model = m.Optional(
+        m.Single(
+            m.Filter("extensions", (NS, "FilteringModel"))
+        )
     )
     m.MelodyModel.filtering_model = property(  # type: ignore[attr-defined]
         operator.attrgetter("project.model_root.filtering_model")

src/capellambse/loader/core.py

@@ -32,6 +32,7 @@
 
 import capellambse._namespaces as _n
 from capellambse import filehandler, helpers
+from capellambse.aird._common import XP_SEMANTIC_RESOURCES
 from capellambse.loader import exs
 from capellambse.loader.modelinfo import ModelInfo
 
@@ -590,6 +591,85 @@ def check_duplicate_uuids(self) -> None:
                 " - check the 'resources' for duplicate models"
             )
 
+    def __get_metadata(
+        self, afm: ModelFile
+    ) -> etree._Element:
+        """Return metadata from given model.
+
+        Parameters
+        ----------
+        afm
+            model metadata file
+        return
+            metadata element if found
+
+        Raises
+        ------
+        RuntimeError
+            If metadata could not be found
+        """
+        metadata = next(afm.root.iter(METADATA_TAG), None)
+        if metadata is None:
+            raise RuntimeError("Cannot find <Metadata> in primary .afm file")
+        LOGGER.debug("Found <Metadata> with ID %s", metadata.get("id"))
+        return metadata
+
+    def _link_library(
+        self, lib: pathlib.PurePosixPath
+    ) -> None:
+        """Link library into the project tree, updates .aird, .capella, .afm to correcrly reflect library in target model.
+
+        Parameters
+        ----------
+        lib
+            path to a library .aird file
+
+
+        Description
+        -----------
+        When you need to refere to external library (or reuse one in a project)
+        ```
+        p = "..." #path to library
+        model._loader._link_library(p)
+
+        lib = model.project.extensions[0].reference.library #no longer crashes, all fragments are in place
+
+        ```
+        """
+        handler = self.resources[str(lib)]
+        _h , filename = _derive_entrypoint(handler)
+        frag = ModelFile(
+            filename, handler, ignore_uuid_dups=self.__ignore_uuid_dups
+        )
+
+        p = lib.joinpath(filename)
+        self.trees[p] = frag
+        for ref in _find_refs(frag.root):
+            ref_name = helpers.normalize_pure_path(
+                _unquote_ref(ref), base=p.parent
+            )
+            self.__load_referenced_files(ref_name)
+
+            if ref_name.suffix == ".afm":
+                meta_lib = self.__get_metadata(self.trees[ref_name])
+                meta_self = self.__find_metadata()
+
+                if not next(filter(lambda el: re.search(str(ref_name), el.attrib["href"]), meta_self.iterchildren("additionalResources")), None):
+                    ael = meta_self.makeelement("additionalMetadata", href=f"../{ref_name}#{meta_lib.attrib['id']}")
+                    meta_self.append(ael)
+            elif ref_name.suffix == ".capella":
+                aird_self = self.trees[pathlib.PurePosixPath(f"\x00/{self.entrypoint}")]
+
+                last = next(filter(lambda el: re.search(str(ref_name), el.text), XP_SEMANTIC_RESOURCES(aird_self.root)), None)
+                if not last:
+                    for r in XP_SEMANTIC_RESOURCES(aird_self.root):
+                        last = r
+
+                    if last is not None:
+                        sr = last.makeelement("semanticResources")
+                        sr.text = f"platform:/resource/{ref_name}"
+                        last.addnext(sr)
+
     def __load_referenced_files(
         self, resource_path: pathlib.PurePosixPath
     ) -> None:
@@ -1345,11 +1425,7 @@ def __find_metadata(self) -> etree._Element:
         )
         if afm is None:
             raise RuntimeError("Cannot find .afm file in primary resource")
-        metadata = next(afm.root.iter(METADATA_TAG), None)
-        if metadata is None:
-            raise RuntimeError("Cannot find <Metadata> in primary .afm file")
-        LOGGER.debug("Found <Metadata> with ID %s", metadata.get("id"))
-        return metadata
+        return self.__get_metadata(afm)
 
     def referenced_viewpoints(self) -> cabc.Iterator[tuple[str, str]]:
         metadata = self.__find_metadata()

src/capellambse/metamodel/capellamodeller.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import capellambse.model as m
+from capellambse.metamodel import re
 
 from . import capellacore
 from . import namespaces as ns
@@ -57,6 +58,10 @@ class SystemEngineering(capellacore.AbstractModellingStructure, ModelRoot):
     [source:MIL-STD 499B standard]
     """
 
+    extensions = m._descriptors.Containment[re.ReElementContainer](
+        "ownedExtensions", (ns.RE, "RecCatalog")
+    )
+
     @property
     def oa(self) -> oa.OperationalAnalysis:
         from . import oa  # noqa: PLC0415

src/capellambse/metamodel/re.py

@@ -55,12 +55,16 @@ class GroupingElementPkg(CatalogElementPkg):
 
 
 class CatalogElementLink(ReAbstractElement):
-    source = m.Association["CatalogElement"]((NS, "CatalogElement"), "source")
-    target = m.Association["m.ModelElement"](
-        (ns.MODELLINGCORE, "ModelElement"), "target"
+    source = m.Single(m.Association["CatalogElement"]((NS, "CatalogElement"), "source"))
+    target = m.Single(
+        m.Association["m.ModelElement"](
+            (ns.MODELLINGCORE, "ModelElement"), "target"
+        )
     )
-    origin = m.Association["CatalogElementLink"](
-        (NS, "CatalogElementLink"), "origin"
+    origin = m.Single(
+        m.Association["CatalogElementLink"](
+            (NS, "CatalogElementLink"), "origin"
+        )
     )
     unsynchronized_features = m.StringPOD("unsynchronizedFeatures")
     is_suffixed = m.BoolPOD("suffixed")
@@ -75,12 +79,20 @@ class CatalogElement(ReDescriptionElement, ReElementContainer):
     is_read_only = m.BoolPOD("readOnly")
     version = m.StringPOD("version")
     tags = m.StringPOD("tags")
-    origin = m.Association["CatalogElement"]((NS, "CatalogElement"), "origin")
-    current_compliancy = m.Association["CompliancyDefinition"](
-        (NS, "CompliancyDefinition"), "currentCompliancy"
+    origin = m.Single(
+        m.Association["CatalogElement"](
+            (NS, "CatalogElement"), "origin"
+        )
     )
-    default_replica_compliancy = m.Association["CompliancyDefinition"](
-        (NS, "CompliancyDefinition"), "defaultReplicaCompliancy"
+    current_compliancy = m.Single(
+        m.Association["CompliancyDefinition"](
+            (NS, "CompliancyDefinition"), "currentCompliancy"
+        )
+    )
+    default_replica_compliancy = m.Single(
+        m.Association["CompliancyDefinition"](
+            (NS, "CompliancyDefinition"), "defaultReplicaCompliancy"
+        )
     )
     links = m.Containment["CatalogElementLink"](
         "ownedLinks", (NS, "CatalogElementLink")

src/capellambse/model/_descriptors.py

@@ -22,6 +22,7 @@
     "MissingValueError",
     "NewObject",
     "NonUniqueMemberError",
+    "Optional",
     "ParentAccessor",
     "PhysicalAccessor",
     "PhysicalLinkEndsAccessor",
@@ -363,6 +364,90 @@ def __repr__(self) -> str:
             f" use {self.alternative!r} instead>"
         )
 
+class Optional(Accessor[T_co | "_obj.ElementList[T_co]" | None ], t.Generic[T_co]):
+    """An Accessor wrapper that makes result optional.
+
+    This Accessor is used to wrap other Accessors and make faults optional.
+    It catches wrapped accessor faults, hides them and intentionally
+    returns empty result effectively preventing runtime errors when accessing
+    optional model elements (i.e. extensions)
+
+    Parameters
+    ----------
+    wrapped
+        The accessor to wrap. This accessor must return a list (i.e. it
+        is not possible to nest *Single* descriptors). The instance
+        passed here should also not be used anywhere else.
+
+    optional
+        Marker of optional element, when set - hides the errors
+
+        Defaults to True.
+
+    Examples
+    --------
+    >>> class Foo(capellacore.CapellaElement):
+    ...     bar = Optional["Bar"](Containment("bar", (NS, "Bar")))
+    """
+
+    def __init__(
+        self,
+        wrapped: Accessor[T_co | _obj.ElementList[T_co] | None ],
+        optional: bool = False
+    ) -> None:
+        """Create a new optional descriptor."""
+        self.wrapped: t.Final = wrapped
+        self.optional: t.Final = optional
+
+    @t.overload
+    def __get__(self, obj: None, objtype: type[t.Any]) -> te.Self: ...
+    @t.overload
+    def __get__(
+        self, obj: _obj.ModelObject, objtype: type[t.Any] | None = None
+    ) -> T_co | None: ...
+    def __get__(
+        self, obj: _obj.ModelObject | None, objtype: t.Any | None = None
+    ) -> te.Self | T_co | None:
+        """Retrieve the value of the attribute."""
+        if obj is None:
+            return self
+
+        objs: t.Any = None
+        try:
+            objs = self.wrapped.__get__(obj, type(obj))
+        finally:
+            self.__objs = objs
+            return objs
+
+
+    def __set__(
+        self, obj: _obj.ModelObject, value: _obj.ModelObject | None
+    ) -> None:
+        """Set the value of the attribute."""
+        if self.__objs:
+            self.wrapped.__set__(obj, [value])
+
+    def __delete__(self, obj: _obj.ModelObject) -> None:
+        """Delete the attribute."""
+        if self.objs:
+            self.wrapped.__delete__(obj)
+
+    def __set_name__(self, owner: type[_obj.ModelObject], name: str) -> None:
+        """Set the name and owner of the descriptor."""
+        self.wrapped.__set_name__(owner, name)
+        super().__set_name__(owner, name)
+
+    def __repr__(self) -> str:
+        wrapped = repr(self.wrapped).replace(" " + repr(self._qualname), "")
+        return f"<Optional {self._qualname!r} of {wrapped}>"
+
+    def purge_references(
+        self, obj: _obj.ModelObject, target: _obj.ModelObject
+    ) -> contextlib.AbstractContextManager[None]:
+        if hasattr(self.wrapped, "purge_references"):
+            return self.wrapped.purge_references(obj, target)
+        return contextlib.nullcontext(None)
+
 
 class Single(Accessor[T_co | None], t.Generic[T_co]):
     """An Accessor wrapper that ensures there is exactly one value.