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

dsp_tools/error/custom_warnings.py

@@ -0,0 +1,39 @@
+from abc import ABC
+from abc import abstractmethod
+
+from dsp_tools.utils.ansi_colors import BOLD_RED
+from dsp_tools.utils.ansi_colors import RESET_TO_DEFAULT
+
+
+class DspToolsWarning(Warning, ABC):
+    """Abstract base class for warnings that implement a custom showwarnings() function"""
+
+    @classmethod
+    @abstractmethod
+    def showwarning(cls, message: str) -> None:
+        """Functionality that should be executed when a warning of this class is emitted"""
+
+
+class DspToolsUserWarning(DspToolsWarning):
+    """Class for general user-facing warnings"""
+
+    @classmethod
+    def showwarning(cls, message: str) -> None:
+        """Print the warning, without context"""
+        print(BOLD_RED + f"WARNING: {message}" + RESET_TO_DEFAULT)
+
+
+class DspToolsFutureWarning(DspToolsWarning, FutureWarning):
+    """Class for user-facing deprecation warnings"""
+
+    @classmethod
+    def showwarning(cls, message: str) -> None:
+        """Print the warning, without context"""
+        print(BOLD_RED + f"DEPRECATION WARNING: {message}" + RESET_TO_DEFAULT)
+
+
+class DspToolsUnexpectedStatusCodeWarning(DspToolsWarning):
+    @classmethod
+    def showwarning(cls, message: str) -> None:
+        """Print the warning, without context"""
+        print(BOLD_RED + f"ERROR: {message}" + RESET_TO_DEFAULT)

dsp_tools/error/exceptions.py

@@ -0,0 +1,204 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from dsp_tools.config.logger_config import LOGGER_SAVEPATH
+from dsp_tools.utils.ansi_colors import BOLD_RED
+from dsp_tools.utils.ansi_colors import RESET_TO_DEFAULT
+
+
+@dataclass
+class BaseError(Exception):
+    """
+    A basic error class for DSP-TOOLS.
+
+    Attributes:
+        message: A message that describes the error
+    """
+
+    message: str = ""
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class InternalError(BaseError):
+    """
+    Class for errors that are raised if the user cannot solve the problem themselves.
+    """
+
+    def __init__(self, custom_msg: str | None = None, keep_default_msg: bool = True) -> None:
+        default_msg = (
+            f"\n\n{BOLD_RED}An internal error occurred.{RESET_TO_DEFAULT}\n"
+            "Please contact the dsp-tools development team (at support@dasch.swiss) with the following information:\n"
+            "    - Which command was used.\n"
+            "    - If applicable, any files that were used in conjunction with the command.\n"
+            "    - A text file with the terminal output copied into.\n"
+            f"    - The log file at {LOGGER_SAVEPATH}.\n"
+        )
+        match keep_default_msg, custom_msg:
+            case False, str():
+                super().__init__(custom_msg)
+            case True, str():
+                default_msg = f"\n\n{custom_msg}\n--------------------------{default_msg}"
+                super().__init__(default_msg)
+            case _:
+                super().__init__(default_msg)
+
+
+class DockerNotReachableError(BaseError):
+    """This error is raised when docker is not running."""
+
+    def __init__(self) -> None:
+        msg = "Docker is not running properly. Please start Docker and try again."
+        super().__init__(msg)
+
+
+class DspApiNotReachableError(BaseError):
+    """This error is raised when the DSP-API could not be reached on localhost."""
+
+
+class DspToolsRequestException(BaseError):
+    """Class for errors that are raised if any request exceptions happens."""
+
+
+class InputError(BaseError):
+    """This error is raised when the user input is invalid. The message should be as user-friendly as possible."""
+
+
+class UserError(BaseError):
+    """
+    This is a base class for all the errors that are raised when the user input is invalid.
+    The message should be as user-friendly as possible.
+    """
+
+
+class InvalidGuiAttributeError(BaseError):
+    """This error is raised when a invalid gui-attribute is used."""
+
+
+class FatalNonOkApiResponseCode(BaseError):
+    """This error is raised when the API gives an unexpected response, that we cannot anticipate and handle cleanly."""
+
+    def __init__(self, request_url: str, status_code: int, response_text: str) -> None:
+        resp_txt = response_text[:200] if len(response_text) > 200 else response_text
+        msg = (
+            f"We currently do not support the following API response code for this request.\n"
+            f"Status code: {status_code}\n"
+            f"Request URL: {request_url}\n"
+            f"Original Response: {resp_txt}\n"
+            f"Please contact support@dasch.swiss with the log file at {LOGGER_SAVEPATH}."
+        )
+        super().__init__(msg)
+
+
+class UserFilepathNotFoundError(InputError):
+    """This error is raised if a filepath from the user does not exist."""
+
+    def __init__(self, filepath: str | Path) -> None:
+        msg = f"The provided filepath does not exist: {filepath}"
+        super().__init__(msg)
+
+
+class UserDirectoryNotFoundError(InputError):
+    """This error is raised if a directory from the user does not exist."""
+
+    def __init__(self, directory: str | Path) -> None:
+        msg = f"The provided directory does not exist: {directory}"
+        super().__init__(msg)
+
+
+class JSONFileParsingError(InputError):
+    """This error should be raised if the user provided input file cannot be parsed."""
+
+
+class PermanentConnectionError(BaseError):
+    """This error is raised when all attempts to reconnect to DSP have failed."""
+
+
+class InvalidInputError(BaseError):
+    """This error is raised if the API responds with a permanent error because of invalid input data"""
+
+
+class ShaclValidationCliError(BaseError):
+    """This error is raised when the validate data docker command has problems"""
+
+
+class ShaclValidationError(BaseError):
+    """This error is raised when an unexpected error occurs during the validation"""
+
+
+class InvalidIngestFileNameError(InvalidInputError):
+    """This error is raised if INGEST rejects a file due to its name."""
+
+
+class PermanentTimeOutError(BaseError):
+    """This error is raised when python throws a timeout due to no response from the DSP-API."""
+
+
+class BadCredentialsError(PermanentConnectionError):
+    """This error is raised when DSP-API doesn't accept the prodived credentials."""
+
+
+class XmlUploadError(BaseError):
+    """Represents an error raised in the context of the xmlupload."""
+
+
+class XmlInputConversionError(BaseError):
+    """Represents an error raised in the context of the xmlupload."""
+
+
+class Id2IriReplacementError(BaseError):
+    """Represents an error raised if an internal ID could not be found in the Id2Iri mapping."""
+
+
+class DuplicateIdsInXmlAndId2IriMapping(InputError):
+    """
+    Represents an error raised if a resource ID that is in the Id2Iri mapping
+    is also used as a resource id in the new data.
+    """
+
+
+class XmlUploadInterruptedError(XmlUploadError):
+    """Represents an error raised when the xmlupload was interrupted."""
+
+
+class XmlUploadPermissionsNotFoundError(BaseError):
+    """Class for errors that are raised when a permission does not exist."""
+
+
+class XmlUploadAuthorshipsNotFoundError(BaseError):
+    """Class for errors that are raised when an authorship id does not exist."""
+
+
+class XmlUploadListNodeNotFoundError(BaseError):
+    """Class for errors that are raised when a list node does not exist."""
+
+
+class UnknownDOAPException(BaseError):
+    """Class for errors that are raised if a DOAP cannot be parsed"""
+
+
+class ProjectOntologyNotFound(BaseError):
+    """Class for errors that are raised if a project is expected to have 1 or more ontologies, but none were found."""
+
+    def __init__(self, shortcode: str) -> None:
+        msg = f"The project with the shortcode '{shortcode}' does not have any ontologies."
+        super().__init__(msg)
+
+
+class ProjectNotFoundError(InputError):
+    """Class if a project is expected to exist but could not be found."""
+
+
+class InvalidLicenseError(InputError):
+    """This error is raised when a license string cannot be parsed."""
+
+    license_str: str
+
+    def __init__(self, license_str: str) -> None:
+        msg = (
+            f"The provided license string is invalid and cannot be parsed: '{license_str}'"
+            "You must provide a license that can be parsed by xmllib.find_license_in_string(). "
+            "See https://docs.dasch.swiss/latest/DSP-TOOLS/xmllib-docs/general-functions/#xmllib.general_functions.find_license_in_string"
+        )
+        super().__init__(msg)

dsp_tools/error/problems.py

@@ -0,0 +1,10 @@
+from typing import Protocol
+
+
+class Problem(Protocol):
+    """Information about input errors."""
+
+    def execute_error_protocol(self) -> str:
+        """
+        This function initiates all the steps for successful problem communication with the user.
+        """

dsp_tools/error/xmllib_errors.py

@@ -0,0 +1,20 @@
+from dsp_tools.error.exceptions import BaseError
+
+
+class XmllibInputError(BaseError):
+    """
+    This error is raised if a user provided invalid input.
+    It should never be raised plain, but with the dedicated util function.
+    """
+
+
+class XmllibFileNotFoundError(BaseError):
+    """
+    This error is raised if a user provided a filepath that does not exist.
+    """
+
+
+class XmllibInternalError(BaseError):
+    """
+    This error is raised if an internal error, i.e. an error on which the user has no influence, is found in the xmllib.
+    """

dsp_tools/error/xmllib_warnings.py

@@ -0,0 +1,54 @@
+from abc import ABC
+from abc import abstractmethod
+from dataclasses import dataclass
+from enum import StrEnum
+
+from dsp_tools.utils.ansi_colors import BOLD_RED
+from dsp_tools.utils.ansi_colors import RESET_TO_DEFAULT
+from dsp_tools.utils.ansi_colors import YELLOW
+
+
+class UserMessageSeverity(StrEnum):
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+
+
+@dataclass
+class MessageInfo:
+    """
+    message: message about what went wrong
+    resource_id: ID of the affected resource
+    prop_name: property name of the affected property (if applicable)
+    field: information about which field of the resource is affected (if not the property), e.g. "resource id", "label"
+    """
+
+    message: str
+    resource_id: str | None = None
+    prop_name: str | None = None
+    field: str | None = None
+
+
+class XmllibUserInfoBase(Warning, ABC):
+    """Base class for warnings that implement a custom showwarnings() function"""
+
+    @classmethod
+    @abstractmethod
+    def showwarning(cls, message: str) -> None:
+        """Functionality that should be executed when a warning of this class is emitted"""
+
+
+class XmllibInputInfo(XmllibUserInfoBase):
+    """If the xmllib input may be problematic"""
+
+    @classmethod
+    def showwarning(cls, message: str) -> None:
+        print(YELLOW + f"INFO | {message}" + RESET_TO_DEFAULT)
+
+
+class XmllibInputWarning(XmllibUserInfoBase):
+    """If the xmllib input is problematic"""
+
+    @classmethod
+    def showwarning(cls, message: str) -> None:
+        print(BOLD_RED + f"WARNING | {message}" + RESET_TO_DEFAULT)

dsp_tools/error/xmllib_warnings_util.py

@@ -0,0 +1,159 @@
+import csv
+import inspect
+import os
+import warnings
+from typing import Any
+from typing import Never
+
+import regex
+from dotenv import find_dotenv
+from dotenv import load_dotenv
+
+from dsp_tools.error.xmllib_errors import XmllibFileNotFoundError
+from dsp_tools.error.xmllib_errors import XmllibInputError
+from dsp_tools.error.xmllib_warnings import MessageInfo
+from dsp_tools.error.xmllib_warnings import UserMessageSeverity
+from dsp_tools.error.xmllib_warnings import XmllibInputInfo
+from dsp_tools.error.xmllib_warnings import XmllibInputWarning
+from dsp_tools.utils.ansi_colors import BOLD_YELLOW
+from dsp_tools.utils.ansi_colors import RESET_TO_DEFAULT
+
+load_dotenv(dotenv_path=find_dotenv(usecwd=True))
+
+
+def initialise_warning_file() -> None:
+    if file_path := os.getenv("XMLLIB_WARNINGS_CSV_SAVEPATH"):
+        try:
+            new_row = ["File", "Severity", "Message", "Resource ID", "Property", "Field"]
+            with open(file_path, "w", newline="") as file:
+                print(
+                    BOLD_YELLOW,
+                    f"Warnings generated by the xmllib "
+                    f"will be saved to '{file_path}' and will not be printed in the terminal.",
+                    RESET_TO_DEFAULT,
+                )
+                writer = csv.writer(file)
+                writer.writerow(new_row)
+        except FileNotFoundError:
+            raise XmllibFileNotFoundError(
+                f"The filepath '{file_path}' you entered in your .env file does not exist. "
+                f"Please ensure that the folder you named exists."
+            ) from None
+
+
+def write_message_to_csv(
+    file_path: str, msg: MessageInfo, function_trace: str | None, severity: UserMessageSeverity
+) -> None:
+    new_row = [
+        function_trace if function_trace else "",
+        str(severity),
+        msg.message if msg.message else "",
+        msg.resource_id if msg.resource_id else "",
+        msg.prop_name if msg.prop_name else "",
+        msg.field if msg.field else "",
+    ]
+    with open(file_path, "a", newline="") as file:
+        writer = csv.writer(file)
+        writer.writerow(new_row)
+
+
+def get_user_message_string(msg: MessageInfo, function_trace: str | None) -> str:
+    str_list = [f"File '{function_trace}'"] if function_trace else []
+    if msg.resource_id:
+        str_list.append(f"Resource ID '{msg.resource_id}'")
+    if msg.prop_name:
+        str_list.append(f"Property '{msg.prop_name}'")
+    if msg.field:
+        str_list.append(f"Field '{msg.field}'")
+    str_list.append(msg.message)
+    return " | ".join(str_list)
+
+
+def _get_calling_code_context() -> str | None:
+    """
+    Find file name and line number of the file that was written by the user.
+    """
+    all_stack_frames = inspect.stack()
+    frame_files = [x.filename for x in all_stack_frames]
+    calling_func_index = _get_stack_frame_number(frame_files)
+    if calling_func_index == 0:
+        return None
+    user_frame_info = all_stack_frames.pop(calling_func_index)
+    file_name = user_frame_info.filename.rsplit("/", 1)[1]
+    return f"{file_name}:{user_frame_info.lineno}"
+
+
+def _get_stack_frame_number(file_names: list[str]) -> int:
+    """
+    Get index number of first python file of the stack trace which is not any more in the dsp-tools code.
+    This is the index of the first user python file.
+    """
+    calling_func_index = -1
+    for file in file_names:
+        if _filter_stack_frames(file):
+            calling_func_index += 1
+        else:
+            calling_func_index += 1
+            break
+    return calling_func_index
+
+
+def _filter_stack_frames(file_path: str) -> bool:
+    dsp_tools_path = r"\/dsp[-_]tools\/(xmllib|error)\/"
+    if regex.search(dsp_tools_path, file_path):
+        return True
+    elif regex.search(r"^<[a-zA-Z]+>$", file_path):
+        # This is for functions like str(), which appear in the stack trace as filename "<string>"
+        return True
+    return False
+
+
+def raise_xmllib_input_error(msg: MessageInfo) -> Never:
+    """These are to be used if the error is caused by user input."""
+    function_trace = _get_calling_code_context()
+    if file_path := os.getenv("XMLLIB_WARNINGS_CSV_SAVEPATH"):
+        write_message_to_csv(file_path, msg, function_trace, UserMessageSeverity.ERROR)
+    msg_str = get_user_message_string(msg, function_trace)
+    raise XmllibInputError(msg_str)
+
+
+def emit_xmllib_input_warning(msg: MessageInfo) -> None:
+    """These are to be used if the error is caused by user input."""
+    if str(os.getenv("XMLLIB_IGNORE_USER_WARNING")).lower() == "true":
+        return
+    function_trace = _get_calling_code_context()
+    if file_path := os.getenv("XMLLIB_WARNINGS_CSV_SAVEPATH"):
+        write_message_to_csv(file_path, msg, function_trace, UserMessageSeverity.WARNING)
+    else:
+        msg_str = get_user_message_string(msg, function_trace)
+        warnings.warn(XmllibInputWarning(msg_str))
+
+
+def emit_xmllib_input_info(msg: MessageInfo) -> None:
+    """These are to be used if the error is caused by user input."""
+    if str(os.getenv("XMLLIB_IGNORE_USER_INFO")).lower() == "true":
+        return
+    function_trace = _get_calling_code_context()
+    if file_path := os.getenv("XMLLIB_WARNINGS_CSV_SAVEPATH"):
+        write_message_to_csv(file_path, msg, function_trace, UserMessageSeverity.INFO)
+    else:
+        msg_str = get_user_message_string(msg, function_trace)
+        warnings.warn(XmllibInputInfo(msg_str))
+
+
+def emit_xmllib_input_type_mismatch_warning(
+    *,
+    expected_type: str,
+    value: Any,
+    res_id: str | None,
+    value_field: str | None = None,
+    prop_name: str | None = None,
+) -> None:
+    """These are to be used if the error is caused by user input."""
+    msg_info = MessageInfo(
+        message=f"The input should be a valid {expected_type}, your input '{value}' does not match the type.",
+        resource_id=res_id,
+        prop_name=prop_name,
+        field=value_field,
+    )
+    emit_xmllib_input_warning(msg_info)

dsp_tools/error/xsd_validation_error_msg.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class XSDValidationMessage:
+    line_number: int
+    element: str | None
+    attribute: str | None
+    message: str
+
+
+def get_xsd_validation_message_str(msg: XSDValidationMessage) -> str:
+    msg_list = [f"Line Number {msg.line_number}"]
+    if msg.element:
+        msg_list.append(f"Element '{msg.element}'")
+    if msg.attribute:
+        msg_list.append(f"Attribute '{msg.attribute}'")
+    msg_list.append(msg.message)
+    return " | ".join(msg_list)

dsp_tools/{models → legacy_models}/datetimestamp.py

@@ -5,7 +5,7 @@ from typing import Union
 
 import regex
 
-from dsp_tools.models.exceptions import BaseError
+from dsp_tools.error.exceptions import BaseError
 
 
 class DateTimeStamp:
@@ -44,27 +44,27 @@ class DateTimeStamp:
         else:
             raise BaseError(f"Invalid xsd:dateTimeStamp: '{val}'")
 
-    def __eq__(self, other: Union[str, "DateTimeStamp"]) -> bool:
+    def __eq__(self, other: Union[str, DateTimeStamp]) -> bool:
         if isinstance(other, str):
             other = DateTimeStamp(other)
         return self._dateTimeStamp == other._dateTimeStamp
 
-    def __lt__(self, other: "DateTimeStamp") -> bool:
+    def __lt__(self, other: DateTimeStamp) -> bool:
         if isinstance(other, str):
             other = DateTimeStamp(other)
         return self._dateTimeStamp < other._dateTimeStamp
 
-    def __le__(self, other: "DateTimeStamp") -> bool:
+    def __le__(self, other: DateTimeStamp) -> bool:
         if isinstance(other, str):
             other = DateTimeStamp(other)
         return self._dateTimeStamp <= other._dateTimeStamp
 
-    def __gt__(self, other: "DateTimeStamp") -> bool:
+    def __gt__(self, other: DateTimeStamp) -> bool:
         if isinstance(other, str):
             other = DateTimeStamp(other)
         return self._dateTimeStamp > other._dateTimeStamp
 
-    def __ge__(self, other: "DateTimeStamp") -> bool:
+    def __ge__(self, other: DateTimeStamp) -> bool:
         if isinstance(other, str):
             other = DateTimeStamp(other)
         return self._dateTimeStamp >= other._dateTimeStamp
@@ -74,7 +74,7 @@ class DateTimeStamp:
             other = DateTimeStamp(other)
         return self._dateTimeStamp != other._dateTimeStamp
 
-    def __str__(self: "DateTimeStamp") -> str:
+    def __str__(self: DateTimeStamp) -> str:
         return self._dateTimeStamp
 
     def toJsonObj(self) -> dict[str, str]:

dsp_tools/{models → legacy_models}/langstring.py

@@ -4,7 +4,7 @@ from typing import Any
 from typing import Optional
 from typing import Union
 
-from dsp_tools.models.exceptions import BaseError
+from dsp_tools.error.exceptions import BaseError
 
 
 @unique

dsp_tools/{models → legacy_models}/projectContext.py

@@ -1,9 +1,9 @@
 from typing import Optional
 
-from dsp_tools.commands.project.models.group import Group
-from dsp_tools.commands.project.models.project import Project
-from dsp_tools.models.exceptions import BaseError
-from dsp_tools.utils.connection import Connection
+from dsp_tools.clients.connection import Connection
+from dsp_tools.commands.get.legacy_models.group import Group
+from dsp_tools.commands.get.legacy_models.project import Project
+from dsp_tools.error.exceptions import BaseError
 
 
 class ProjectContext: