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

dsp_tools/commands/xmlupload/xmlupload.py

@@ -0,0 +1,516 @@
+from __future__ import annotations
+
+import pickle
+import sys
+import warnings
+from datetime import datetime
+from pathlib import Path
+from typing import Never
+
+from loguru import logger
+from rdflib import URIRef
+from tqdm import tqdm
+
+from dsp_tools.cli.args import ServerCredentials
+from dsp_tools.cli.args import ValidateDataConfig
+from dsp_tools.cli.args import ValidationSeverity
+from dsp_tools.clients.authentication_client import AuthenticationClient
+from dsp_tools.clients.authentication_client_live import AuthenticationClientLive
+from dsp_tools.clients.connection import Connection
+from dsp_tools.clients.connection_live import ConnectionLive
+from dsp_tools.clients.fuseki_metrics import FusekiMetrics
+from dsp_tools.clients.legal_info_client import LegalInfoClient
+from dsp_tools.clients.legal_info_client_live import LegalInfoClientLive
+from dsp_tools.clients.project_client import ProjectClient
+from dsp_tools.clients.project_client_live import ProjectClientLive
+from dsp_tools.commands.validate_data.validate_data import validate_parsed_resources
+from dsp_tools.commands.xmlupload.make_rdf_graph.make_resource_and_values import create_resource_with_values
+from dsp_tools.commands.xmlupload.models.ingest import AssetClient
+from dsp_tools.commands.xmlupload.models.ingest import DspIngestClientLive
+from dsp_tools.commands.xmlupload.models.lookup_models import IRILookups
+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.models.upload_state import UploadState
+from dsp_tools.commands.xmlupload.prepare_xml_input.get_processed_resources import get_processed_resources
+from dsp_tools.commands.xmlupload.prepare_xml_input.list_client import ListClient
+from dsp_tools.commands.xmlupload.prepare_xml_input.list_client import ListClientLive
+from dsp_tools.commands.xmlupload.prepare_xml_input.prepare_xml_input import get_parsed_resources_and_mappers
+from dsp_tools.commands.xmlupload.prepare_xml_input.prepare_xml_input import get_stash_and_upload_order
+from dsp_tools.commands.xmlupload.prepare_xml_input.read_validate_xml_file import check_if_bitstreams_exist
+from dsp_tools.commands.xmlupload.prepare_xml_input.read_validate_xml_file import validate_iiif_uris
+from dsp_tools.commands.xmlupload.resource_create_client import ResourceCreateClient
+from dsp_tools.commands.xmlupload.stash.upload_stashed_resptr_props import upload_stashed_resptr_props
+from dsp_tools.commands.xmlupload.stash.upload_stashed_xml_texts import upload_stashed_xml_texts
+from dsp_tools.commands.xmlupload.upload_config import UploadConfig
+from dsp_tools.commands.xmlupload.write_diagnostic_info import write_id2iri_mapping
+from dsp_tools.config.logger_config import WARNINGS_SAVEPATH
+from dsp_tools.error.custom_warnings import DspToolsUserWarning
+from dsp_tools.error.exceptions import BaseError
+from dsp_tools.error.exceptions import PermanentConnectionError
+from dsp_tools.error.exceptions import PermanentTimeOutError
+from dsp_tools.error.exceptions import XmlUploadInterruptedError
+from dsp_tools.utils.ansi_colors import BOLD_RED
+from dsp_tools.utils.ansi_colors import BOLD_YELLOW
+from dsp_tools.utils.ansi_colors import RESET_TO_DEFAULT
+from dsp_tools.utils.data_formats.uri_util import is_prod_like_server
+from dsp_tools.utils.fuseki_bloating import communicate_fuseki_bloating
+from dsp_tools.utils.replace_id_with_iri import use_id2iri_mapping_to_replace_ids
+from dsp_tools.utils.xml_parsing.models.parsed_resource import ParsedResource
+from dsp_tools.utils.xml_parsing.parse_clean_validate_xml import parse_and_clean_xml_file
+
+
+def xmlupload(
+    input_file: Path,
+    creds: ServerCredentials,
+    imgdir: str,
+    config: UploadConfig = UploadConfig(),
+) -> bool:
+    """
+    This function reads an XML file and imports the data described in it onto the DSP server.
+
+    Args:
+        input_file: path to XML file containing the resources
+        creds: the credentials to access the DSP server
+        imgdir: the image directory
+        config: the configuration for the upload
+
+    Raises:
+        BaseError: in case of permanent network or software failure
+        InputError: in case of permanent network or software failure, or if the XML file is invalid
+        InputError: in case of permanent network or software failure, or if the XML file is invalid
+
+    Returns:
+        True if all resources could be uploaded without errors; False if one of the resources could not be
+        uploaded because there is an error in it
+    """
+
+    root = parse_and_clean_xml_file(input_file)
+    shortcode = root.attrib["shortcode"]
+
+    auth = AuthenticationClientLive(server=creds.server, email=creds.user, password=creds.password)
+    con = ConnectionLive(creds.server, auth)
+    config = config.with_server_info(server=creds.server, shortcode=shortcode)
+    clients = _get_live_clients(con, auth, creds, shortcode, imgdir)
+
+    parsed_resources, lookups = get_parsed_resources_and_mappers(root, clients)
+    if config.id2iri_file:
+        parsed_resources = use_id2iri_mapping_to_replace_ids(parsed_resources, Path(config.id2iri_file))
+
+    is_on_prod_like_server = is_prod_like_server(creds.server)
+
+    validation_ok = _handle_validation(
+        parsed_resources=parsed_resources,
+        lookups=lookups,
+        config=config,
+        is_on_prod_like_server=is_on_prod_like_server,
+        auth=auth,
+        input_file=input_file,
+    )
+    if not validation_ok:
+        return False
+
+    check_if_bitstreams_exist(root, imgdir)
+    if not config.skip_iiif_validation:
+        validate_iiif_uris(root)
+
+    if not is_on_prod_like_server:
+        enable_unknown_license_if_any_are_missing(clients.legal_info_client, parsed_resources)
+
+    processed_resources = get_processed_resources(parsed_resources, lookups, is_on_prod_like_server)
+
+    sorted_resources, stash = get_stash_and_upload_order(processed_resources)
+    state = UploadState(
+        pending_resources=sorted_resources,
+        pending_stash=stash,
+        config=config,
+    )
+
+    return execute_upload(clients, state)
+
+
+def _handle_validation(
+    parsed_resources: list[ParsedResource],
+    lookups: XmlReferenceLookups,
+    config: UploadConfig,
+    is_on_prod_like_server: bool,
+    auth: AuthenticationClient,
+    input_file: Path,
+) -> bool:
+    validation_should_be_skipped = config.skip_validation
+    if is_on_prod_like_server and config.skip_validation:
+        msg = (
+            "You set the flag '--skip-validation' to circumvent the SHACL schema validation. "
+            "This means that the upload may fail due to undetected errors. "
+            "Do you wish to skip the validation (yes/no)? "
+        )
+        resp = ""
+        while resp not in ["yes", "no"]:
+            resp = input(BOLD_RED + msg + RESET_TO_DEFAULT)
+        if str(resp) == "no":
+            validation_should_be_skipped = False
+    if not validation_should_be_skipped:
+        ignore_duplicates = config.ignore_duplicate_files_warning
+        if is_on_prod_like_server and ignore_duplicates:
+            msg = (
+                "You set the flag '--ignore-duplicate-files-warning'. "
+                "This means that duplicate multimedia files will not be detected. "
+                "Are you sure you want to exclude this from the validation? (yes/no)"
+            )
+            resp = ""
+            while resp not in ["yes", "no"]:
+                resp = input(BOLD_RED + msg + RESET_TO_DEFAULT)
+            if str(resp) == "no":
+                ignore_duplicates = False
+        v_severity = config.validation_severity
+        if is_on_prod_like_server:
+            v_severity = ValidationSeverity.INFO
+        validation_passed = validate_parsed_resources(
+            parsed_resources=parsed_resources,
+            authorship_lookup=lookups.authorships,
+            permission_ids=list(lookups.permissions.keys()),
+            shortcode=config.shortcode,
+            config=ValidateDataConfig(
+                input_file,
+                save_graph_dir=None,
+                severity=v_severity,
+                ignore_duplicate_files_warning=ignore_duplicates,
+                is_on_prod_server=is_on_prod_like_server,
+                skip_ontology_validation=config.skip_ontology_validation,
+                do_not_request_resource_metadata_from_db=config.do_not_request_resource_metadata_from_db,
+            ),
+            auth=auth,
+        )
+        if not validation_passed:
+            return False
+    else:
+        logger.debug("SHACL validation was skipped.")
+    return True
+
+
+def _get_live_clients(
+    con: Connection,
+    auth: AuthenticationClient,
+    creds: ServerCredentials,
+    shortcode: str,
+    imgdir: str,
+) -> UploadClients:
+    ingest_client: AssetClient
+    ingest_client = DspIngestClientLive(creds.dsp_ingest_url, auth, shortcode, imgdir)
+    project_client: ProjectClient = ProjectClientLive(auth.server, auth)
+    list_client: ListClient = ListClientLive(con, project_client.get_project_iri(shortcode))
+    legal_info_client: LegalInfoClient = LegalInfoClientLive(creds.server, shortcode, auth)
+    return UploadClients(
+        asset_client=ingest_client,
+        list_client=list_client,
+        legal_info_client=legal_info_client,
+    )
+
+
+def enable_unknown_license_if_any_are_missing(
+    legal_info_client: LegalInfoClient, parsed_resources: list[ParsedResource]
+) -> None:
+    all_license_infos = [x.file_value.metadata.license_iri for x in parsed_resources if x.file_value]
+    if not all(all_license_infos):
+        legal_info_client.enable_unknown_license()
+        msg = (
+            "The files or iiif-uris in your data are missing some legal information. "
+            "To facilitate an upload on a test environment we are adding dummy information.\n"
+            "In order to be able to use the license 'unknown' in place of missing licenses, "
+            "we are enabling it for your project."
+        )
+        print(BOLD_YELLOW, msg, RESET_TO_DEFAULT)
+
+
+def execute_upload(clients: UploadClients, upload_state: UploadState) -> bool:
+    """Execute an upload from an upload state, and clean up afterwards.
+
+    Args:
+        clients: the clients needed for the upload
+        upload_state: the initial state of the upload to execute
+
+    Returns:
+        True if all resources could be uploaded without errors; False if any resource could not be uploaded
+    """
+    logger.debug("Start uploading data")
+    db_metrics = None
+    if clients.legal_info_client.server == "http://0.0.0.0:3333":
+        db_metrics = FusekiMetrics()
+        db_metrics.try_get_start_size()
+    _upload_copyright_holders(upload_state.pending_resources, clients.legal_info_client)
+    _upload_resources(clients, upload_state)
+    if db_metrics is not None:
+        db_metrics.try_get_end_size()
+        communicate_fuseki_bloating(db_metrics)
+    return _cleanup_upload(upload_state)
+
+
+def _upload_copyright_holders(resources: list[ProcessedResource], legal_info_client: LegalInfoClient) -> None:
+    logger.debug("Get and upload copyright holders")
+    copyright_holders = _get_copyright_holders(resources)
+    legal_info_client.post_copyright_holders(copyright_holders)
+
+
+def _get_copyright_holders(resources: list[ProcessedResource]) -> list[str]:
+    copyright_holders = set()
+    for res in resources:
+        if res.file_value:
+            copyright_holders.add(res.file_value.metadata.copyright_holder)
+        elif res.iiif_uri:
+            copyright_holders.add(res.iiif_uri.metadata.copyright_holder)
+    return [x for x in copyright_holders if x]
+
+
+def _cleanup_upload(upload_state: UploadState) -> bool:
+    """
+    Write the id2iri mapping to a file and print a message to the console.
+
+    Args:
+        upload_state: the current state of the upload
+
+    Returns:
+        success status (deduced from failed_uploads and non-applied stash)
+    """
+    write_id2iri_mapping(
+        id2iri_mapping=upload_state.iri_resolver.lookup,
+        shortcode=upload_state.config.shortcode,
+        diagnostics=upload_state.config.diagnostics,
+    )
+    has_stash_failed = upload_state.pending_stash and not upload_state.pending_stash.is_empty()
+    if not upload_state.failed_uploads and not has_stash_failed:
+        success = True
+        print(f"{datetime.now()}: All resources have successfully been uploaded.")
+        logger.info("All resources have successfully been uploaded.")
+    else:
+        success = False
+        if upload_state.failed_uploads:
+            res_msg = f"Could not upload the following resources: {upload_state.failed_uploads}"
+            print(f"\n{datetime.now()}: WARNING: {res_msg}\n")
+            print(f"See {WARNINGS_SAVEPATH} for more information\n")
+            logger.warning(res_msg)
+        if has_stash_failed:
+            stash_msg = f"Could not reapply the following stash items: {upload_state.pending_stash}"
+            print(f"\n{datetime.now()}: WARNING: {stash_msg}\n")
+            print(f"See {WARNINGS_SAVEPATH} for more information\n")
+            logger.warning(stash_msg)
+        msg = _save_upload_state(upload_state)
+        print(msg)
+
+    upload_state.config.diagnostics.save_location.unlink(missing_ok=True)
+    return success
+
+
+def _upload_resources(clients: UploadClients, upload_state: UploadState) -> None:
+    """
+    Iterates through all resources and tries to upload them to DSP.
+    If a temporary exception occurs, the action is repeated until success,
+    and if a permanent exception occurs, the resource is skipped.
+
+    Args:
+        clients: the clients needed for the upload
+        upload_state: the current state of the upload
+
+    Raises:
+        BaseException: in case of an unhandled exception during resource creation
+        XmlUploadInterruptedError: if the number of resources created is equal to the interrupt_after value
+    """
+    project_iri = clients.list_client.project_iri
+
+    iri_lookup = IRILookups(
+        project_iri=URIRef(project_iri),
+        id_to_iri=upload_state.iri_resolver,
+    )
+
+    resource_create_client = ResourceCreateClient(
+        con=clients.list_client.con,
+    )
+    progress_bar = tqdm(upload_state.pending_resources.copy(), desc="Creating Resources", dynamic_ncols=True)
+    try:
+        for creation_attempts_of_this_round, resource in enumerate(progress_bar):
+            _upload_one_resource(
+                upload_state=upload_state,
+                resource=resource,
+                ingest_client=clients.asset_client,
+                resource_create_client=resource_create_client,
+                iri_lookups=iri_lookup,
+                creation_attempts_of_this_round=creation_attempts_of_this_round,
+            )
+            progress_bar.set_description(f"Creating Resources (failed: {len(upload_state.failed_uploads)})")
+        if upload_state.pending_stash:
+            _upload_stash(upload_state, clients.list_client.con)
+    except XmlUploadInterruptedError as err:
+        _handle_upload_error(err, upload_state)
+
+
+def _upload_stash(
+    upload_state: UploadState,
+    con: Connection,
+) -> None:
+    if upload_state.pending_stash and upload_state.pending_stash.standoff_stash:
+        upload_stashed_xml_texts(upload_state, con)
+    if upload_state.pending_stash and upload_state.pending_stash.link_value_stash:
+        upload_stashed_resptr_props(upload_state, con)
+
+
+def _upload_one_resource(
+    upload_state: UploadState,
+    resource: ProcessedResource,
+    ingest_client: AssetClient,
+    resource_create_client: ResourceCreateClient,
+    iri_lookups: IRILookups,
+    creation_attempts_of_this_round: int,
+) -> None:
+    media_info = None
+    if resource.file_value:
+        try:
+            ingest_result = ingest_client.get_bitstream_info(resource.file_value)
+        except PermanentConnectionError as err:
+            _handle_permanent_connection_error(err)
+        except KeyboardInterrupt:
+            _handle_keyboard_interrupt()
+        if not ingest_result:
+            upload_state.failed_uploads.append(resource.res_id)
+            return
+        media_info = ingest_result
+
+    iri = None
+    try:
+        serialised_resource = create_resource_with_values(
+            resource=resource, bitstream_information=media_info, lookups=iri_lookups
+        )
+        logger.info(f"Attempting to create resource {resource.res_id} (label: {resource.label})...")
+        iri = resource_create_client.create_resource(serialised_resource, resource_has_bitstream=bool(media_info))
+    except (PermanentTimeOutError, KeyboardInterrupt) as err:
+        _handle_permanent_timeout_or_keyboard_interrupt(err, resource.res_id)
+    except PermanentConnectionError as err:
+        _handle_permanent_connection_error(err)
+    except Exception as err:  # noqa: BLE001 (blind-except)
+        err_msg = err.message if isinstance(err, BaseError) else None
+        _inform_about_resource_creation_failure(resource, err_msg)
+
+    try:
+        _tidy_up_resource_creation_idempotent(upload_state, iri, resource)
+        _interrupt_if_indicated(upload_state, creation_attempts_of_this_round)
+    except KeyboardInterrupt:
+        _tidy_up_resource_creation_idempotent(upload_state, iri, resource)
+        _handle_keyboard_interrupt()
+
+
+def _handle_permanent_connection_error(err: PermanentConnectionError) -> Never:
+    msg = "Lost connection to DSP server, probably because the server is down. "
+    msg += f"Please continue later with 'resume-xmlupload'. Reason for this failure: {err.message}"
+    logger.error(msg)
+    msg += f"\nSee {WARNINGS_SAVEPATH} for more information."
+    raise XmlUploadInterruptedError(msg) from None
+
+
+def _handle_keyboard_interrupt() -> Never:
+    warnings.warn(DspToolsUserWarning("xmlupload manually interrupted. Tidying up, then exit..."))
+    msg = "xmlupload manually interrupted. Please continue later with 'resume-xmlupload'"
+    raise XmlUploadInterruptedError(msg) from None
+
+
+def _handle_permanent_timeout_or_keyboard_interrupt(
+    err: PermanentTimeOutError | KeyboardInterrupt, res_id: str
+) -> Never:
+    warnings.warn(DspToolsUserWarning(f"{type(err).__name__}: Tidying up, then exit..."))
+    msg = (
+        f"There was a {type(err).__name__} while trying to create resource '{res_id}'.\n"
+        f"It is unclear if the resource '{res_id}' was created successfully or not.\n"
+        f"Please check manually in the DSP-APP or DB.\n"
+        f"In case of successful creation, call 'resume-xmlupload' with the flag "
+        f"'--skip-first-resource' to prevent duplication.\n"
+        f"If not, a normal 'resume-xmlupload' can be started."
+    )
+    logger.error(msg)
+    raise XmlUploadInterruptedError(msg) from None
+
+
+def _interrupt_if_indicated(upload_state: UploadState, creation_attempts_of_this_round: int) -> None:
+    # if the interrupt_after value is not set, the upload will not be interrupted
+    interrupt_after = upload_state.config.interrupt_after or 999_999_999
+    if creation_attempts_of_this_round + 1 >= interrupt_after:
+        msg = f"Interrupted: Maximum number of resources was reached ({upload_state.config.interrupt_after})"
+        raise XmlUploadInterruptedError(msg)
+
+
+def _tidy_up_resource_creation_idempotent(
+    upload_state: UploadState,
+    iri: str | None,
+    resource: ProcessedResource,
+) -> None:
+    previous_successful = len(upload_state.iri_resolver.lookup)
+    previous_failed = len(upload_state.failed_uploads)
+    upcoming = len(upload_state.pending_resources)
+    current_res = previous_successful + previous_failed + 1
+    total_res = previous_successful + previous_failed + upcoming
+    if iri:
+        # resource creation succeeded: update the iri_resolver
+        upload_state.iri_resolver.lookup[resource.res_id] = iri
+        msg = f"Created resource {current_res}/{total_res}: '{resource.label}' (ID: '{resource.res_id}', IRI: '{iri}')"
+        logger.info(msg)
+    else:  # noqa: PLR5501
+        # resource creation failed gracefully: register it as failed
+        if resource.res_id not in upload_state.failed_uploads:
+            upload_state.failed_uploads.append(resource.res_id)
+
+    if resource in upload_state.pending_resources:
+        upload_state.pending_resources.remove(resource)
+
+
+def _inform_about_resource_creation_failure(resource: ProcessedResource, err_msg: str | None) -> None:
+    log_msg = f"Unable to create resource '{resource.label}' ({resource.res_id})\n"
+    if err_msg:
+        log_msg += err_msg
+    logger.exception(log_msg)
+
+
+def _handle_upload_error(err: BaseException, upload_state: UploadState) -> None:
+    """
+    In case the xmlupload must be interrupted,
+    e.g. because of an error that could not be handled,
+    or due to keyboard interrupt,
+    this method ensures
+    that all information about what is already in DSP
+    is written into diagnostic files.
+
+    It then quits the Python interpreter with exit code 1.
+
+    Args:
+        err: the error that was the cause of the abort
+        upload_state: the current state of the upload
+    """
+    if isinstance(err, XmlUploadInterruptedError):
+        msg = "\n==========================================\n" + err.message + "\n"
+        exit_code = 0
+    else:
+        msg = (
+            f"\n==========================================\n"
+            f"{datetime.now()}: xmlupload must be aborted because of an error.\n"
+            f"Error message: '{err}'\n"
+            f"See {WARNINGS_SAVEPATH} for more information\n"
+        )
+        exit_code = 1
+
+    msg += _save_upload_state(upload_state)
+
+    if failed := upload_state.failed_uploads:
+        msg += f"Independently from this, there were some resources that could not be uploaded: {failed}\n"
+
+    if exit_code == 1:
+        logger.error(msg)
+    else:
+        logger.info(msg)
+    print(msg)
+
+    sys.exit(exit_code)
+
+
+def _save_upload_state(upload_state: UploadState) -> str:
+    save_location = upload_state.config.diagnostics.save_location
+    save_location.unlink(missing_ok=True)
+    save_location.touch(exist_ok=True)
+    with open(save_location, "wb") as file:
+        pickle.dump(upload_state, file)
+    logger.info(f"Saved the current upload state to {save_location}")
+    return f"Saved the current upload state to {save_location}.\n"

dsp_tools/config/logger_config.py

@@ -0,0 +1,69 @@
+import os
+from datetime import datetime
+from pathlib import Path
+
+from dotenv import find_dotenv
+from dotenv import load_dotenv
+from loguru import logger
+
+load_dotenv(dotenv_path=find_dotenv(usecwd=True))
+
+
+def _make_and_get_logs_directory() -> Path:
+    """Get the base .dsp-tools directory, creating it if it doesn't exist."""
+    base_dir = Path.home() / ".dsp-tools" / "logs"
+    base_dir.mkdir(exist_ok=True, parents=True)
+    return base_dir
+
+
+timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S-%f")[:-3]
+
+LOGGER_SAVEPATH = (_make_and_get_logs_directory() / f"{timestamp}_logging.log").absolute()
+WARNINGS_SAVEPATH = Path("warnings.log")
+
+
+def logger_config() -> None:
+    """
+    This function configures the log files.
+    Currently, there are three sinks:
+    - timestamp_logging.log in ~/.dsp-tools/logs/ contains the entire stack-trace
+    - warnings.log in the cwd only with level warning and higher for the user (no stack-trace)
+      OR a complete logging.log file with the stack-trace if configured in the .env
+    - print output on the terminal, formatted the same as the warnings.log
+    """
+    # If this is not removed, the default formatting is also printed out on the terminal
+    logger.remove()
+
+    text_format = "<level>{time:YYYY-MM-DD HH:mm:ss.SSS} | {level: <8} | {message}</level>"
+    rotation_size = "100 MB"
+
+    logger.add(
+        sink=LOGGER_SAVEPATH,
+        format=text_format,
+        backtrace=True,
+        diagnose=True,
+        delay=True,
+    )
+
+    additional_log = str(os.getenv("DSP_TOOLS_SAVE_ADDITIONAL_LOG_FILE_IN_CWD"))
+    if additional_log.lower() == "true":
+        logger.add(
+            sink=Path("logging.log"),
+            format=text_format,
+            backtrace=True,
+            diagnose=True,
+            rotation=rotation_size,
+            retention=2,
+            delay=True,
+        )
+    else:
+        logger.add(
+            sink=WARNINGS_SAVEPATH,
+            level="WARNING",
+            format=text_format,
+            backtrace=False,
+            diagnose=False,
+            rotation=rotation_size,
+            retention=2,
+            delay=True,
+        )

dsp_tools/config/warnings_config.py

@@ -0,0 +1,32 @@
+import warnings
+from typing import TextIO
+
+from dsp_tools.error.custom_warnings import DspToolsWarning
+from dsp_tools.error.xmllib_warnings import XmllibUserInfoBase
+
+
+def initialize_warnings() -> None:
+    """
+    This function makes sure that DSP-TOOLS internal warnings are displayed in their custom way how they specify it.
+    This is done by monkeypatching the behavior of the warnings module, as officially recommended by the Python docs:
+    https://docs.python.org/3/library/warnings.html#warnings.showwarning
+    """
+
+    built_in_showwarning = warnings.showwarning
+
+    def _custom_showwarning(
+        message: Warning | str,
+        category: type[Warning],
+        filename: str,
+        lineno: int,
+        file: TextIO | None = None,
+        line: str | None = None,
+    ) -> None:
+        if issubclass(category, DspToolsWarning):
+            category.showwarning(str(message))
+        elif issubclass(category, XmllibUserInfoBase):
+            category.showwarning(str(message))
+        else:
+            built_in_showwarning(message, category, filename, lineno, file, line)
+
+    warnings.showwarning = _custom_showwarning

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)