refactor: add specific model for bitstream information (DEV-2893) (#613)

Co-authored-by: Johannes Nussbaum <39048939+jnussbaum@users.noreply.github.com>

src/dsp_tools/models/xmlresource.py

@@ -1,3 +1,4 @@
+from dataclasses import dataclass
 from typing import Optional, Union
 
 import regex
@@ -11,6 +12,20 @@
 from dsp_tools.models.xmlproperty import XMLProperty
 
 
+@dataclass(frozen=True)
+class BitstreamInfo:
+    """
+    Represents a bitstream object,
+    consisting of its file name on the local file system,
+    the internal file name assigned by SIPI
+    and optionally its permissions.
+    """
+
+    local_file: str
+    internal_file_name: str
+    permissions: Permissions | None = None
+
+
 class XMLResource:  # pylint: disable=too-many-instance-attributes
     """
     Represents a resource in the XML used for data import.
@@ -174,24 +189,29 @@ def get_propvals(
         return prop_data
 
     def get_bitstream_information(
-        self, internal_file_name_bitstream: str, permissions_lookup: dict[str, Permissions]
-    ) -> Optional[dict[str, Union[str, Permissions]]]:
+        self,
+        internal_file_name_bitstream: str,
+        permissions_lookup: dict[str, Permissions],
+    ) -> BitstreamInfo | None:
         """
-        Get the bitstream object belonging to the resource
+        This method constructs a `BitstreamInfo` object from the current resource,
+        or None, if the resource does not have a bitstream representation.
+        The `BitstreamInfo` object contains the local file name (relative to the imgdir directory),
+        the internal file name assigned by SIPI
+        and the permissions of the bitstream representation, if permissions are defined.
 
         Args:
             internal_file_name_bitstream: Internal file name of bitstream object as returned from Sipi
             permissions_lookup: Is used to resolve the permission id's to permission sets
 
         Returns:
-            A dict of the bitstream object
+            A BitstreamInfo object
         """
-        tmp: Optional[dict[str, Union[str, Permissions]]] = None
-        if self.bitstream:
-            bitstream = self.bitstream
-            tmp = {"value": bitstream.value, "internal_file_name": internal_file_name_bitstream}
-            if bitstream.permissions:
-                permissions = permissions_lookup.get(bitstream.permissions)
-                if permissions:
-                    tmp["permissions"] = permissions
-        return tmp
+        if not self.bitstream:
+            return None
+        permissions = permissions_lookup.get(self.bitstream.permissions) if self.bitstream.permissions else None
+        return BitstreamInfo(
+            local_file=self.bitstream.value,
+            internal_file_name=internal_file_name_bitstream,
+            permissions=permissions,
+        )

src/dsp_tools/utils/xmlupload/resource_multimedia.py

@@ -7,7 +7,7 @@
 from dsp_tools.models.permission import Permissions
 from dsp_tools.models.sipi import Sipi
 from dsp_tools.models.xmlbitstream import XMLBitstream
-from dsp_tools.models.xmlresource import XMLResource
+from dsp_tools.models.xmlresource import BitstreamInfo, XMLResource
 from dsp_tools.utils.create_logger import get_logger
 from dsp_tools.utils.shared import try_network_action
 
@@ -19,7 +19,7 @@ def _upload_bitstream(
     sipi_server: Sipi,
     imgdir: str,
     permissions_lookup: dict[str, Permissions],
-) -> dict[str, str | Permissions] | None:
+) -> BitstreamInfo | None:
     """
     This function uploads a specified bitstream file to SIPI and then returns the file information from SIPI.
 
@@ -52,7 +52,7 @@ def handle_bitstream(
     permissions_lookup: dict[str, Permissions],
     sipi_server: Sipi,
     imgdir: str,
-) -> dict[str, Any] | None:
+) -> BitstreamInfo | None:
     """
     Upload a bitstream file to SIPI
 

src/dsp_tools/utils/xmlupload/xmlupload.py

@@ -17,7 +17,7 @@
 from dsp_tools.models.resource import KnoraStandoffXmlEncoder, ResourceInstance, ResourceInstanceFactory
 from dsp_tools.models.sipi import Sipi
 from dsp_tools.models.xmlpermission import XmlPermission
-from dsp_tools.models.xmlresource import XMLResource
+from dsp_tools.models.xmlresource import BitstreamInfo, XMLResource
 from dsp_tools.utils.create_logger import get_logger
 from dsp_tools.utils.shared import login, try_network_action
 from dsp_tools.utils.xmlupload.ark2iri import convert_ark_v0_to_resource_iri
@@ -400,20 +400,29 @@ def _create_resource(
     res_type: type,
     resource: XMLResource,
     resource_iri: str | None,
-    bitstream_information: dict[str, Any] | None,
+    bitstream_information: BitstreamInfo | None,
     con: Connection,
     permissions_lookup: dict[str, Permissions],
     id2iri_mapping: dict[str, str],
 ) -> tuple[str, str] | None:
     properties = resource.get_propvals(id2iri_mapping, permissions_lookup)
     try:
+        if bitstream_information:
+            bitstream_info: dict[str, str | Permissions] | None = {
+                "value": bitstream_information.local_file,
+                "internal_file_name": bitstream_information.internal_file_name,
+            }
+            if bitstream_information.permissions and bitstream_info:
+                bitstream_info["permissions"] = bitstream_information.permissions
+        else:
+            bitstream_info = None
         resource_instance: ResourceInstance = res_type(
             con=con,
             label=resource.label,
             iri=resource_iri,
             permissions=permissions_lookup.get(str(resource.permissions)),
             creation_date=resource.creation_date,
-            bitstream=bitstream_information,
+            bitstream=bitstream_info,
             values=properties,
         )
         created_resource: ResourceInstance = try_network_action(resource_instance.create)