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

dsp_tools/clients/list_client.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+from typing import Protocol
+
+from dsp_tools.clients.authentication_client import AuthenticationClient
+
+
+@dataclass
+class OneList:
+    list_iri: str
+    list_name: str
+    nodes: list[OneNode]
+
+    def hlist(self) -> str:
+        return f'"hlist=<{self.list_iri}>"'
+
+
+@dataclass
+class OneNode:
+    name: str
+    iri: str
+
+
+@dataclass
+class ListGetClient(Protocol):
+    """Client to request and reformat the lists of a project."""
+
+    api_url: str
+    shortcode: str
+
+    def get_all_lists_and_nodes(self) -> list[OneList]:
+        """Get all lists and its nodes from a project."""
+
+    def get_all_list_iris_and_names(self) -> dict[str, str]:
+        """Get all list names and IRIs"""
+
+
+@dataclass
+class ListCreateClient(Protocol):
+    api_url: str
+    auth: AuthenticationClient
+
+    def create_new_list(self, list_info: dict[str, Any]) -> str | None:
+        """Create a new list."""
+
+    def add_list_node(self, node_info: dict[str, Any], parent_iri: str) -> str | None:
+        """Add a list node to an existing list."""

dsp_tools/clients/list_client_live.py

@@ -0,0 +1,166 @@
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Any
+from typing import cast
+from urllib.parse import quote_plus
+
+import requests
+from requests import RequestException
+from requests import Response
+
+from dsp_tools.clients.authentication_client import AuthenticationClient
+from dsp_tools.clients.list_client import ListCreateClient
+from dsp_tools.clients.list_client import ListGetClient
+from dsp_tools.clients.list_client import OneList
+from dsp_tools.clients.list_client import OneNode
+from dsp_tools.error.exceptions import BadCredentialsError
+from dsp_tools.error.exceptions import FatalNonOkApiResponseCode
+from dsp_tools.utils.request_utils import RequestParameters
+from dsp_tools.utils.request_utils import log_and_raise_request_exception
+from dsp_tools.utils.request_utils import log_and_warn_unexpected_non_ok_response
+from dsp_tools.utils.request_utils import log_request
+from dsp_tools.utils.request_utils import log_response
+
+TIMEOUT = 60
+
+
+@dataclass
+class ListGetClientLive(ListGetClient):
+    """Client to request and reformat the lists of a project."""
+
+    api_url: str
+    shortcode: str
+
+    def get_all_lists_and_nodes(self) -> list[OneList]:
+        list_json = self._get_all_list_iris()
+        all_iris = self._extract_list_iris(list_json)
+        all_lists = [self._get_one_list(iri) for iri in all_iris]
+        return [self._reformat_one_list(lst) for lst in all_lists]
+
+    def get_all_list_iris_and_names(self) -> dict[str, str]:
+        response_json = self._get_all_list_iris()
+        iris = self._extract_list_iris(response_json)
+        names = [x["name"] for x in response_json["lists"]]
+        return dict(zip(names, iris))
+
+    def _get_all_list_iris(self) -> dict[str, Any]:
+        url = f"{self.api_url}/admin/lists?projectShortcode={self.shortcode}"
+        timeout = 10
+        log_request(RequestParameters("GET", url, timeout))
+        try:
+            response = requests.get(url=url, timeout=timeout)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        log_response(response)
+        if response.ok:
+            json_response = cast(dict[str, Any], response.json())
+            return json_response
+        raise FatalNonOkApiResponseCode(url, response.status_code, response.text)
+
+    def _extract_list_iris(self, response_json: dict[str, Any]) -> list[str]:
+        return [x["id"] for x in response_json["lists"]]
+
+    def _get_one_list(self, list_iri: str) -> dict[str, Any]:
+        encoded_list_iri = quote_plus(list_iri)
+        url = f"{self.api_url}/admin/lists/{encoded_list_iri}"
+        timeout = 30
+        log_request(RequestParameters("GET", url, timeout))
+        try:
+            response = requests.get(url=url, timeout=timeout)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        log_response(response, include_response_content=False)
+        if response.ok:
+            response_json = cast(dict[str, Any], response.json())
+            return response_json
+        raise FatalNonOkApiResponseCode(url, response.status_code, response.text)
+
+    def _reformat_one_list(self, response_json: dict[str, Any]) -> OneList:
+        list_name = response_json["list"]["listinfo"]["name"]
+        list_id = response_json["list"]["listinfo"]["id"]
+        nodes = response_json["list"]["children"]
+        all_nodes = []
+        for child in nodes:
+            all_nodes.append(OneNode(child["name"], child["id"]))
+            if node_child := child.get("children"):
+                self._reformat_children(node_child, all_nodes)
+        return OneList(list_iri=list_id, list_name=list_name, nodes=all_nodes)
+
+    def _reformat_children(self, list_child: list[dict[str, Any]], current_nodes: list[OneNode]) -> None:
+        for child in list_child:
+            current_nodes.append(OneNode(child["name"], child["id"]))
+            if grand_child := child.get("children"):
+                self._reformat_children(grand_child, current_nodes)
+
+
+@dataclass
+class ListCreateClientLive(ListCreateClient):
+    api_url: str
+    project_iri: str
+    auth: AuthenticationClient
+
+    def create_new_list(self, list_info: dict[str, Any]) -> str | None:
+        url = f"{self.api_url}/admin/lists"
+        headers = self._get_request_header()
+        try:
+            response = _post_and_log_request(url, list_info, headers)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        if response.ok:
+            result = response.json()
+            list_iri = cast(str, result["list"]["listinfo"]["id"])
+            return list_iri
+        if response.status_code == HTTPStatus.FORBIDDEN:
+            raise BadCredentialsError(
+                "Only a SystemAdmin or ProjectAdmin can create lists. "
+                "Your permissions are insufficient for this action."
+            )
+        log_and_warn_unexpected_non_ok_response(response.status_code, response.text)
+        return None
+
+    def add_list_node(self, node_info: dict[str, Any], parent_iri: str) -> str | None:
+        encoded_parent_iri = quote_plus(parent_iri)
+        url = f"{self.api_url}/admin/lists/{encoded_parent_iri}"
+        headers = self._get_request_header()
+        try:
+            response = _post_and_log_request(url, node_info, headers)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        if response.ok:
+            result = response.json()
+            node_iri = cast(str, result["nodeinfo"]["id"])
+            return node_iri
+        if response.status_code == HTTPStatus.FORBIDDEN:
+            raise BadCredentialsError(
+                "Only a SystemAdmin or ProjectAdmin can add nodes to lists. "
+                "Your permissions are insufficient for this action."
+            )
+        log_and_warn_unexpected_non_ok_response(response.status_code, response.text)
+        return None
+
+    def _get_request_header(self) -> dict[str, str]:
+        return {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.auth.get_token()}",
+        }
+
+
+def _post_and_log_request(
+    url: str,
+    data: dict[str, Any],
+    headers: dict[str, str] | None = None,
+) -> Response:
+    params = RequestParameters("POST", url, TIMEOUT, data, headers)
+    log_request(params)
+    response = requests.post(
+        url=params.url,
+        headers=params.headers,
+        data=params.data_serialized,
+        timeout=params.timeout,
+    )
+    log_response(response)
+    return response

dsp_tools/clients/metadata_client.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+from enum import Enum
+from enum import auto
+from typing import Protocol
+
+from dsp_tools.clients.authentication_client import AuthenticationClient
+
+
+class ExistingResourcesRetrieved(Enum):
+    TRUE = auto()
+    FALSE = auto()
+
+
+@dataclass
+class MetadataClient(Protocol):
+    """
+    Protocol class/interface for the metadata endpoint in the API.
+    """
+
+    server: str
+    authentication_client: AuthenticationClient
+
+    def get_resource_metadata(self, shortcode: str) -> tuple[ExistingResourcesRetrieved, list[dict[str, str]]]:
+        """Get all resource metadata from one project."""

dsp_tools/clients/metadata_client_live.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass
+from http import HTTPStatus
+
+import requests
+from loguru import logger
+from requests import RequestException
+
+from dsp_tools.clients.authentication_client import AuthenticationClient
+from dsp_tools.clients.metadata_client import ExistingResourcesRetrieved
+from dsp_tools.clients.metadata_client import MetadataClient
+from dsp_tools.utils.request_utils import RequestParameters
+from dsp_tools.utils.request_utils import log_and_warn_unexpected_non_ok_response
+from dsp_tools.utils.request_utils import log_request
+from dsp_tools.utils.request_utils import log_response
+
+TIMEOUT = 120
+
+
+@dataclass
+class MetadataClientLive(MetadataClient):
+    server: str
+    authentication_client: AuthenticationClient
+
+    def get_resource_metadata(self, shortcode: str) -> tuple[ExistingResourcesRetrieved, list[dict[str, str]]]:
+        url = f"{self.server}/v2/metadata/projects/{shortcode}/resources?format=JSON"
+        header = {"Authorization": f"Bearer {self.authentication_client.get_token()}"}
+        params = RequestParameters(method="GET", url=url, timeout=TIMEOUT, headers=header)
+        logger.debug("GET Resource Metadata")
+        log_request(params)
+        try:
+            response = requests.get(
+                url=params.url,
+                headers=params.headers,
+                timeout=params.timeout,
+            )
+        except RequestException as err:
+            logger.exception(err)
+            return ExistingResourcesRetrieved.FALSE, []
+        if response.ok:
+            log_response(response, include_response_content=False)
+            logger.debug(f"{len(response.json())} NUMBER OF RESOURCES RETRIEVED")
+            return ExistingResourcesRetrieved.TRUE, response.json()
+        if response.status_code != HTTPStatus.FORBIDDEN:
+            # this warning is to inform for unhandled status codes
+            # if the user has insufficient credentials but references resources in the XML, they will get informed then
+            log_and_warn_unexpected_non_ok_response(response.status_code, response.text)
+        return ExistingResourcesRetrieved.FALSE, []

dsp_tools/clients/ontology_clients.py

@@ -0,0 +1,49 @@
+from typing import Any
+from typing import Protocol
+
+from rdflib import Literal
+
+from dsp_tools.clients.authentication_client import AuthenticationClient
+from dsp_tools.utils.request_utils import ResponseCodeAndText
+
+
+class OntologyCreateClient(Protocol):
+    """
+    Protocol class/interface to create / update the ontology through the API.
+    """
+
+    server: str
+    authentication_client: AuthenticationClient
+
+    def get_last_modification_date(self, project_iri: str, onto_iri: str) -> Literal:
+        """Get the last modification date of an ontology"""
+
+    def post_resource_cardinalities(self, cardinality_graph: dict[str, Any]) -> Literal | None:
+        """Add cardinalities to an existing resource class."""
+
+    def post_new_property(self, property_graph: dict[str, Any]) -> Literal | ResponseCodeAndText:
+        """Create a property on the server"""
+
+    def post_new_class(self, property_graph: dict[str, Any]) -> Literal | ResponseCodeAndText:
+        """Create a class on the server"""
+
+    def post_new_ontology(self, onto_graph: dict[str, Any]) -> str | ResponseCodeAndText:
+        """Create a new ontology on the server"""
+
+
+class OntologyGetClient(Protocol):
+    """
+    Protocol class/interface to get ontologies from the API.
+    """
+
+    api_url: str
+    shortcode: str
+
+    def get_knora_api(self) -> str:
+        """Get the knora-api ontology."""
+
+    def get_ontologies(self) -> tuple[list[str], list[str]]:
+        """Get all project ontologies."""
+
+    def _get_one_ontology(self, ontology_iri: str) -> str:
+        """Get one ontology by its IRI."""

dsp_tools/clients/ontology_create_client_live.py

@@ -0,0 +1,166 @@
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Any
+from typing import cast
+
+import requests
+from rdflib import Graph
+from rdflib import Literal
+from rdflib import URIRef
+from requests import RequestException
+from requests import Response
+
+from dsp_tools.clients.authentication_client import AuthenticationClient
+from dsp_tools.clients.ontology_clients import OntologyCreateClient
+from dsp_tools.error.exceptions import BadCredentialsError
+from dsp_tools.error.exceptions import FatalNonOkApiResponseCode
+from dsp_tools.utils.rdf_constants import KNORA_API
+from dsp_tools.utils.request_utils import RequestParameters
+from dsp_tools.utils.request_utils import ResponseCodeAndText
+from dsp_tools.utils.request_utils import log_and_raise_request_exception
+from dsp_tools.utils.request_utils import log_and_warn_unexpected_non_ok_response
+from dsp_tools.utils.request_utils import log_request
+from dsp_tools.utils.request_utils import log_response
+
+TIMEOUT = 60
+
+
+@dataclass
+class OntologyCreateClientLive(OntologyCreateClient):
+    """
+    Client for the ontology endpoint in the API.
+    """
+
+    server: str
+    authentication_client: AuthenticationClient
+
+    def get_last_modification_date(self, project_iri: str, onto_iri: str) -> Literal:
+        url = f"{self.server}/v2/ontologies/metadata"
+        header = {"X-Knora-Accept-Project": project_iri}
+        try:
+            response = self._get_and_log_request(url, header)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        if response.ok:
+            return _parse_last_modification_date(response.text, URIRef(onto_iri))
+        raise FatalNonOkApiResponseCode(url, response.status_code, response.text)
+
+    def post_resource_cardinalities(self, cardinality_graph: dict[str, Any]) -> Literal | None:
+        url = f"{self.server}/v2/ontologies/cardinalities"
+        try:
+            response = self._post_and_log_request(url, cardinality_graph)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        if response.ok:
+            return _parse_last_modification_date(response.text)
+        if response.status_code == HTTPStatus.FORBIDDEN:
+            raise BadCredentialsError(
+                "Only a SystemAdmin or ProjectAdmin can add cardinalities to resource classes. "
+                "Your permissions are insufficient for this action."
+            )
+        log_and_warn_unexpected_non_ok_response(response.status_code, response.text)
+        return None
+
+    def post_new_property(self, property_graph: dict[str, Any]) -> Literal | ResponseCodeAndText:
+        url = f"{self.server}/v2/ontologies/properties"
+        try:
+            response = self._post_and_log_request(url, property_graph)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        if response.ok:
+            return _parse_last_modification_date(response.text)
+        if response.status_code == HTTPStatus.FORBIDDEN:
+            raise BadCredentialsError(
+                "Only a SystemAdmin or ProjectAdmin can create properties. "
+                "Your permissions are insufficient for this action."
+            )
+        return ResponseCodeAndText(response.status_code, response.text)
+
+    def post_new_class(self, class_graph: dict[str, Any]) -> Literal | ResponseCodeAndText:
+        url = f"{self.server}/v2/ontologies/classes"
+        try:
+            response = self._post_and_log_request(url, class_graph)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        if response.ok:
+            return _parse_last_modification_date(response.text)
+        if response.status_code == HTTPStatus.FORBIDDEN:
+            raise BadCredentialsError(
+                "Only a SystemAdmin or ProjectAdmin can create classes. "
+                "Your permissions are insufficient for this action."
+            )
+        return ResponseCodeAndText(response.status_code, response.text)
+
+    def post_new_ontology(self, onto_graph: dict[str, Any]) -> str | ResponseCodeAndText:
+        url = f"{self.server}/v2/ontologies"
+        try:
+            response = self._post_and_log_request(url, onto_graph)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+
+        if response.ok:
+            response_json: dict[str, Any] = response.json()
+            return cast(str, response_json["@id"])
+        if response.status_code == HTTPStatus.FORBIDDEN:
+            raise BadCredentialsError(
+                "Only a SystemAdmin or ProjectAdmin can create new ontologies. "
+                "Your permissions are insufficient for this action."
+            )
+        return ResponseCodeAndText(response.status_code, response.text)
+
+    def _post_and_log_request(
+        self,
+        url: str,
+        data: dict[str, Any] | None,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        data_dict, generic_headers = self._prepare_request(data, headers)
+        params = RequestParameters("POST", url, TIMEOUT, data_dict, generic_headers)
+        log_request(params)
+        response = requests.post(
+            url=params.url,
+            headers=params.headers,
+            data=params.data_serialized,
+            timeout=params.timeout,
+        )
+        log_response(response)
+        return response
+
+    def _get_and_log_request(
+        self,
+        url: str,
+        headers: dict[str, str] | None = None,
+    ) -> Response:
+        _, generic_headers = self._prepare_request({}, headers)
+        params = RequestParameters(method="GET", url=url, timeout=TIMEOUT, headers=generic_headers)
+        log_request(params)
+        response = requests.get(
+            url=params.url,
+            headers=params.headers,
+            timeout=params.timeout,
+        )
+        log_response(response)
+        return response
+
+    def _prepare_request(
+        self, data: dict[str, Any] | None, headers: dict[str, str] | None
+    ) -> tuple[dict[str, Any] | None, dict[str, str]]:
+        generic_headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.authentication_client.get_token()}",
+        }
+        data_dict = data if data else None
+        if headers:
+            generic_headers.update(headers)
+        return data_dict, generic_headers
+
+
+def _parse_last_modification_date(response_text: str, onto_iri: URIRef | None = None) -> Literal:
+    g = Graph()
+    g.parse(data=response_text, format="json-ld")
+    date = next(g.objects(subject=onto_iri, predicate=KNORA_API.lastModificationDate))
+    return cast(Literal, date)

dsp_tools/clients/ontology_get_client_live.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass
+from typing import Any
+from typing import cast
+
+import requests
+from requests import RequestException
+
+from dsp_tools.clients.ontology_clients import OntologyGetClient
+from dsp_tools.error.exceptions import FatalNonOkApiResponseCode
+from dsp_tools.error.exceptions import ProjectOntologyNotFound
+from dsp_tools.utils.request_utils import RequestParameters
+from dsp_tools.utils.request_utils import log_and_raise_request_exception
+from dsp_tools.utils.request_utils import log_request
+from dsp_tools.utils.request_utils import log_response
+
+
+@dataclass
+class OntologyGetClientLive(OntologyGetClient):
+    api_url: str
+    shortcode: str
+
+    def get_knora_api(self) -> str:
+        url = f"{self.api_url}/ontology/knora-api/v2#"
+        headers = {"Accept": "text/turtle"}
+        timeout = 60
+        params = RequestParameters("GET", url, timeout=timeout, headers=headers)
+        log_request(params)
+        try:
+            response = requests.get(url=params.url, headers=params.headers, timeout=params.timeout)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+        log_response(response, include_response_content=False)
+        if response.ok:
+            return response.text
+        raise FatalNonOkApiResponseCode(params.url, response.status_code, response.text)
+
+    def get_ontologies(self) -> tuple[list[str], list[str]]:
+        """
+        Returns a list of project ontologies as a string in turtle format.
+        And a list of the ontology IRIs
+
+        Returns:
+            list of ontologies and IRIs
+        """
+        ontology_iris = self._get_ontology_iris()
+        ontologies = [self._get_one_ontology(x) for x in ontology_iris]
+        return ontologies, ontology_iris
+
+    def _get_ontology_iris(self) -> list[str]:
+        url = f"{self.api_url}/admin/projects/shortcode/{self.shortcode}"
+        timeout = 10
+        params = RequestParameters("GET", url, timeout=timeout)
+        log_request(params)
+        try:
+            response = requests.get(url=params.url, timeout=params.timeout)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+        log_response(response)
+        if not response.ok:
+            raise FatalNonOkApiResponseCode(params.url, response.status_code, response.text)
+        response_json = cast(dict[str, Any], response.json())
+        if not (ontos := response_json.get("project", {}).get("ontologies")):
+            raise ProjectOntologyNotFound(self.shortcode)
+        output = cast(list[str], ontos)
+        return output
+
+    def _get_one_ontology(self, ontology_iri: str) -> str:
+        url = ontology_iri
+        headers = {"Accept": "text/turtle"}
+        timeout = 30
+        params = RequestParameters("GET", url, timeout=timeout, headers=headers)
+        log_request(params)
+        try:
+            response = requests.get(url=params.url, headers=params.headers, timeout=params.timeout)
+        except RequestException as err:
+            log_and_raise_request_exception(err)
+        log_response(response, include_response_content=False)
+        if response.ok:
+            return response.text
+        raise FatalNonOkApiResponseCode(params.url, response.status_code, response.text)

dsp_tools/clients/permissions_client.py

@@ -0,0 +1,68 @@
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote_plus
+
+import requests
+from loguru import logger
+from requests import RequestException
+
+from dsp_tools.clients.authentication_client import AuthenticationClient
+from dsp_tools.utils.request_utils import RequestParameters
+from dsp_tools.utils.request_utils import log_request
+from dsp_tools.utils.request_utils import log_response
+
+
+@dataclass
+class PermissionsClient:
+    auth: AuthenticationClient
+    proj_iri: str
+
+    def get_project_doaps(self) -> list[dict[str, Any]]:
+        params = RequestParameters(
+            "GET",
+            f"{self.auth.server}/admin/permissions/doap/{quote_plus(self.proj_iri)}",
+            timeout=10,
+            headers={"Accept": "application/json", "Authorization": f"Bearer {self.auth.get_token()}"},
+        )
+        log_request(params)
+        try:
+            response = requests.get(params.url, timeout=params.timeout, headers=params.headers)
+            log_response(response)
+        except RequestException:
+            logger.exception("Error while retrieving existing DOAPs")
+            return []
+        res: list[dict[str, Any]] = response.json()["default_object_access_permissions"]
+        return res
+
+    def delete_doap(self, doap_iri: str) -> bool:
+        params = RequestParameters(
+            "DELETE",
+            f"{self.auth.server}/admin/permissions/{quote_plus(doap_iri)}",
+            timeout=10,
+            headers={"Authorization": f"Bearer {self.auth.get_token()}"},
+        )
+        log_request(params)
+        try:
+            response = requests.delete(params.url, timeout=params.timeout, headers=params.headers)
+            log_response(response)
+        except RequestException:
+            logger.exception("Error while deleting DOAP")
+            return False
+        return True
+
+    def create_new_doap(self, payload: dict[str, Any]) -> bool:
+        params = RequestParameters(
+            "POST",
+            f"{self.auth.server}/admin/permissions/doap",
+            timeout=10,
+            headers={"Authorization": f"Bearer {self.auth.get_token()}"},
+            data=payload,
+        )
+        log_request(params)
+        try:
+            response = requests.post(params.url, timeout=params.timeout, headers=params.headers, json=params.data)
+            log_response(response)
+        except RequestException:
+            logger.exception("Error while creating new DOAP")
+            return False
+        return True

dsp_tools/clients/project_client.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from typing import Any
+from typing import Protocol
+
+from dsp_tools.utils.request_utils import ResponseCodeAndText
+
+
+@dataclass
+class ProjectClient(Protocol):
+    server: str
+
+    def get_project_iri(self, shortcode: str) -> str:
+        """Get the IRI of a project via shortcode."""
+
+    def post_new_project(self, project_info: dict[str, Any]) -> str | ResponseCodeAndText:
+        """Post a new project."""