dsp-tools 0.9.13__py3-none-any.whl → 18.3.0.post13__py3-none-any.whl

dsp_tools/commands/xmlupload/models/processed/res.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from dsp_tools.commands.xmlupload.models.permission import Permissions
+from dsp_tools.commands.xmlupload.models.processed.file_values import ProcessedFileValue
+from dsp_tools.commands.xmlupload.models.processed.file_values import ProcessedIIIFUri
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedValue
+from dsp_tools.legacy_models.datetimestamp import DateTimeStamp
+
+
+@dataclass
+class ProcessedResource:
+    res_id: str
+    type_iri: str
+    label: str
+    permissions: Permissions | None
+    values: list[ProcessedValue]
+    file_value: ProcessedFileValue | None = None
+    iiif_uri: ProcessedIIIFUri | None = None
+    migration_metadata: MigrationMetadata | None = None
+
+
+@dataclass
+class MigrationMetadata:
+    iri_str: str | None
+    creation_date: DateTimeStamp | None

dsp_tools/commands/xmlupload/models/processed/values.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+from dsp_tools.commands.xmlupload.models.formatted_text_value import FormattedTextValue
+from dsp_tools.commands.xmlupload.models.permission import Permissions
+from dsp_tools.utils.data_formats.date_util import Date
+
+
+@dataclass
+class IntervalFloats:
+    start: float
+    end: float
+
+
+type ProcessedValueTypes = Union[bool, str, float, int, FormattedTextValue, Date, IntervalFloats]
+
+
+@dataclass
+class ProcessedValue:
+    value: ProcessedValueTypes
+    prop_iri: str
+    comment: str | None
+    permissions: Permissions | None
+
+
+@dataclass
+class ProcessedBoolean(ProcessedValue):
+    value: bool
+
+
+@dataclass
+class ProcessedColor(ProcessedValue):
+    value: str
+
+
+@dataclass
+class ProcessedDate(ProcessedValue):
+    value: Date
+
+
+@dataclass
+class ProcessedDecimal(ProcessedValue):
+    value: float
+
+
+@dataclass
+class ProcessedGeoname(ProcessedValue):
+    value: str
+
+
+@dataclass
+class ProcessedGeometry(ProcessedValue):
+    value: str
+
+
+@dataclass
+class ProcessedInt(ProcessedValue):
+    value: int
+
+
+@dataclass
+class ProcessedInterval(ProcessedValue):
+    value: IntervalFloats
+
+
+@dataclass
+class ProcessedLink(ProcessedValue):
+    value: str
+    value_uuid: str
+
+    def __post_init__(self) -> None:
+        self.prop_iri = f"{self.prop_iri}Value"
+
+
+@dataclass
+class ProcessedList(ProcessedValue):
+    value: str
+
+
+@dataclass
+class ProcessedSimpleText(ProcessedValue):
+    value: str
+
+
+@dataclass
+class ProcessedRichtext(ProcessedValue):
+    value: FormattedTextValue
+    resource_references: set[str]
+    value_uuid: str
+
+
+@dataclass
+class ProcessedTime(ProcessedValue):
+    value: str
+
+
+@dataclass
+class ProcessedUri(ProcessedValue):
+    value: str

dsp_tools/commands/xmlupload/models/rdf_models.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rdflib import URIRef
+
+
+@dataclass
+class RDFPropTypeInfo:
+    knora_type: URIRef
+    knora_prop: URIRef
+    xsd_type: URIRef | None = None
+
+
+@dataclass
+class AbstractFileValue:
+    value: str
+    metadata: FileValueMetadata
+
+
+@dataclass
+class FileValueMetadata:
+    license_iri: str
+    copyright_holder: str
+    authorships: list[str]
+    permissions: str | None

dsp_tools/commands/xmlupload/models/upload_clients.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+
+from dsp_tools.clients.legal_info_client import LegalInfoClient
+from dsp_tools.commands.xmlupload.models.ingest import AssetClient
+from dsp_tools.commands.xmlupload.prepare_xml_input.list_client import ListClient
+
+
+@dataclass(frozen=True)
+class UploadClients:
+    """Holds all the clients needed for the upload process."""
+
+    asset_client: AssetClient
+    list_client: ListClient
+    legal_info_client: LegalInfoClient

dsp_tools/commands/xmlupload/models/upload_state.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from dataclasses import field
+
+from dsp_tools.commands.xmlupload.iri_resolver import IriResolver
+from dsp_tools.commands.xmlupload.models.processed.res import ProcessedResource
+from dsp_tools.commands.xmlupload.stash.stash_models import Stash
+from dsp_tools.commands.xmlupload.upload_config import UploadConfig
+
+
+@dataclass
+class UploadState:
+    """
+    Save the state of an xmlupload, so that after an interruption, it can be resumed.
+    """
+
+    pending_resources: list[ProcessedResource]
+    pending_stash: Stash | None
+    config: UploadConfig
+    failed_uploads: list[str] = field(default_factory=list)
+    iri_resolver: IriResolver = field(default_factory=IriResolver)

dsp_tools/commands/xmlupload/prepare_xml_input/ark2iri.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import base64
+import uuid
+
+import regex
+
+from dsp_tools.error.exceptions import BaseError
+
+
+def convert_ark_v0_to_resource_iri(ark: str) -> str:
+    """
+    Converts an ARK URL from salsah.org (ARK version 0) of the form ark:/72163/080c-779b9990a0c3f-6e
+    to a DSP resource IRI of the form http://rdfh.ch/080C/Ef9heHjPWDS7dMR_gGax2Q
+
+    This method is needed for the migration of projects from salsah.org to DSP.
+    Resources need to be created with an existing ARK,
+    so the IRI needs to be extracted from that ARK
+    in order for the ARK URL to be still valid after the migration.
+
+    Args:
+        ark: an ARK version 0 of the form ark:/72163/080c-779b9990a0c3f-6e,
+            '72163' being the Name Assigning Authority number,
+            '080c' being the project shortcode,
+            '779b9990a0c3f' being an ID derived from the object's Salsah ID and
+            '6e' being check digits
+
+    Raises:
+        BaseError: if the ARK is invalid
+
+    Returns:
+        Resource IRI (str) of the form http://rdfh.ch/080C/Ef9heHjPWDS7dMR_gGax2Q
+    """
+    # create the DaSCH namespace to create version 5 UUIDs
+    generic_namespace_url = uuid.NAMESPACE_URL
+    dasch_uuid_ns = uuid.uuid5(generic_namespace_url, "https://dasch.swiss")  # cace8b00-717e-50d5-bcb9-486f39d733a2
+
+    # get the salsah resource ID from the ARK and convert it to a UUID version 5 (base64 encoded)
+    if ark.count("-") != 2:
+        raise BaseError(f"Error while converting ARK '{ark}'. The ARK seems to be invalid")
+    project_id, resource_id, _ = ark.split("-")
+    _, project_id = project_id.rsplit("/", 1)
+    project_id = project_id.upper()
+    if not regex.match("^[0-9a-fA-F]{4}$", project_id):
+        raise BaseError(f"Error while converting ARK '{ark}'. Invalid project shortcode '{project_id}'")
+    if not regex.match("^[0-9A-Za-z]+$", resource_id):
+        raise BaseError(f"Error while converting ARK '{ark}'. Invalid Salsah ID '{resource_id}'")
+
+    # make a UUID v5 from the namespace created above (which is a UUID itself) and the resource ID
+    # and encode it to base64
+    dsp_uuid = base64.urlsafe_b64encode(uuid.uuid5(dasch_uuid_ns, resource_id).bytes).decode("utf-8")
+    dsp_uuid = dsp_uuid[:-2]
+
+    # use the new UUID to create the resource IRI
+    return f"http://rdfh.ch/{project_id}/{dsp_uuid}"

dsp_tools/commands/xmlupload/prepare_xml_input/get_processed_resources.py

@@ -0,0 +1,252 @@
+from typing import cast
+from uuid import uuid4
+
+from loguru import logger
+from tqdm import tqdm
+
+from dsp_tools.commands.xmlupload.models.lookup_models import XmlReferenceLookups
+from dsp_tools.commands.xmlupload.models.permission import Permissions
+from dsp_tools.commands.xmlupload.models.processed.file_values import ProcessedFileMetadata
+from dsp_tools.commands.xmlupload.models.processed.file_values import ProcessedFileValue
+from dsp_tools.commands.xmlupload.models.processed.file_values import ProcessedIIIFUri
+from dsp_tools.commands.xmlupload.models.processed.res import MigrationMetadata
+from dsp_tools.commands.xmlupload.models.processed.res import ProcessedResource
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedBoolean
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedColor
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedDate
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedDecimal
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedGeometry
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedGeoname
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedInt
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedInterval
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedLink
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedList
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedRichtext
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedSimpleText
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedTime
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedUri
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedValue
+from dsp_tools.commands.xmlupload.prepare_xml_input.ark2iri import convert_ark_v0_to_resource_iri
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import TypeTransformerMapper
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import assert_is_string
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import assert_is_tuple
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_boolean
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_date
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_decimal
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_geometry
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_integer
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_interval
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_richtext
+from dsp_tools.commands.xmlupload.prepare_xml_input.transform_input_values import transform_simpletext
+from dsp_tools.commands.xmlupload.richtext_id2iri import find_internal_ids
+from dsp_tools.error.exceptions import XmlUploadAuthorshipsNotFoundError
+from dsp_tools.error.exceptions import XmlUploadListNodeNotFoundError
+from dsp_tools.error.exceptions import XmlUploadPermissionsNotFoundError
+from dsp_tools.legacy_models.datetimestamp import DateTimeStamp
+from dsp_tools.utils.xml_parsing.models.parsed_resource import KnoraValueType
+from dsp_tools.utils.xml_parsing.models.parsed_resource import ParsedFileValue
+from dsp_tools.utils.xml_parsing.models.parsed_resource import ParsedFileValueMetadata
+from dsp_tools.utils.xml_parsing.models.parsed_resource import ParsedMigrationMetadata
+from dsp_tools.utils.xml_parsing.models.parsed_resource import ParsedResource
+from dsp_tools.utils.xml_parsing.models.parsed_resource import ParsedValue
+
+TYPE_TRANSFORMER_MAPPER: dict[KnoraValueType, TypeTransformerMapper] = {
+    KnoraValueType.BOOLEAN_VALUE: TypeTransformerMapper(ProcessedBoolean, transform_boolean),
+    KnoraValueType.COLOR_VALUE: TypeTransformerMapper(ProcessedColor, assert_is_string),
+    KnoraValueType.DECIMAL_VALUE: TypeTransformerMapper(ProcessedDecimal, transform_decimal),
+    KnoraValueType.DATE_VALUE: TypeTransformerMapper(ProcessedDate, transform_date),
+    KnoraValueType.GEOM_VALUE: TypeTransformerMapper(ProcessedGeometry, transform_geometry),
+    KnoraValueType.GEONAME_VALUE: TypeTransformerMapper(ProcessedGeoname, assert_is_string),
+    KnoraValueType.INT_VALUE: TypeTransformerMapper(ProcessedInt, transform_integer),
+    KnoraValueType.INTERVAL_VALUE: TypeTransformerMapper(ProcessedInterval, transform_interval),
+    KnoraValueType.TIME_VALUE: TypeTransformerMapper(ProcessedTime, assert_is_string),
+    KnoraValueType.SIMPLETEXT_VALUE: TypeTransformerMapper(ProcessedSimpleText, transform_simpletext),
+    KnoraValueType.URI_VALUE: TypeTransformerMapper(ProcessedUri, assert_is_string),
+}
+
+
+def get_processed_resources(
+    resources: list[ParsedResource], lookups: XmlReferenceLookups, is_on_prod_like_server: bool
+) -> list[ProcessedResource]:
+    logger.debug("Transform ParsedResource into ProcessedResource")
+    progress_bar = tqdm(resources, desc="Preparing data for upload", dynamic_ncols=True)
+    return [_get_one_resource(res, lookups, is_on_prod_like_server) for res in progress_bar]
+
+
+def _get_one_resource(
+    resource: ParsedResource, lookups: XmlReferenceLookups, is_on_prod_like_server: bool
+) -> ProcessedResource:
+    permissions = _resolve_permission(resource.permissions_id, lookups.permissions)
+    values = [_get_one_processed_value(val, lookups) for val in resource.values]
+    migration_metadata = None
+    file_val, iiif_uri = _resolve_file_value(resource, lookups, is_on_prod_like_server)
+    if resource.migration_metadata:
+        migration_metadata = _get_resource_migration_metadata(resource.migration_metadata)
+    return ProcessedResource(
+        res_id=resource.res_id,
+        type_iri=resource.res_type,
+        label=resource.label,
+        permissions=permissions,
+        values=values,
+        file_value=file_val,
+        iiif_uri=iiif_uri,
+        migration_metadata=migration_metadata,
+    )
+
+
+def _get_resource_migration_metadata(metadata: ParsedMigrationMetadata) -> MigrationMetadata:
+    res_iri = metadata.iri
+    # ARK takes precedence over the IRI,
+    # but must be transformed into an IRI as it is only for external reference and not consistent with a DB IRI
+    if metadata.ark:
+        res_iri = convert_ark_v0_to_resource_iri(metadata.ark)
+    date = DateTimeStamp(metadata.creation_date) if metadata.creation_date else None
+    return MigrationMetadata(res_iri, date)
+
+
+def _resolve_file_value(
+    resource: ParsedResource, lookups: XmlReferenceLookups, is_on_prod_like_server: bool
+) -> tuple[None | ProcessedFileValue, None | ProcessedIIIFUri]:
+    file_val, iiif_uri = None, None
+    if not resource.file_value:
+        return file_val, iiif_uri
+
+    if is_on_prod_like_server:
+        metadata = _get_file_metadata(resource.file_value.metadata, lookups)
+    else:
+        metadata = _get_file_metadata_for_test_environments(resource.file_value.metadata, lookups)
+    if resource.file_value.value_type == KnoraValueType.STILL_IMAGE_IIIF:
+        iiif_uri = _get_iiif_uri_value(resource.file_value, metadata)
+    else:
+        file_val = _get_file_value(
+            val=resource.file_value, metadata=metadata, res_id=resource.res_id, res_label=resource.label
+        )
+    return file_val, iiif_uri
+
+
+def _get_file_value(
+    val: ParsedFileValue, metadata: ProcessedFileMetadata, res_id: str, res_label: str
+) -> ProcessedFileValue:
+    file_type = cast(KnoraValueType, val.value_type)
+    file_val = assert_is_string(val.value)
+    return ProcessedFileValue(
+        value=file_val,
+        file_type=file_type,
+        metadata=metadata,
+        res_id=res_id,
+        res_label=res_label,
+    )
+
+
+def _get_iiif_uri_value(iiif_uri: ParsedFileValue, metadata: ProcessedFileMetadata) -> ProcessedIIIFUri:
+    file_val = assert_is_string(iiif_uri.value)
+    return ProcessedIIIFUri(file_val, metadata)
+
+
+def _get_file_metadata(file_metadata: ParsedFileValueMetadata, lookups: XmlReferenceLookups) -> ProcessedFileMetadata:
+    license_iri = assert_is_string(file_metadata.license_iri)
+    copyright_holder = assert_is_string(file_metadata.copyright_holder)
+    auth_id = assert_is_string(file_metadata.authorship_id)
+    authorships = _resolve_authorship(auth_id, lookups.authorships)
+    permissions = _resolve_permission(file_metadata.permissions_id, lookups.permissions)
+    return ProcessedFileMetadata(
+        license_iri=license_iri,
+        copyright_holder=copyright_holder,
+        authorships=authorships,
+        permissions=permissions,
+    )
+
+
+def _get_file_metadata_for_test_environments(
+    metadata: ParsedFileValueMetadata, lookups: XmlReferenceLookups
+) -> ProcessedFileMetadata:
+    lic_iri = metadata.license_iri or "http://rdfh.ch/licenses/unknown"
+    copy_right = metadata.copyright_holder if metadata.copyright_holder else "DUMMY"
+    if not metadata.authorship_id:
+        authorship = ["DUMMY"]
+    else:
+        authorship = _resolve_authorship(metadata.authorship_id, lookups.authorships)
+    permissions = _resolve_permission(metadata.permissions_id, lookups.permissions)
+    return ProcessedFileMetadata(
+        license_iri=lic_iri,
+        copyright_holder=copy_right,
+        authorships=authorship,
+        permissions=permissions,
+    )
+
+
+def _resolve_authorship(authorship_id: str, lookup: dict[str, list[str]]) -> list[str]:
+    if not (found := lookup.get(authorship_id)):
+        raise XmlUploadAuthorshipsNotFoundError(f"Could not find authorships for value: {authorship_id}")
+    return found
+
+
+def _get_one_processed_value(val: ParsedValue, lookups: XmlReferenceLookups) -> ProcessedValue:
+    match val.value_type:
+        case KnoraValueType.LIST_VALUE:
+            return _get_list_value(val, lookups)
+        case KnoraValueType.LINK_VALUE:
+            return _get_link_value(val, lookups)
+        case KnoraValueType.RICHTEXT_VALUE:
+            return _get_richtext_value(val, lookups)
+        case _ as val_type:
+            transformation_mapper = TYPE_TRANSFORMER_MAPPER[val_type]
+            return _get_generic_value(val=val, lookups=lookups, transformation_mapper=transformation_mapper)
+
+
+def _get_generic_value(
+    val: ParsedValue, lookups: XmlReferenceLookups, transformation_mapper: TypeTransformerMapper
+) -> ProcessedValue:
+    transformed_value = transformation_mapper.val_transformer(val.value)
+    permission_val = _resolve_permission(val.permissions_id, lookups.permissions)
+    return transformation_mapper.val_type(transformed_value, val.prop_name, val.comment, permission_val)
+
+
+def _get_link_value(val: ParsedValue, lookups: XmlReferenceLookups) -> ProcessedValue:
+    transformed_value = assert_is_string(val.value)
+    permission_val = _resolve_permission(val.permissions_id, lookups.permissions)
+    link_val: ProcessedValue = ProcessedLink(
+        value=transformed_value,
+        prop_iri=val.prop_name,
+        comment=val.comment,
+        permissions=permission_val,
+        value_uuid=str(uuid4()),
+    )
+    return link_val
+
+
+def _get_list_value(val: ParsedValue, lookups: XmlReferenceLookups) -> ProcessedValue:
+    tuple_val = assert_is_tuple(val.value)
+    if not (list_iri := lookups.listnodes.get(tuple_val)):
+        raise XmlUploadListNodeNotFoundError(f"Could not find list IRI for value: {tuple_val}")
+    permission_val = _resolve_permission(val.permissions_id, lookups.permissions)
+    list_val: ProcessedValue = ProcessedList(
+        value=list_iri,
+        prop_iri=val.prop_name,
+        comment=val.comment,
+        permissions=permission_val,
+    )
+    return list_val
+
+
+def _get_richtext_value(val: ParsedValue, lookups: XmlReferenceLookups) -> ProcessedValue:
+    transformed_value = transform_richtext(val.value)
+    permission_val = _resolve_permission(val.permissions_id, lookups.permissions)
+    richtext: ProcessedValue = ProcessedRichtext(
+        value=transformed_value,
+        prop_iri=val.prop_name,
+        comment=val.comment,
+        permissions=permission_val,
+        resource_references=find_internal_ids(transformed_value.xmlstr),
+        value_uuid=str(uuid4()),
+    )
+    return richtext
+
+
+def _resolve_permission(permissions: str | None, permissions_lookup: dict[str, Permissions]) -> Permissions | None:
+    """Resolve the permission into a string that can be sent to the API."""
+    if permissions:
+        if not (per := permissions_lookup.get(permissions)):
+            raise XmlUploadPermissionsNotFoundError(f"Could not find permissions for value: {permissions}")
+        return per
+    return None

dsp_tools/commands/xmlupload/prepare_xml_input/iiif_uri_validator.py

@@ -0,0 +1,50 @@
+from dataclasses import dataclass
+
+import requests
+
+from dsp_tools.commands.xmlupload.models.input_problems import IIIFUriProblem
+from dsp_tools.utils.data_formats.uri_util import is_iiif_uri
+
+
+@dataclass(frozen=True)
+class IIIFUriValidator:
+    """Client handling communication with external IIIF-servers to do a health check."""
+
+    def validate_one_uri(self, uri: str) -> IIIFUriProblem | None:
+        """Check if the IIIF-server is reachable. If not, it returns information for error message."""
+        regex_has_passed = is_iiif_uri(uri)
+        response = self._make_network_call(uri)
+        if isinstance(response, Exception):
+            return IIIFUriProblem(
+                uri=uri,
+                regex_has_passed=regex_has_passed,
+                raised_exception_name=response.__class__.__name__,
+            )
+        match response.ok, regex_has_passed:
+            case True, True:
+                return None
+            case _:
+                return IIIFUriProblem(
+                    uri=uri,
+                    regex_has_passed=regex_has_passed,
+                    status_code=response.status_code,
+                )
+
+    def _make_network_call(self, uri: str) -> requests.Response | Exception:
+        info_json_uri = self._make_info_json_uri(uri)
+        try:
+            return requests.get(
+                url=info_json_uri,
+                headers={"Content-Type": "application/ld+json"},
+                timeout=10,
+            )
+        except Exception as e:  # noqa: BLE001 (blind-except)
+            return e
+
+    def _make_info_json_uri(self, uri: str) -> str:
+        splt = uri.split("/")
+        if len(splt) < 5:
+            info_uri = uri.rstrip("/")
+        else:
+            info_uri = "/".join(splt[:-4])
+        return f"{info_uri}/info.json"

dsp_tools/commands/xmlupload/prepare_xml_input/list_client.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Any
+from typing import Protocol
+from urllib.parse import quote_plus
+
+from loguru import logger
+
+from dsp_tools.clients.connection import Connection
+
+
+@dataclass(frozen=True)
+class ListNode:
+    """Information about a list node."""
+
+    node_iri: str
+    node_name: str
+
+
+@dataclass(frozen=True)
+class List:
+    """Information about a list."""
+
+    root_iri: str
+    list_name: str
+    nodes: list[ListNode]
+
+
+@dataclass(frozen=True)
+class ProjectLists:
+    """Information about the lists of a project."""
+
+    lists: list[List]
+
+
+class ListClient(Protocol):
+    """Interface (protocol) for list-related requests to the DSP-API."""
+
+    con: Connection
+    project_iri: str
+
+    def get_list_node_id_to_iri_lookup(self) -> dict[tuple[str, str], str]:
+        """Get a lookup of list node names to IRIs."""
+
+
+@dataclass
+class ListClientLive:
+    """Client handling list-related requests to the DSP-API."""
+
+    con: Connection
+    project_iri: str
+    list_info: ProjectLists | None = field(init=False, default=None)
+
+    def get_list_node_id_to_iri_lookup(self) -> dict[tuple[str, str], str]:
+        """
+        Get a mapping of list node IDs to their respective IRIs.
+        A list node ID is structured as follows:
+        `("<list name>", "<node name>") where the list name is the node name of the root node.
+
+        Returns:
+            The mapping of list node IDs to IRIs.
+        """
+        if not self.list_info:
+            self.list_info = _get_list_info_from_server(self.con, self.project_iri)
+        lookup = dict(_get_node_tuples(self.list_info.lists))
+        # Enable referencing list node IRIs in the XML:
+        # add a reference of the list node IRIs to themselves (with empty list names)
+        lookup.update({("", v): v for v in lookup.values()})
+        return lookup
+
+
+def _get_node_tuples(lists: list[List]) -> Iterable[tuple[tuple[str, str], str]]:
+    for lst in lists:
+        list_name = lst.list_name
+        for node in lst.nodes:
+            yield (list_name, node.node_name), node.node_iri
+
+
+def _get_list_info_from_server(con: Connection, project_iri: str) -> ProjectLists:
+    logger.info(f"Retrieving lists of project {project_iri}")
+    list_iris = _get_list_iris_from_server(con, project_iri)
+    lists = [_get_list_from_server(con, list_iri) for list_iri in list_iris]
+    return ProjectLists(lists)
+
+
+def _get_list_iris_from_server(con: Connection, project_iri: str) -> list[str]:
+    iri = quote_plus(project_iri)
+    res = con.get(f"/admin/lists?projectIri={iri}")
+    lists: list[dict[str, Any]] = res["lists"]
+    logger.info(f"Found {len(lists)} lists for project")
+    return [lst["id"] for lst in lists]
+
+
+def _get_list_from_server(con: Connection, list_iri: str) -> List:
+    logger.info(f"Retrieving nodes of list {list_iri}")
+    iri = quote_plus(list_iri)
+    res = con.get(f"/admin/lists/{iri}")
+    list_object: dict[str, Any] = res["list"]
+    list_info = list_object["listinfo"]
+    children: list[dict[str, Any]] = list_object["children"]
+    root_iri = list_info["id"]
+    # if the root node does not have a name, use the label instead
+    list_name: str = list_info.get("name") or list_info["labels"][0]["value"]
+    root_node = ListNode(root_iri, list_name)
+    nodes = [root_node, *_children_to_nodes(children)]
+    return List(root_iri, list_name, nodes)
+
+
+def _children_to_nodes(children: list[dict[str, Any]]) -> list[ListNode]:
+    nodes = []
+    for child in children:
+        node_iri = child["id"]
+        node_name = child["name"]
+        nodes.append(ListNode(node_iri=node_iri, node_name=node_name))
+        if "children" in child:
+            nodes.extend(_children_to_nodes(child["children"]))
+    return nodes