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

dsp_tools/commands/xmlupload/prepare_xml_input/prepare_xml_input.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from loguru import logger
+from lxml import etree
+
+from dsp_tools.clients.connection import Connection
+from dsp_tools.commands.xmlupload.models.lookup_models import XmlReferenceLookups
+from dsp_tools.commands.xmlupload.models.processed.res import ProcessedResource
+from dsp_tools.commands.xmlupload.models.upload_clients import UploadClients
+from dsp_tools.commands.xmlupload.stash.analyse_circular_reference_graph import generate_upload_order
+from dsp_tools.commands.xmlupload.stash.create_info_for_graph import create_info_for_graph_from_processed_resources
+from dsp_tools.commands.xmlupload.stash.stash_circular_references import stash_circular_references
+from dsp_tools.commands.xmlupload.stash.stash_models import Stash
+from dsp_tools.error.exceptions import BaseError
+from dsp_tools.error.exceptions import InputError
+from dsp_tools.legacy_models.projectContext import ProjectContext
+from dsp_tools.utils.xml_parsing.get_lookups import get_authorship_lookup
+from dsp_tools.utils.xml_parsing.get_lookups import get_permissions_lookup
+from dsp_tools.utils.xml_parsing.get_parsed_resources import get_parsed_resources
+from dsp_tools.utils.xml_parsing.models.parsed_resource import ParsedResource
+
+LIST_SEPARATOR = "\n-    "
+
+
+def get_parsed_resources_and_mappers(
+    root: etree._Element, clients: UploadClients
+) -> tuple[list[ParsedResource], XmlReferenceLookups]:
+    logger.debug("Get ParsedResource and XML-Lookups from root")
+    print("Parsing XML file for upload.")
+    parsed_resources = get_parsed_resources(root, clients.legal_info_client.server)
+    processed_lookups = _get_xml_reference_lookups(root=root, clients=clients)
+    return parsed_resources, processed_lookups
+
+
+def _get_xml_reference_lookups(root: etree._Element, clients: UploadClients) -> XmlReferenceLookups:
+    proj_context = _get_project_context_from_server(
+        connection=clients.list_client.con, shortcode=root.attrib["shortcode"]
+    )
+    permissions_lookup = get_permissions_lookup(root, proj_context)
+    authorship_lookup = get_authorship_lookup(root)
+    listnode_lookup = clients.list_client.get_list_node_id_to_iri_lookup()
+    return XmlReferenceLookups(
+        permissions=permissions_lookup,
+        listnodes=listnode_lookup,
+        authorships=authorship_lookup,
+    )
+
+
+def _get_project_context_from_server(connection: Connection, shortcode: str) -> ProjectContext:
+    try:
+        proj_context = ProjectContext(con=connection, shortcode=shortcode)
+    except BaseError:
+        logger.exception("Unable to retrieve project context from DSP server")
+        raise InputError("Unable to retrieve project context from DSP server") from None
+    return proj_context
+
+
+def get_stash_and_upload_order(
+    resources: list[ProcessedResource],
+) -> tuple[list[ProcessedResource], Stash | None]:
+    logger.debug("Get stash and upload order")
+    info_for_graph = create_info_for_graph_from_processed_resources(resources)
+    stash_lookup, upload_order = generate_upload_order(info_for_graph)
+    sorting_lookup = {res.res_id: res for res in resources}
+    sorted_resources = [sorting_lookup[res_id] for res_id in upload_order]
+    stash = stash_circular_references(sorted_resources, stash_lookup)
+    return sorted_resources, stash

dsp_tools/commands/xmlupload/prepare_xml_input/read_validate_xml_file.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+
+from loguru import logger
+from lxml import etree
+from tqdm import tqdm
+
+from dsp_tools.commands.xmlupload.models.input_problems import AllIIIFUriProblems
+from dsp_tools.commands.xmlupload.prepare_xml_input.iiif_uri_validator import IIIFUriValidator
+from dsp_tools.error.custom_warnings import DspToolsUserWarning
+from dsp_tools.error.exceptions import InputError
+
+
+def validate_iiif_uris(root: etree._Element) -> None:
+    uris = [uri.strip() for node in root.iter(tag="iiif-uri") if (uri := node.text)]
+    if (num := len(uris)) > 1001:
+        warnings.warn(
+            DspToolsUserWarning(
+                f"Your data contains {num} IIIF-URIs. "
+                f"Each validation makes a server call. "
+                f"Due to the large number, the validation of the IIIF-URIs has to be skipped."
+            )
+        )
+        return
+    progress_bar = tqdm(uris, desc="Checking IIIF-URIs", dynamic_ncols=True)
+    validator = IIIFUriValidator()
+    problems = []
+    for uri in progress_bar:
+        if result := validator.validate_one_uri(uri):
+            problems.append(result)
+    if problems:
+        msg = AllIIIFUriProblems(problems).get_msg()
+        warnings.warn(DspToolsUserWarning(msg))
+        logger.warning(msg)
+
+
+def check_if_bitstreams_exist(root: etree._Element, imgdir: str) -> None:
+    """
+    Make sure that all bitstreams referenced in the XML file exist in the imgdir.
+
+    Args:
+        root: parsed XML file
+        imgdir: folder where the bitstreams are stored
+
+    Raises:
+        InputError: if a bitstream does not exist in the imgdir
+    """
+    logger.debug("Checking if filepaths exist.")
+    multimedia_resources = [x for x in root if any(y.tag == "bitstream" for y in x.iter())]
+    progress_bar = tqdm(multimedia_resources, desc="Checking multimedia filepaths", dynamic_ncols=True)
+    for res in progress_bar:
+        pth = next(Path(x.text.strip()) for x in res.iter() if x.tag == "bitstream" and x.text)
+        if not Path(imgdir / pth).is_file():
+            raise InputError(
+                f"Bitstream '{pth!s}' of resource '{res.attrib['label']}' does not exist in the imgdir '{imgdir}'."
+            )

dsp_tools/commands/xmlupload/prepare_xml_input/transform_input_values.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from json.decoder import JSONDecodeError
+from typing import Union
+from typing import assert_never
+from typing import cast
+
+from dsp_tools.commands.xmlupload.models.formatted_text_value import FormattedTextValue
+from dsp_tools.commands.xmlupload.models.processed.values import IntervalFloats
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedValue
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedValueTypes
+from dsp_tools.error.exceptions import XmlInputConversionError
+from dsp_tools.utils.data_formats.date_util import Date
+from dsp_tools.utils.data_formats.date_util import parse_date_string
+
+type InputTypes = Union[str, FormattedTextValue, tuple[str | None, str | None] | None]
+
+
+@dataclass
+class TypeTransformerMapper:
+    val_type: type[ProcessedValue]
+    val_transformer: Callable[[InputTypes], ProcessedValueTypes]
+
+
+def assert_is_string(value: InputTypes) -> str:
+    """Assert a value is a string."""
+    match value:
+        case str() as s:
+            return s
+        case FormattedTextValue() as xml:
+            raise XmlInputConversionError(f"Expected string value, but got XML value: {xml.xmlstr}")
+        case tuple():
+            raise XmlInputConversionError(f"Expected string value, but got tuple value: {value}")
+        case None:
+            raise XmlInputConversionError("Expected string value, but got None")
+        case _:
+            assert_never(value)
+
+
+def assert_is_tuple(value: InputTypes) -> tuple[str, str]:
+    """Assert a value is a tuple."""
+    match value:
+        case tuple() as t:
+            if len(t) == 2 and isinstance(t[0], str) and isinstance(t[1], str):
+                return cast(tuple[str, str], t)
+            raise XmlInputConversionError(f"Expected tuple with two elements but got {value}")
+        case FormattedTextValue() as xml:
+            raise XmlInputConversionError(f"Expected tuple value, but got XML value: {xml.xmlstr}")
+        case str():
+            raise XmlInputConversionError(f"Expected tuple value, but got string value: {value}")
+        case None:
+            raise XmlInputConversionError("Expected tuple value, but got None")
+        case _:
+            assert_never(value)
+
+
+def transform_boolean(value: InputTypes) -> bool:
+    """Transform the value into a boolean"""
+    match value:
+        case "True" | "true" | "1" | 1 | True:
+            return True
+        case "False" | "false" | "0" | 0 | False:
+            return False
+        case _:
+            raise XmlInputConversionError(f"Could not parse boolean value: {value}")
+
+
+def transform_date(input_value: InputTypes) -> Date:
+    """Transform a date string into a date object."""
+    val = assert_is_string(input_value)
+    return parse_date_string(val)
+
+
+def transform_decimal(value: InputTypes) -> float:
+    """Transform a value into a float"""
+    str_val = assert_is_string(value)
+    return float(str_val)
+
+
+def transform_integer(value: InputTypes) -> int:
+    """Transform a value into an integer"""
+    str_val = assert_is_string(value)
+    return int(str_val)
+
+
+def transform_interval(input_value: InputTypes) -> IntervalFloats:
+    """Transform a string input into an interval object."""
+    val = assert_is_tuple(input_value)
+    try:
+        return IntervalFloats(float(val[0]), float(val[1]))
+    except ValueError:
+        raise XmlInputConversionError(f"Could not parse interval: {val}") from None
+
+
+def transform_geometry(value: InputTypes) -> str:
+    """Transform a value into a geometry string"""
+    str_val = assert_is_string(value)
+    try:
+        return json.dumps(json.loads(str_val))
+    except JSONDecodeError:
+        raise XmlInputConversionError(f"Could not parse json value: {value}") from None
+
+
+def transform_simpletext(value: InputTypes) -> str:
+    str_val = assert_is_string(value)
+    if len(str_val) == 0:
+        raise XmlInputConversionError("After removing redundant whitespaces and newlines the input string is empty.")
+    return str_val
+
+
+def transform_richtext(value: InputTypes) -> FormattedTextValue:
+    str_val = assert_is_string(value)
+    if len(str_val) == 0:
+        raise XmlInputConversionError("After removing redundant whitespaces and newlines the input string is empty.")
+    return FormattedTextValue(str_val)

dsp_tools/commands/xmlupload/resource_create_client.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from typing import cast
+
+from rdflib import Graph
+
+from dsp_tools.clients.connection import Connection
+from dsp_tools.commands.xmlupload.make_rdf_graph.jsonld_utils import serialise_jsonld_for_resource
+
+
+@dataclass(frozen=True)
+class ResourceCreateClient:
+    """client class that creates resources on a DSP server."""
+
+    con: Connection
+
+    def create_resource(
+        self,
+        graph: Graph,
+        resource_has_bitstream: bool,
+    ) -> str:
+        """Creates a resource on the DSP server, and returns its IRI"""
+        res_dict = serialise_jsonld_for_resource(graph)
+        headers = {"X-Asset-Ingested": "true"} if resource_has_bitstream else None
+        res = self.con.post(route="/v2/resources", data=res_dict, headers=headers)
+        return cast(str, res["@id"])

dsp_tools/commands/xmlupload/richtext_id2iri.py

@@ -0,0 +1,37 @@
+import regex
+
+from dsp_tools.commands.xmlupload.iri_resolver import IriResolver
+from dsp_tools.error.exceptions import Id2IriReplacementError
+
+
+def prepare_richtext_string_for_upload(richtext_str: str, iri_resolver: IriResolver) -> str:
+    richtext_str, ids_not_found = replace_ids_if_found(richtext_str, iri_resolver)
+    if ids_not_found:
+        raise Id2IriReplacementError(
+            f"Some internal IDs of the following richtext could not be resolved to an IRI: {richtext_str}"
+        )
+    return _richtext_as_xml(richtext_str)
+
+
+def replace_ids_if_found(richtext_str: str, iri_resolver: IriResolver) -> tuple[str, set[str]]:
+    ids_used = find_internal_ids(richtext_str)
+    not_found = set()
+    if ids_used:
+        for id_ in ids_used:
+            if iri_found := iri_resolver.get(id_):
+                richtext_str = _replace_one_id(richtext_str, id_, iri_found)
+            else:
+                not_found.add(id_)
+    return richtext_str, not_found
+
+
+def _replace_one_id(txt: str, id_: str, iri: str) -> str:
+    return txt.replace(f'href="IRI:{id_}:IRI"', f'href="{iri}"')
+
+
+def find_internal_ids(txt: str) -> set[str]:
+    return set(regex.findall(pattern='href="IRI:(.*?):IRI"', string=txt))
+
+
+def _richtext_as_xml(richtext_str: str) -> str:
+    return f'<?xml version="1.0" encoding="UTF-8"?>\n<text>{richtext_str}</text>'

dsp_tools/commands/xmlupload/stash/analyse_circular_reference_graph.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+from typing import Any
+
+import rustworkx as rx
+
+from dsp_tools.commands.xmlupload.stash.graph_models import Cost
+from dsp_tools.commands.xmlupload.stash.graph_models import Edge
+from dsp_tools.commands.xmlupload.stash.graph_models import InfoForGraph
+from dsp_tools.commands.xmlupload.stash.graph_models import LinkValueLink
+from dsp_tools.commands.xmlupload.stash.graph_models import StandOffLink
+
+
+def generate_upload_order(info_for_graph: InfoForGraph) -> tuple[dict[str, list[str]], list[str]]:
+    """
+    Generates the upload order from the Info for the graph
+
+    Args:
+        info_for_graph: Info for the graph
+
+    Returns:
+        - A dictionary which maps the resources that have stashes to the UUIDs of the stashed links.
+        - A list of resource IDs which gives the order in which the resources should be uploaded to DSP-API.
+    """
+    graph, node_to_id, edges = _make_graph(info_for_graph)
+    stash_lookup, upload_order, _ = _generate_upload_order_from_graph(graph, node_to_id, edges)
+    return stash_lookup, upload_order
+
+
+def _make_graph(
+    info_for_graph: InfoForGraph,
+) -> tuple[rx.PyDiGraph[Any, Any], dict[int, str], list[Edge]]:
+    """
+    This function takes information about the resources of an XML file and links between them.
+    From that it constructs a rustworkx directed graph.
+    Resources are represented as nodes and links as edges.
+
+    Args:
+        info_for_graph: Information required to construct the graph
+
+    Returns:
+        - The rustworkx graph.
+        - A dictionary that maps the rustworkx index number of the nodes to the original resource ID from the XML file.
+        - A list with all the edges in the graph.
+    """
+    graph: rx.PyDiGraph[Any, Any] = rx.PyDiGraph()
+    nodes = [(id_, None, None) for id_ in info_for_graph.all_resource_ids]
+    node_indices = list(graph.add_nodes_from(nodes))
+    id_to_node = dict(zip(info_for_graph.all_resource_ids, node_indices))
+    node_to_id = dict(zip(node_indices, info_for_graph.all_resource_ids))
+    edges = [Edge(id_to_node[x.source_id], id_to_node[x.target_id], x) for x in info_for_graph.link_values]
+    for xml in info_for_graph.standoff_links:
+        edges.extend([Edge(id_to_node[xml.source_id], id_to_node[x], xml) for x in xml.target_ids])
+    graph.add_edges_from([e.as_tuple() for e in edges])
+    return graph, node_to_id, edges
+
+
+def _generate_upload_order_from_graph(
+    graph: rx.PyDiGraph[Any, Any],
+    node_to_id: dict[int, str],
+    edges: list[Edge],
+) -> tuple[dict[str, list[str]], list[str], int]:
+    """
+    Generate the order in which the resources should be uploaded to the DSP-API based on the dependencies.
+
+    Args:
+        graph: graph
+        node_to_id: mapping between indices of the graph nodes and original resource IDs from the XML file
+        edges: edges in the graph (contains info about source node, target node, and link info)
+
+    Returns:
+        - A dictionary which maps the resources that have stashes to the UUIDs of the stashed links.
+        - A list of resource IDs which gives the order in which the resources should be uploaded to DSP-API.
+        - The number of links in the stash.
+    """
+    upload_order: list[str] = []
+    stash_lookup: dict[str, list[str]] = {}
+    node_indices = set(node_to_id.keys())
+    leaf_nodes, remaining_node_indices = _remove_leaf_nodes(graph, node_to_id, node_indices)
+    upload_order.extend(leaf_nodes)
+    stash_counter = 0
+    while remaining_node_indices:
+        cycle = list(rx.digraph_find_cycle(graph))
+        links_to_remove = _find_cheapest_outgoing_links(graph, cycle, edges)
+        stash_counter += len(links_to_remove)
+        _remove_edges_to_stash(
+            graph=graph,
+            edges_to_remove=links_to_remove,
+            all_edges=edges,
+            remaining_nodes=remaining_node_indices,
+        )
+        stash_lookup = _add_stash_to_lookup_dict(stash_lookup, [x.link_object for x in links_to_remove])
+        leaf_nodes, remaining_node_indices = _remove_leaf_nodes(graph, node_to_id, remaining_node_indices)
+        upload_order.extend(leaf_nodes)
+    return stash_lookup, upload_order, stash_counter
+
+
+def _remove_leaf_nodes(
+    graph: rx.PyDiGraph[Any, Any],
+    node_to_id: dict[int, str],
+    node_indices: set[int],
+) -> tuple[list[str], set[int]]:
+    """
+    Leaf nodes are nodes that do not have any outgoing links.
+    This means that they have no dependencies and are ok to upload.
+    This function removes them from the graph.
+
+    Args:
+        graph: graph
+        node_to_id: mapping of the rustworkx index number of the nodes to the original resource ID from the XML file
+        node_indices: node indices that are in the graph
+
+    Returns:
+        - A list with the IDs of the removed leaf nodes.
+        - A set with the indices of the nodes that remain in the graph.
+    """
+    removed_leaf_nodes: list[str] = []
+    remaining_node_indices = set(node_indices)
+    while leaf_nodes := [x for x in remaining_node_indices if graph.out_degree(x) == 0]:
+        removed_leaf_nodes.extend(node_to_id[n] for n in leaf_nodes)
+        graph.remove_nodes_from(leaf_nodes)
+        remaining_node_indices = remaining_node_indices - set(leaf_nodes)
+    return removed_leaf_nodes, remaining_node_indices
+
+
+def _find_cheapest_outgoing_links(
+    graph: rx.PyDiGraph[Any, Any],
+    cycle: list[tuple[int, int]],
+    edges: list[Edge],
+) -> list[Edge]:
+    """
+    This function searches for the nodes whose outgoing links should be removed in order to break the cycle.
+    It calculates which links between the resources create the smallest stash.
+
+    Args:
+        graph: graph
+        cycle: the list with (source, target) for each edge in the cycle
+        edges: edges in the graph (contains info about source node, target node, and link info)
+
+    Returns:
+        The edges (i.e. links) that should be stashed (containing all the edges connecting the two nodes)
+    """
+    costs: list[Cost] = []
+    for source, target in cycle:
+        edges_in = graph.in_edges(source)
+        node_gain = len(edges_in)
+        edges_out = graph.out_edges(source)
+        node_cost = sum(x[2].cost_links for x in edges_out)
+        node_value = node_cost / node_gain
+        costs.append(Cost(source, target, node_value))
+    cheapest_cost = sorted(costs, key=lambda x: x.node_value)[0]
+    return [x for x in edges if x.source == cheapest_cost.source and x.target == cheapest_cost.target]
+
+
+def _remove_edges_to_stash(
+    graph: rx.PyDiGraph[Any, Any],
+    edges_to_remove: list[Edge],
+    all_edges: list[Edge],
+    remaining_nodes: set[int],
+) -> None:
+    """
+    This function removes the edges from the graph in order to break a cycle.
+
+    Args:
+        graph: graph
+        edges_to_remove: edges that should be removed
+        all_edges: all edges in the original graph
+        remaining_nodes: indices of the nodes in the graph
+    """
+    normal_edges_to_remove = [(x.source, x.target) for x in edges_to_remove]
+    # if only one (source, target) is removed, it removes only one edge, not all
+    # therefore we need as many entries in the list as there are edges between the source and the target
+
+    phantom_edges_to_remove = []
+    source, target = edges_to_remove[0].source, edges_to_remove[0].target
+    for link_to_stash in [x.link_object for x in edges_to_remove]:
+        if isinstance(link_to_stash, StandOffLink):
+            phantom_edges_to_remove.extend(
+                _find_phantom_xml_edges(source, target, all_edges, link_to_stash, remaining_nodes)
+            )
+
+    all_edges_to_remove = normal_edges_to_remove + phantom_edges_to_remove
+    graph.remove_edges_from(all_edges_to_remove)
+
+
+def _find_phantom_xml_edges(
+    source_node_index: int,
+    target_node_index: int,
+    all_edges: list[Edge],
+    xml_link_to_stash: StandOffLink,
+    remaining_nodes: set[int],
+) -> list[tuple[int, int]]:
+    """
+    If an edge that will be removed represents an XML link,
+    the text value may contain further links to other resources.
+    If we stash the XMLLink, then in the real data all links of that text value are stashed.
+    So, these "phantom" links must be removed from the graph.
+    This function identifies the edges that must be removed from the rx graph.
+
+    Args:
+        source_node_index: rustworkx index of source node
+        target_node_index: rustworkx index of target node
+        all_edges: all edges in the original graph
+        xml_link_to_stash: XML link that will be stashed
+        remaining_nodes: indices of all nodes in the graph
+
+    Returns:
+        edges (rustworkx indices of nodes) that represent the links in the original XML text
+    """
+
+    def check(x: Edge) -> bool:
+        return all(
+            (
+                x.source == source_node_index,
+                x.target != target_node_index,
+                x.link_object == xml_link_to_stash,
+                x.target in remaining_nodes,
+                # the target could have been removed because it was a leaf node, so we must check if it is still there
+            )
+        )
+
+    return [(x.source, x.target) for x in all_edges if check(x)]
+
+
+def _add_stash_to_lookup_dict(
+    stash_dict: dict[str, list[str]],
+    links_to_stash: list[StandOffLink | LinkValueLink],
+) -> dict[str, list[str]]:
+    stash_list = [stash_link.link_uuid for stash_link in links_to_stash]
+    # all stashed links have the same subject id, so we can just take the first one
+    subj_id = links_to_stash[0].source_id
+    if subj_id in stash_dict:
+        stash_dict[subj_id].extend(stash_list)
+    else:
+        stash_dict[subj_id] = stash_list
+    return stash_dict

dsp_tools/commands/xmlupload/stash/create_info_for_graph.py

@@ -0,0 +1,53 @@
+from dsp_tools.commands.xmlupload.models.processed.res import ProcessedResource
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedLink
+from dsp_tools.commands.xmlupload.models.processed.values import ProcessedRichtext
+from dsp_tools.commands.xmlupload.stash.graph_models import InfoForGraph
+from dsp_tools.commands.xmlupload.stash.graph_models import LinkValueLink
+from dsp_tools.commands.xmlupload.stash.graph_models import StandOffLink
+from dsp_tools.utils.data_formats.iri_util import is_resource_iri
+
+
+def create_info_for_graph_from_processed_resources(resources: list[ProcessedResource]) -> InfoForGraph:
+    """Extracts information to create the graph to analyse the circular references."""
+    all_links = []
+    all_stand_off = []
+    all_resource_ids = []
+    for res in resources:
+        links, stand_off = _process_one_resource(res)
+        all_links.extend(links)
+        all_stand_off.extend(stand_off)
+        all_resource_ids.append(res.res_id)
+    return InfoForGraph(
+        all_resource_ids=all_resource_ids,
+        link_values=all_links,
+        standoff_links=all_stand_off,
+    )
+
+
+def _process_one_resource(resource: ProcessedResource) -> tuple[list[LinkValueLink], list[StandOffLink]]:
+    link_values = []
+    stand_off = []
+    for val in resource.values:
+        if isinstance(val, ProcessedLink):
+            if is_resource_iri(val.value):
+                continue
+            link_values.append(
+                LinkValueLink(
+                    source_id=resource.res_id,
+                    target_id=val.value,
+                    link_uuid=val.value_uuid,
+                )
+            )
+        elif isinstance(val, ProcessedRichtext):
+            if val.resource_references:
+                only_ids = {x for x in val.resource_references if not is_resource_iri(x)}
+                if not only_ids:
+                    continue
+                stand_off.append(
+                    StandOffLink(
+                        source_id=resource.res_id,
+                        target_ids=only_ids,
+                        link_uuid=val.value_uuid,
+                    )
+                )
+    return link_values, stand_off

dsp_tools/commands/xmlupload/stash/graph_models.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class InfoForGraph:
+    all_resource_ids: list[str]
+    link_values: list[LinkValueLink]
+    standoff_links: list[StandOffLink]
+
+
+@dataclass(frozen=True)
+class LinkValueLink:
+    """
+    This class represents a direct link (resptr) between a starting resource and a target resource.
+
+    Attributes:
+        source_id: ID of the resource from which the link originates
+        target_id: ID of the resource where the link points to
+        link_uuid: identifier of this link
+    """
+
+    source_id: str
+    target_id: str
+    link_uuid: str
+
+    @property
+    def cost_links(self) -> float:
+        """The cost of this outgoing is consistently 1"""
+        return 1
+
+
+@dataclass(frozen=True)
+class StandOffLink:
+    """
+    This class represents one or more links from a single starting resource to a set of target resources,
+    where all target resources are linked to from a single text value of the starting resource.
+
+    Attributes:
+        source_id: ID of the resource from which the link(s) originate
+        target_ids: IDs of the resources that are referenced in the text value
+        link_uuid: identifier of this link
+    """
+
+    source_id: str
+    target_ids: set[str]
+    link_uuid: str
+
+    @property
+    def cost_links(self) -> float:
+        """The cost of this outgoing link (1 / number of links in the XML text)"""
+        return 1 / len(self.target_ids)
+
+
+@dataclass(frozen=True)
+class Edge:
+    """
+    This class represents an edge in the rustworkx graph.
+
+    Attributes:
+        source: rustworkx index of the resource from which the link originates
+        target: rustworkx index of the resource where the link points to
+        link_object: the link that connects the source with the target
+    """
+
+    source: int
+    target: int
+    link_object: LinkValueLink | StandOffLink
+
+    def as_tuple(self) -> tuple[int, int, LinkValueLink | StandOffLink]:
+        """Returns a representation of this edge as a tuple of the source index, target index and link object"""
+        return self.source, self.target, self.link_object
+
+
+@dataclass(frozen=True)
+class Cost:
+    """
+    Attributes:
+        source: rustworkx index of the resource from which the link originates
+        target: rustworkx index of the resource where the link points to
+        node_value: cost-gain-ratio if this link is stashed
+    """
+
+    source: int
+    target: int
+    node_value: float