dsp-tools 9.1.0.post11__py3-none-any.whl → 18.3.0.post13__py3-none-any.whl

dsp_tools/utils/request_utils.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import warnings
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import datetime
+from http import HTTPStatus
+from typing import Any
+from typing import Literal
+from typing import Never
+from typing import Union
+
+from loguru import logger
+from requests import JSONDecodeError
+from requests import ReadTimeout
+from requests import RequestException
+from requests import Response
+
+from dsp_tools.commands.get.legacy_models.context import Context
+from dsp_tools.commands.get.legacy_models.helpers import OntoIri
+from dsp_tools.config.logger_config import LOGGER_SAVEPATH
+from dsp_tools.error.custom_warnings import DspToolsUnexpectedStatusCodeWarning
+from dsp_tools.error.exceptions import DspToolsRequestException
+from dsp_tools.error.exceptions import PermanentTimeOutError
+
+
+@dataclass
+class ResponseCodeAndText:
+    status_code: int
+    text: str
+
+
+@dataclass
+class PostFiles:
+    """One or more files to be uploaded in a POST request."""
+
+    files: list[PostFile]
+
+    def to_dict(self) -> dict[str, tuple[str, Any, str] | tuple[str, Any]]:
+        return {x.file_name: x.to_tuple() for x in self.files}
+
+
+@dataclass
+class PostFile:
+    file_name: str
+    fileobj: Any
+    content_type: str | None = None
+
+    def to_tuple(self) -> tuple[str, Any, str] | tuple[str, Any]:
+        if self.content_type:
+            return self.file_name, self.fileobj, self.content_type
+        return self.file_name, self.fileobj
+
+
+class SetEncoder(json.JSONEncoder):
+    """Encoder used to serialize objects to JSON that would by default not be serializable"""
+
+    def default(self, o: Union[set[Any], Context, OntoIri]) -> Any:
+        """Return a serializable object for o"""
+        if isinstance(o, set):
+            return list(o)
+        elif isinstance(o, Context):
+            return o.toJsonObj()
+        elif isinstance(o, OntoIri):
+            return {"iri": o.iri, "hashtag": o.hashtag}
+        return json.JSONEncoder.default(self, o)
+
+
+@dataclass
+class RequestParameters:
+    method: Literal["POST", "GET", "PUT", "DELETE"]
+    url: str
+    timeout: int
+    data: dict[str, Any] | None = None
+    data_serialized: bytes | None = field(init=False, default=None)
+    headers: dict[str, str] | None = None
+    files: PostFiles | None = None
+
+    def __post_init__(self) -> None:
+        self.data_serialized = self._serialize_payload(self.data)
+
+    def _serialize_payload(self, payload: dict[str, Any] | None) -> bytes | None:
+        # If data is not encoded as bytes, issues can occur with non-ASCII characters,
+        # where the content-length of the request will turn out to be different from the actual length.
+        return json.dumps(payload, cls=SetEncoder, ensure_ascii=False).encode("utf-8") if payload else None
+
+    def as_kwargs(self) -> dict[str, Any]:
+        kwargs = {
+            "method": self.method,
+            "url": self.url,
+            "timeout": self.timeout,
+            "data": self.data_serialized,
+            "headers": self.headers,
+        }
+        if self.files:
+            kwargs["files"] = self.files.to_dict()
+        return kwargs
+
+
+def log_request(params: RequestParameters, extra_headers: dict[str, Any] | None = None) -> None:
+    """Logs the request."""
+    dumpobj = {
+        "method": params.method,
+        "url": params.url,
+        "timeout": params.timeout,
+    }
+    headers_to_log = {}
+    if extra_headers:
+        headers_to_log = extra_headers
+    if params.headers:
+        headers_to_log = headers_to_log | params.headers
+    dumpobj["headers"] = sanitize_headers(headers_to_log)
+    if params.data:
+        data = params.data.copy()
+        if "password" in data:
+            data["password"] = "***"
+        dumpobj["data"] = data
+    if params.files:
+        dumpobj["files"] = [x.file_name for x in params.files.files]
+    logger.debug(f"REQUEST: {json.dumps(dumpobj, cls=SetEncoder)}")
+
+
+def log_response(response: Response, include_response_content: bool = True) -> None:
+    """Log the response of a request."""
+    dumpobj: dict[str, Any] = {
+        "status_code": response.status_code,
+        "headers": sanitize_headers(dict(response.headers)) if response.headers else "",
+    }
+    if include_response_content:
+        try:
+            dumpobj["content"] = response.json()
+        except JSONDecodeError:
+            dumpobj["content"] = response.text
+    else:
+        dumpobj["content"] = "too big to be logged"
+    logger.debug(f"RESPONSE: {json.dumps(dumpobj)}")
+
+
+def sanitize_headers(headers: dict[str, str | bytes]) -> dict[str, str]:
+    """Remove sensitive information from request headers."""
+
+    def _mask(key: str, value: str | bytes) -> str:
+        if isinstance(value, bytes):
+            value = value.decode("utf-8")
+        if key == "Authorization" and value.startswith("Bearer "):
+            return "Bearer ***"
+        if key == "Set-Cookie":
+            return "***"
+        return value
+
+    return {k: _mask(k, v) for k, v in headers.items()}
+
+
+def log_request_failure_and_sleep(reason: str, retry_counter: int, exc_info: bool) -> None:
+    """
+    Log the reason for a request failure and sleep.
+
+    =============  ================  =============================
+    retry_counter  seconds to sleep  cumulative waiting time (min)
+    =============  ================  =============================
+    0              1                 0
+    1              2                 0
+    2              4                 0
+    3              8                 0
+    4              16                0
+    5              32                1
+    6              64                2
+    7              128               4
+    8              256               9
+    9              300               14
+    10             300               19
+    11             300               24
+    12             300               29
+    15             300               44
+    18             300               59
+    24             300               89
+    30             300               119
+    =============  ================  =============================
+    """
+    sleep_time = min(2**retry_counter, 300)
+    msg = f"{reason}: Try reconnecting to DSP server, next attempt in {sleep_time} seconds..."
+    print(f"{datetime.now()}: {msg}")
+    if exc_info:
+        logger.exception(f"{msg} ({retry_counter=:})")
+    else:
+        logger.error(f"{msg} ({retry_counter=:})")
+    time.sleep(sleep_time)
+
+
+def log_and_raise_timeouts(error: TimeoutError | ReadTimeout) -> Never:
+    """Log a timeout error raised by a request and raise our own PermanentTimeOutError"""
+    msg = f"A '{error.__class__.__name__}' occurred during the connection to the DSP server."
+    print(f"{datetime.now()}: {msg}")
+    logger.error(msg)
+    raise PermanentTimeOutError(msg) from None
+
+
+def should_retry(response: Response) -> bool:
+    """Returns the decision if a retry of a request is sensible."""
+    in_500_range = 500 <= response.status_code < 600
+    try_again_later = "try again later" in response.text.lower()
+    in_testing_env = os.getenv("DSP_TOOLS_TESTING") == "true"  # set in .github/workflows/tests-on-push.yml
+    return (try_again_later or in_500_range) and not in_testing_env
+
+
+def log_and_raise_request_exception(error: RequestException) -> Never:
+    msg = (
+        f"During an API call the following exception occurred. "
+        f"Please contact support@dasch.swiss with the log file at {LOGGER_SAVEPATH} "
+        f"if you required help resolving the issue.\n"
+        f"Original exception name: {error.__class__.__name__}\n"
+    )
+    if error.request:
+        msg += f"Original request: {error.request.method} {error.request.url}"
+    logger.exception(msg)
+    raise DspToolsRequestException(msg) from None
+
+
+def log_and_warn_unexpected_non_ok_response(status_code: int, response_text: str) -> None:
+    resp_txt = response_text[:200] if len(response_text) > 200 else response_text
+    msg = (
+        "We got an unexpected API response during the following request. "
+        "Please contact the dsp-tools development team (at support@dasch.swiss) with your log file "
+        "so that we can handle this more gracefully in the future.\n"
+        f"Response status code: {status_code}\n"
+        f"Original Message: {resp_txt}"
+    )
+    logger.warning(msg)
+    warnings.warn(DspToolsUnexpectedStatusCodeWarning(msg))
+
+
+def is_server_error(response: ResponseCodeAndText) -> bool:
+    if HTTPStatus.INTERNAL_SERVER_ERROR <= response.status_code <= HTTPStatus.NETWORK_AUTHENTICATION_REQUIRED:
+        return True
+    return False

dsp_tools/utils/xml_parsing/get_lookups.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import cast
+
+import regex
+from lxml import etree
+
+from dsp_tools.commands.xmlupload.models.permission import Permissions
+from dsp_tools.commands.xmlupload.models.permissions_parsed import XmlPermission
+from dsp_tools.legacy_models.projectContext import ProjectContext
+
+
+def get_authorship_lookup(root: etree._Element) -> dict[str, list[str]]:
+    def get_one_author(ele: etree._Element) -> str:
+        # The xsd file ensures that the body of the element contains valid non-whitespace characters
+        txt = cast(str, ele.text)
+        txt = regex.sub(r" +", " ", txt)
+        return txt.strip()
+
+    authorship_lookup = {}
+    for auth in root.iter(tag="authorship"):
+        individual_authors = [get_one_author(child) for child in auth.iterchildren()]
+        authorship_lookup[auth.attrib["id"]] = individual_authors
+    return authorship_lookup
+
+
+def get_permissions_lookup(root: etree._Element, proj_context: ProjectContext) -> dict[str, Permissions]:
+    permission_ele = list(root.iter(tag="permissions"))
+    permissions = [XmlPermission(permission, proj_context) for permission in permission_ele]
+    permissions_dict = {permission.permission_id: permission for permission in permissions}
+    permissions_lookup = {name: perm.get_permission_instance() for name, perm in permissions_dict.items()}
+    return permissions_lookup

dsp_tools/utils/xml_parsing/get_parsed_resources.py

@@ -0,0 +1,325 @@
+from pathlib import Path
+
+import regex
+from lxml import etree
+
+from dsp_tools.commands.validate_data.mappers import XML_TAG_TO_VALUE_TYPE_MAPPER
+from dsp_tools.error.exceptions import InputError
+from dsp_tools.utils.data_formats.iri_util import convert_api_url_for_correct_iri_namespace_construction
+from dsp_tools.utils.rdf_constants import KNORA_API_PREFIX
+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
+
+
+def get_parsed_resources(root: etree._Element, api_url: str) -> list[ParsedResource]:
+    api_url = convert_api_url_for_correct_iri_namespace_construction(api_url)
+    iri_lookup = _create_from_local_name_to_absolute_iri_lookup(root, api_url)
+    all_res: list[ParsedResource] = []
+    for res in root.iterdescendants(tag="resource"):
+        res_type = iri_lookup[res.attrib["restype"]]
+        all_res.append(_parse_one_resource(res, res_type, iri_lookup))
+    for res in root.iterdescendants(tag="region"):
+        res_type = f"{KNORA_API_PREFIX}Region"
+        all_res.append(_parse_one_resource(res, res_type, iri_lookup))
+    for res in root.iterdescendants(tag="link"):
+        res_type = f"{KNORA_API_PREFIX}LinkObj"
+        all_res.append(_parse_one_resource(res, res_type, iri_lookup))
+    for res in root.iterdescendants(tag="video-segment"):
+        all_res.append(_parse_segment(res, "Video"))
+    for res in root.iterdescendants(tag="audio-segment"):
+        all_res.append(_parse_segment(res, "Audio"))
+    return all_res
+
+
+def _create_from_local_name_to_absolute_iri_lookup(root: etree._Element, api_url: str) -> dict[str, str]:
+    shortcode = root.attrib["shortcode"]
+    default_ontology = root.attrib["default-ontology"]
+    local_names = {ele.attrib["restype"] for ele in root.iterdescendants(tag="resource")}
+    props = {ele.attrib["name"] for ele in root.iter() if "name" in ele.attrib}
+    local_names.update(props)
+    lookup = {local: _get_one_absolute_iri(local, shortcode, default_ontology, api_url) for local in local_names}
+    return lookup
+
+
+def _get_one_absolute_iri(local_name: str, shortcode: str, default_ontology: str, api_url: str) -> str:
+    split_name = local_name.split(":")
+    if len(split_name) == 1:
+        return f"{KNORA_API_PREFIX}{local_name}"
+    if len(split_name) == 2:
+        if split_name[0] == "":
+            return f"{_construct_namespace(api_url, shortcode, default_ontology)}{split_name[1]}"
+        if split_name[0] == "knora-api":
+            return f"{KNORA_API_PREFIX}{split_name[1]}"
+        return f"{_construct_namespace(api_url, shortcode, split_name[0])}{split_name[1]}"
+    raise InputError(
+        f"It is not permissible to have a colon in a property or resource class name. "
+        f"Please correct the following: {local_name}"
+    )
+
+
+def _construct_namespace(api_url: str, shortcode: str, onto_name: str) -> str:
+    return f"{api_url}/ontology/{shortcode}/{onto_name}/v2#"
+
+
+def _parse_segment(segment: etree._Element, segment_type: str) -> ParsedResource:
+    values = _parse_segment_values(segment, segment_type)
+    migration_metadata = _parse_migration_metadata(segment)
+    return ParsedResource(
+        res_id=segment.attrib["id"],
+        res_type=f"{KNORA_API_PREFIX}{segment_type}Segment",
+        label=segment.attrib["label"],
+        permissions_id=segment.attrib.get("permissions"),
+        values=values,
+        file_value=None,
+        migration_metadata=migration_metadata,
+    )
+
+
+def _parse_segment_values(segment: etree._Element, segment_type: str) -> list[ParsedValue]:
+    values: list[ParsedValue] = []
+    value: str | tuple[str, str] | None
+    for val in segment.iterchildren():
+        prop = f"{KNORA_API_PREFIX}{val.tag!s}"
+        match val.tag:
+            case "isSegmentOf":
+                val_type = KnoraValueType.LINK_VALUE
+                prop = f"{KNORA_API_PREFIX}is{segment_type}SegmentOf"
+                value = val.text.strip() if val.text else None
+            case "hasSegmentBounds":
+                val_type = KnoraValueType.INTERVAL_VALUE
+                value = (val.attrib["segment_start"], val.attrib["segment_end"])
+            case "hasDescription" | "hasComment":
+                val_type = KnoraValueType.RICHTEXT_VALUE
+                value = _get_richtext_as_string(val)
+            case "relatesTo":
+                val_type = KnoraValueType.LINK_VALUE
+                value = val.text.strip() if val.text else None
+            case _:
+                val_type = KnoraValueType.SIMPLETEXT_VALUE
+                value = _get_simpletext_as_string(val)
+        values.append(
+            ParsedValue(
+                prop_name=prop,
+                value=value,
+                value_type=val_type,
+                permissions_id=val.attrib.get("permissions"),
+                comment=val.attrib.get("comment"),
+            )
+        )
+    return values
+
+
+def _parse_one_resource(resource: etree._Element, res_type: str, iri_lookup: dict[str, str]) -> ParsedResource:
+    values, file_value = _parse_values(resource, iri_lookup)
+    migration_metadata = _parse_migration_metadata(resource)
+    return ParsedResource(
+        res_id=resource.attrib["id"],
+        res_type=res_type,
+        label=resource.attrib["label"],
+        permissions_id=resource.attrib.get("permissions"),
+        values=values,
+        file_value=file_value,
+        migration_metadata=migration_metadata,
+    )
+
+
+def _parse_migration_metadata(resource: etree._Element) -> ParsedMigrationMetadata | None:
+    metadata = (resource.attrib.get("iri"), resource.attrib.get("ark"), resource.attrib.get("creation_date"))
+    if any(metadata):
+        return ParsedMigrationMetadata(
+            iri=metadata[0],
+            ark=metadata[1],
+            creation_date=metadata[2],
+        )
+    return None
+
+
+def _parse_values(
+    resource: etree._Element, iri_lookup: dict[str, str]
+) -> tuple[list[ParsedValue], ParsedFileValue | None]:
+    values = []
+    asset_value = None
+    for val in resource.iterchildren():
+        match val.tag:
+            case "bitstream":
+                asset_value = _parse_file_values(val)
+            case "iiif-uri":
+                asset_value = _parse_iiif_uri(val)
+            case _:
+                values.extend(_parse_one_value(val, iri_lookup))
+    return values, asset_value
+
+
+def _parse_one_value(values: etree._Element, iri_lookup: dict[str, str]) -> list[ParsedValue]:
+    prop_name = iri_lookup[values.attrib["name"]]
+    match values.tag:
+        case "list-prop":
+            return _parse_list_value(values, prop_name)
+        case "text-prop":
+            return _parse_text_value(values, prop_name)
+        case _:
+            return _parse_generic_values(values, prop_name)
+
+
+def _parse_generic_values(values: etree._Element, prop_name: str) -> list[ParsedValue]:
+    value_type = XML_TAG_TO_VALUE_TYPE_MAPPER[str(values.tag)]
+    parsed_values = []
+    for val in values:
+        parsed_values.append(
+            ParsedValue(
+                prop_name=prop_name,
+                value=val.text.strip() if val.text else None,
+                value_type=value_type,
+                permissions_id=val.attrib.get("permissions"),
+                comment=val.attrib.get("comment"),
+            )
+        )
+    return parsed_values
+
+
+def _parse_list_value(values: etree._Element, prop_name: str) -> list[ParsedValue]:
+    parsed_values = []
+    list_name = values.attrib["list"]
+    for val in values:
+        list_node = val.text.strip() if val.text else None
+        parsed_values.append(
+            ParsedValue(
+                prop_name=prop_name,
+                value=(list_name, list_node),
+                value_type=KnoraValueType.LIST_VALUE,
+                permissions_id=val.attrib.get("permissions"),
+                comment=val.attrib.get("comment"),
+            )
+        )
+    return parsed_values
+
+
+def _parse_text_value(values: etree._Element, prop_name: str) -> list[ParsedValue]:
+    parsed_values = []
+    for val in values:
+        if val.attrib["encoding"] == "xml":
+            val_type = KnoraValueType.RICHTEXT_VALUE
+            value = _get_richtext_as_string(val)
+        else:
+            val_type = KnoraValueType.SIMPLETEXT_VALUE
+            value = _get_simpletext_as_string(val)
+        parsed_values.append(
+            ParsedValue(
+                prop_name=prop_name,
+                value=value,
+                value_type=val_type,
+                permissions_id=val.attrib.get("permissions"),
+                comment=val.attrib.get("comment"),
+            )
+        )
+    return parsed_values
+
+
+def _get_richtext_as_string(value: etree._Element) -> str | None:
+    # Not entering any values within the tag results in None,
+    # however if only whitespaces are entered then it should return an empty string so that the user message is precise.
+    if not value.text and len(value) == 0:
+        return None
+    xmlstr = etree.tostring(value, encoding="unicode", method="xml").strip()
+    xmlstr = regex.sub(f"^<{value.tag!s}.*?>", "", xmlstr, count=1)
+    xmlstr = regex.sub(f"</{value.tag!s}>$", "", xmlstr)
+    striped_str = xmlstr.strip()
+    return _cleanup_formatted_text(striped_str)
+
+
+def _cleanup_formatted_text(xmlstr_orig: str) -> str:
+    """
+    In a xml-encoded text value from the XML file,
+    there may be non-text characters that must be removed.
+    This function:
+        - replaces (multiple) line breaks by a space
+        - replaces multiple spaces or tabstops by a single space (except within `<code>` or `<pre>` tags)
+
+    Args:
+        xmlstr_orig: content of the tag from the XML file, in serialized form
+
+    Returns:
+        purged string, suitable to be sent to DSP-API
+    """
+    # replace (multiple) line breaks by a space
+    xmlstr = regex.sub("\n+", " ", xmlstr_orig)
+    # replace multiple spaces or tabstops by a single space (except within <code> or <pre> tags)
+    # the regex selects all spaces/tabstops not followed by </xyz> without <xyz in between.
+    # credits: https://stackoverflow.com/a/46937770/14414188
+    xmlstr = regex.sub("( {2,}|\t+)(?!(.(?!<(code|pre)))*</(code|pre)>)", " ", xmlstr)
+    # remove spaces after <br/> tags (except within <code> tags)
+    xmlstr = regex.sub("((?<=<br/?>) )(?!(.(?!<code))*</code>)", "", xmlstr)
+    # remove leading and trailing spaces
+    xmlstr = xmlstr.strip()
+    return xmlstr
+
+
+def _get_simpletext_as_string(value: etree._Element) -> str | None:
+    # Not entering any values within the tag results in None,
+    # however if only whitespaces are entered then it should return an empty string so that the user message is precise.
+    if len(value) == 0:
+        if not (found := value.text):
+            return None
+    else:
+        # Extract the inner XML content, preserving tags
+        found = "".join(etree.tostring(child, encoding="unicode") for child in value.iterdescendants())
+        if value.text:
+            found = value.text + found
+    # replace multiple spaces or tabstops by a single space
+    str_val = regex.sub(r" {2,}|\t+", " ", found)
+    # remove leading and trailing spaces (of every line, but also of the entire string)
+    str_val = "\n".join([s.strip() for s in str_val.split("\n")])
+    result = str_val.strip()
+    return result
+
+
+def _parse_iiif_uri(iiif_uri: etree._Element) -> ParsedFileValue:
+    return ParsedFileValue(
+        value=iiif_uri.text.strip() if iiif_uri.text else None,
+        value_type=KnoraValueType.STILL_IMAGE_IIIF,
+        metadata=_parse_file_metadata(iiif_uri),
+    )
+
+
+def _parse_file_values(file_value: etree._Element) -> ParsedFileValue:
+    val = file_value.text.strip() if file_value.text else None
+    return ParsedFileValue(
+        value=val,
+        value_type=_get_file_value_type(val),
+        metadata=_parse_file_metadata(file_value),
+    )
+
+
+def _parse_file_metadata(file_value: etree._Element) -> ParsedFileValueMetadata:
+    return ParsedFileValueMetadata(
+        license_iri=file_value.attrib.get("license"),
+        copyright_holder=file_value.attrib.get("copyright-holder"),
+        authorship_id=file_value.attrib.get("authorship-id"),
+        permissions_id=file_value.attrib.get("permissions"),
+    )
+
+
+def _get_file_value_type(file_name: str | None) -> KnoraValueType | None:  # noqa:PLR0911 (Too many return statements)
+    if not file_name:
+        return None
+    file_extension = Path(file_name).suffix[1:].lower()
+    match file_extension:
+        case "zip" | "tar" | "gz" | "z" | "tgz" | "gzip" | "7z":
+            return KnoraValueType.ARCHIVE_FILE
+        case "mp3" | "wav":
+            return KnoraValueType.AUDIO_FILE
+        case "pdf" | "doc" | "docx" | "xls" | "xlsx" | "ppt" | "pptx" | "epub":
+            return KnoraValueType.DOCUMENT_FILE
+        case "mp4":
+            return KnoraValueType.MOVING_IMAGE_FILE
+        # jpx is the extension of the files returned by dsp-ingest
+        case "jpg" | "jpeg" | "jp2" | "png" | "tif" | "tiff" | "jpx":
+            return KnoraValueType.STILL_IMAGE_FILE
+        case "odd" | "rng" | "txt" | "xml" | "htm" | "html" | "xsd" | "xsl" | "csv" | "json":
+            return KnoraValueType.TEXT_FILE
+        case _:
+            return None

dsp_tools/utils/xml_parsing/models/parsed_resource.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from enum import auto
+
+
+@dataclass
+class ParsedResource:
+    res_id: str
+    res_type: str
+    label: str
+    permissions_id: str | None
+    values: list[ParsedValue]
+    file_value: ParsedFileValue | None
+    migration_metadata: ParsedMigrationMetadata | None
+
+
+@dataclass
+class ParsedMigrationMetadata:
+    iri: str | None
+    ark: str | None
+    creation_date: str | None
+
+
+@dataclass
+class ParsedValue:
+    prop_name: str
+    value: str | tuple[str | None, str | None] | None
+    value_type: KnoraValueType
+    permissions_id: str | None
+    comment: str | None
+
+
+@dataclass
+class ParsedFileValue:
+    value: str | None
+    value_type: KnoraValueType | None
+    metadata: ParsedFileValueMetadata
+
+
+@dataclass
+class ParsedFileValueMetadata:
+    license_iri: str | None
+    copyright_holder: str | None
+    authorship_id: str | None
+    permissions_id: str | None
+
+
+class KnoraValueType(Enum):
+    """
+    Maps to a knora value type, for example: BOOLEAN_VALUE -> knora-api:BooleanValue
+    """
+
+    BOOLEAN_VALUE = auto()
+    COLOR_VALUE = auto()
+    DATE_VALUE = auto()
+    DECIMAL_VALUE = auto()
+    GEONAME_VALUE = auto()
+    GEOM_VALUE = auto()
+    INT_VALUE = auto()
+    INTERVAL_VALUE = auto()
+    LINK_VALUE = auto()
+    LIST_VALUE = auto()
+    SIMPLETEXT_VALUE = auto()
+    RICHTEXT_VALUE = auto()
+    TIME_VALUE = auto()
+    URI_VALUE = auto()
+
+    ARCHIVE_FILE = auto()
+    AUDIO_FILE = auto()
+    DOCUMENT_FILE = auto()
+    MOVING_IMAGE_FILE = auto()
+    STILL_IMAGE_FILE = auto()
+    STILL_IMAGE_IIIF = auto()
+    TEXT_FILE = auto()