dsp-tools 17.0.0.post26__tar.gz → 18.0.0__tar.gz

{dsp_tools-17.0.0.post26 → dsp_tools-18.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dsp-tools
-Version: 17.0.0.post26
+Version: 18.0.0
 Summary: DSP-TOOLS is a Python package with a command line interface that helps you interact with a DaSCH service platform (DSP) server.
 Author: DaSCH - Swiss National Data and Service Center for the Humanities
 Author-email: DaSCH - Swiss National Data and Service Center for the Humanities <info@dasch.swiss>

{dsp_tools-17.0.0.post26 → dsp_tools-18.0.0}/pyproject.toml

@@ -2,7 +2,7 @@
 
 [project]
 name = "dsp-tools"
-version = "17.0.0.post26"
+version = "18.0.0"
 description = "DSP-TOOLS is a Python package with a command line interface that helps you interact with a DaSCH service platform (DSP) server."
 authors = [
     { name = "DaSCH - Swiss National Data and Service Center for the Humanities", email = "info@dasch.swiss" },
@@ -203,9 +203,5 @@ exclude = [
     "src/dsp_tools/error/xmllib_warnings_util.py",
     "src/dsp_tools/commands/excel2xml/",
     "test/",
-    # to enable small PRs the following files and directories are to be ignored until `create` is completely refactored
-    "src/dsp_tools/commands/create/",
-    "src/dsp_tools/clients/ontology_client_live.py",
-    "src/dsp_tools/clients/ontology_client.py",
 ]
 sort_by_size = true  # sort unused classes and functions by size 

{dsp_tools-17.0.0.post26 → dsp_tools-18.0.0}/src/dsp_tools/cli/args.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from dataclasses import field
 from enum import Enum
 from pathlib import Path
 
@@ -25,9 +26,22 @@ class ValidateDataConfig:
     ignore_duplicate_files_warning: bool
     is_on_prod_server: bool
     skip_ontology_validation: bool
+    do_not_request_resource_metadata_from_db: bool
 
 
 class ValidationSeverity(Enum):
     ERROR = 3
     WARNING = 2
     INFO = 1
+
+
+@dataclass
+class PathDependencies:
+    required_files: list[Path] = field(default_factory=list)
+    required_directories: list[Path] = field(default_factory=list)
+
+
+@dataclass
+class NetworkRequirements:
+    api_url: str
+    always_requires_docker: bool = False

dsp_tools-18.0.0/src/dsp_tools/cli/call_action.py

@@ -0,0 +1,82 @@
+import argparse
+
+from loguru import logger
+
+from dsp_tools.cli.call_action_files_only import call_excel2json
+from dsp_tools.cli.call_action_files_only import call_excel2lists
+from dsp_tools.cli.call_action_files_only import call_excel2properties
+from dsp_tools.cli.call_action_files_only import call_excel2resources
+from dsp_tools.cli.call_action_files_only import call_id2iri
+from dsp_tools.cli.call_action_files_only import call_old_excel2json
+from dsp_tools.cli.call_action_files_only import call_old_excel2lists
+from dsp_tools.cli.call_action_with_network import call_create
+from dsp_tools.cli.call_action_with_network import call_get
+from dsp_tools.cli.call_action_with_network import call_ingest_files
+from dsp_tools.cli.call_action_with_network import call_ingest_xmlupload
+from dsp_tools.cli.call_action_with_network import call_resume_xmlupload
+from dsp_tools.cli.call_action_with_network import call_start_stack
+from dsp_tools.cli.call_action_with_network import call_stop_stack
+from dsp_tools.cli.call_action_with_network import call_upload_files
+from dsp_tools.cli.call_action_with_network import call_validate_data
+from dsp_tools.cli.call_action_with_network import call_xmlupload
+
+
+def call_requested_action(args: argparse.Namespace) -> bool:  # noqa: PLR0912 (too many branches)
+    """
+    Call the appropriate function of DSP-TOOLS.
+
+    Args:
+        args: parsed CLI arguments
+
+    Raises:
+        BaseError: from the called function
+        InputError: from the called function
+        DockerNotReachableError: from the called function
+        LocalDspApiNotReachableError: from the called function
+        unexpected errors from the called methods and underlying libraries
+
+    Returns:
+        success status
+    """
+    match args.action:
+        # commands with Docker / API interactions
+        case "start-stack":
+            result = call_start_stack(args)
+        case "stop-stack":
+            result = call_stop_stack()
+        case "create":
+            result = call_create(args)
+        case "get":
+            result = call_get(args)
+        case "validate-data":
+            result = call_validate_data(args)
+        case "xmlupload":
+            result = call_xmlupload(args)
+        case "resume-xmlupload":
+            result = call_resume_xmlupload(args)
+        case "upload-files":
+            result = call_upload_files(args)
+        case "ingest-files":
+            result = call_ingest_files(args)
+        case "ingest-xmlupload":
+            result = call_ingest_xmlupload(args)
+        # commands that do not require docker
+        case "excel2json":
+            result = call_excel2json(args)
+        case "old-excel2json":
+            result = call_old_excel2json(args)
+        case "excel2lists":
+            result = call_excel2lists(args)
+        case "old-excel2lists":
+            result = call_old_excel2lists(args)
+        case "excel2resources":
+            result = call_excel2resources(args)
+        case "excel2properties":
+            result = call_excel2properties(args)
+        case "id2iri":
+            result = call_id2iri(args)
+        case _:
+            print(f"ERROR: Unknown action '{args.action}'")
+            logger.error(f"Unknown action '{args.action}'")
+            result = False
+    return result

dsp_tools-18.0.0/src/dsp_tools/cli/call_action_files_only.py

@@ -0,0 +1,74 @@
+import argparse
+from pathlib import Path
+
+from dsp_tools.cli.args import PathDependencies
+from dsp_tools.cli.utils import check_path_dependencies
+from dsp_tools.commands.excel2json.lists.make_lists import excel2lists
+from dsp_tools.commands.excel2json.old_lists import old_excel2lists
+from dsp_tools.commands.excel2json.project import excel2json
+from dsp_tools.commands.excel2json.project import old_excel2json
+from dsp_tools.commands.excel2json.properties import excel2properties
+from dsp_tools.commands.excel2json.resources import excel2resources
+from dsp_tools.commands.id2iri import id2iri
+
+
+def call_id2iri(args: argparse.Namespace) -> bool:
+    check_path_dependencies(PathDependencies([Path(args.xmlfile), Path(args.mapping)]))
+    return id2iri(
+        xml_file=args.xmlfile,
+        json_file=args.mapping,
+        remove_resource_if_id_in_mapping=args.remove_resources,
+    )
+
+
+def call_excel2properties(args: argparse.Namespace) -> bool:
+    check_path_dependencies(PathDependencies([Path(args.excelfile)]))
+    _, _, success = excel2properties(
+        excelfile=args.excelfile,
+        path_to_output_file=args.properties_section,
+    )
+    return success
+
+
+def call_excel2resources(args: argparse.Namespace) -> bool:
+    check_path_dependencies(PathDependencies([Path(args.excelfile)]))
+    _, _, success = excel2resources(
+        excelfile=args.excelfile,
+        path_to_output_file=args.resources_section,
+    )
+    return success
+
+
+def call_old_excel2lists(args: argparse.Namespace) -> bool:
+    check_path_dependencies(PathDependencies(required_directories=[Path(args.excelfolder)]))
+    _, success = old_excel2lists(
+        excelfolder=args.excelfolder,
+        path_to_output_file=args.lists_section,
+        verbose=args.verbose,
+    )
+    return success
+
+
+def call_excel2lists(args: argparse.Namespace) -> bool:
+    check_path_dependencies(PathDependencies(required_directories=[Path(args.excelfolder)]))
+    _, success = excel2lists(
+        excelfolder=args.excelfolder,
+        path_to_output_file=args.lists_section,
+    )
+    return success
+
+
+def call_excel2json(args: argparse.Namespace) -> bool:
+    check_path_dependencies(PathDependencies(required_directories=[Path(args.excelfolder)]))
+    return excel2json(
+        data_model_files=args.excelfolder,
+        path_to_output_file=args.project_definition,
+    )
+
+
+def call_old_excel2json(args: argparse.Namespace) -> bool:
+    check_path_dependencies(PathDependencies(required_directories=[Path(args.excelfolder)]))
+    return old_excel2json(
+        data_model_files=args.excelfolder,
+        path_to_output_file=args.project_definition,
+    )

dsp_tools-18.0.0/src/dsp_tools/cli/call_action_with_network.py

@@ -0,0 +1,203 @@
+import argparse
+from pathlib import Path
+
+from dsp_tools.cli.args import NetworkRequirements
+from dsp_tools.cli.args import PathDependencies
+from dsp_tools.cli.args import ValidationSeverity
+from dsp_tools.cli.utils import check_docker_health
+from dsp_tools.cli.utils import check_input_dependencies
+from dsp_tools.cli.utils import check_network_health
+from dsp_tools.cli.utils import get_creds
+from dsp_tools.commands.create.lists_only import create_lists_only
+from dsp_tools.commands.excel2json.old_lists import validate_lists_section_with_schema
+from dsp_tools.commands.ingest_xmlupload.create_resources.upload_xml import ingest_xmlupload
+from dsp_tools.commands.ingest_xmlupload.ingest_files.ingest_files import ingest_files
+from dsp_tools.commands.ingest_xmlupload.upload_files.upload_files import upload_files
+from dsp_tools.commands.project.create.project_create_all import create_project
+from dsp_tools.commands.project.create.project_validate import validate_project
+from dsp_tools.commands.project.get.get import get_project
+from dsp_tools.commands.resume_xmlupload.resume_xmlupload import resume_xmlupload
+from dsp_tools.commands.start_stack import StackConfiguration
+from dsp_tools.commands.start_stack import StackHandler
+from dsp_tools.commands.validate_data.validate_data import validate_data
+from dsp_tools.commands.xmlupload.upload_config import UploadConfig
+from dsp_tools.commands.xmlupload.xmlupload import xmlupload
+from dsp_tools.error.exceptions import InputError
+from dsp_tools.utils.xml_parsing.parse_clean_validate_xml import parse_and_validate_xml_file
+
+
+def call_start_stack(args: argparse.Namespace) -> bool:
+    check_docker_health()
+    stack_handler = StackHandler(
+        StackConfiguration(
+            max_file_size=args.max_file_size,
+            enforce_docker_system_prune=args.prune,
+            suppress_docker_system_prune=args.no_prune,
+            latest_dev_version=args.latest,
+            upload_test_data=args.with_test_data,
+            custom_host=args.custom_host,
+        )
+    )
+    return stack_handler.start_stack()
+
+
+def call_stop_stack() -> bool:
+    check_docker_health()
+    stack_handler = StackHandler(StackConfiguration())
+    return stack_handler.stop_stack()
+
+
+def call_upload_files(args: argparse.Namespace) -> bool:
+    xml_path = Path(args.xml_file)
+    image_dir = Path(args.imgdir)
+    network_requirements = NetworkRequirements(api_url=args.server)
+    path_requirements = PathDependencies([xml_path], required_directories=[image_dir])
+    check_input_dependencies(path_requirements, network_requirements)
+
+    return upload_files(
+        xml_file=xml_path,
+        creds=get_creds(args),
+        imgdir=image_dir,
+    )
+
+
+def call_ingest_files(args: argparse.Namespace) -> bool:
+    check_network_health(NetworkRequirements(api_url=args.server))
+    return ingest_files(creds=get_creds(args), shortcode=args.shortcode)
+
+
+def call_ingest_xmlupload(args: argparse.Namespace) -> bool:
+    xml_path = Path(args.xml_file)
+    required_files = [xml_path]
+    id2iri_file = args.id2iri_replacement_with_file
+    if id2iri_file:
+        required_files.append(Path(id2iri_file))
+    network_requirements = NetworkRequirements(args.server, always_requires_docker=True)
+    path_deps = PathDependencies(required_files)
+    check_input_dependencies(path_deps, network_requirements)
+
+    interrupt_after = args.interrupt_after if args.interrupt_after > 0 else None
+    return ingest_xmlupload(
+        xml_file=xml_path,
+        creds=get_creds(args),
+        interrupt_after=interrupt_after,
+        skip_validation=args.skip_validation,
+        skip_ontology_validation=args.skip_ontology_validation,
+        id2iri_replacement_file=id2iri_file,
+        do_not_request_resource_metadata_from_db=args.do_not_request_resource_metadata_from_db,
+    )
+
+
+def call_xmlupload(args: argparse.Namespace) -> bool:
+    xml_path = Path(args.xmlfile)
+    required_files = [xml_path]
+    id2iri_file = args.id2iri_replacement_with_file
+    if id2iri_file:
+        required_files.append(Path(id2iri_file))
+    network_requirements = NetworkRequirements(args.server, always_requires_docker=True)
+    path_deps = PathDependencies(required_files, [Path(args.imgdir)])
+    check_input_dependencies(path_deps, network_requirements)
+
+    if args.validate_only:
+        success = parse_and_validate_xml_file(xml_path)
+        print("The XML file is syntactically correct.")
+        return success
+    else:
+        interrupt_after = args.interrupt_after if args.interrupt_after > 0 else None
+        match args.validation_severity:
+            case "info":
+                severity = ValidationSeverity.INFO
+            case "warning":
+                severity = ValidationSeverity.WARNING
+            case "error":
+                severity = ValidationSeverity.ERROR
+            case _:
+                raise InputError(
+                    f"The entered validation severity '{args.validation_severity}' "
+                    f"is not part of the allowed values: info, warning, error."
+                )
+        return xmlupload(
+            input_file=xml_path,
+            creds=get_creds(args),
+            imgdir=args.imgdir,
+            config=UploadConfig(
+                interrupt_after=interrupt_after,
+                skip_iiif_validation=args.no_iiif_uri_validation,
+                skip_validation=args.skip_validation,
+                ignore_duplicate_files_warning=args.ignore_duplicate_files_warning,
+                validation_severity=severity,
+                skip_ontology_validation=args.skip_ontology_validation,
+                do_not_request_resource_metadata_from_db=args.do_not_request_resource_metadata_from_db,
+                id2iri_replacement_file=id2iri_file,
+            ),
+        )
+
+
+def call_validate_data(args: argparse.Namespace) -> bool:
+    xml_path = Path(args.xmlfile)
+    required_files = [xml_path]
+    id2iri_file = args.id2iri_replacement_with_file
+    if id2iri_file:
+        required_files.append(Path(id2iri_file))
+    network_requirements = NetworkRequirements(args.server, always_requires_docker=True)
+    path_deps = PathDependencies(required_files)
+    check_input_dependencies(path_deps, network_requirements)
+
+    return validate_data(
+        filepath=xml_path,
+        creds=get_creds(args),
+        save_graphs=args.save_graphs,
+        ignore_duplicate_files_warning=args.ignore_duplicate_files_warning,
+        skip_ontology_validation=args.skip_ontology_validation,
+        id2iri_replacement_file=id2iri_file,
+        do_not_request_resource_metadata_from_db=args.do_not_request_resource_metadata_from_db,
+    )
+
+
+def call_resume_xmlupload(args: argparse.Namespace) -> bool:
+    # this does not need docker if not on localhost, as does not need to validate
+    check_network_health(NetworkRequirements(args.server))
+    return resume_xmlupload(
+        creds=get_creds(args),
+        skip_first_resource=args.skip_first_resource,
+    )
+
+
+def call_get(args: argparse.Namespace) -> bool:
+    network_dependencies = NetworkRequirements(args.server)
+    path_dependencies = PathDependencies(required_directories=[Path(args.project_definition).parent])
+    check_input_dependencies(path_dependencies, network_dependencies)
+
+    return get_project(
+        project_identifier=args.project,
+        outfile_path=args.project_definition,
+        creds=get_creds(args),
+        verbose=args.verbose,
+    )
+
+
+def call_create(args: argparse.Namespace) -> bool:
+    network_dependencies = NetworkRequirements(args.server)
+    path_dependencies = PathDependencies([Path(args.project_definition)])
+    check_input_dependencies(path_dependencies, network_dependencies)
+
+    success = False
+    match args.lists_only, args.validate_only:
+        case True, True:
+            success = validate_lists_section_with_schema(args.project_definition)
+            print("'Lists' section of the JSON project file is syntactically correct and passed validation.")
+        case True, False:
+            success = create_lists_only(
+                project_file_as_path_or_parsed=args.project_definition,
+                creds=get_creds(args),
+            )
+        case False, True:
+            success = validate_project(args.project_definition)
+            print("JSON project file is syntactically correct and passed validation.")
+        case False, False:
+            success = create_project(
+                project_file_as_path_or_parsed=args.project_definition,
+                creds=get_creds(args),
+                verbose=args.verbose,
+            )
+    return success

{dsp_tools-17.0.0.post26 → dsp_tools-18.0.0}/src/dsp_tools/cli/create_parsers.py

@@ -96,7 +96,7 @@ def _add_start_stack(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     max_file_size_text = "max. multimedia file size allowed for ingest, in MB (default: 2000, max: 100'000)"
     no_prune_text = "don't execute 'docker system prune' (and don't ask)"
     with_test_data_text = "initialise the database with built-in test data"
-    custom_host = "set host to use stack on a server"
+    custom_host = "set a host to an IP or a domain to run the instance on a server"
     subparser = subparsers.add_parser(name="start-stack", help="Run a local instance of DSP-API and DSP-APP")
     subparser.set_defaults(action="start-stack")
     subparser.add_argument("--max_file_size", type=int, help=max_file_size_text)
@@ -237,10 +237,27 @@ def _add_ingest_xmlupload(
     subparser.add_argument("--interrupt-after", type=int, default=-1, help="interrupt after this number of resources")
     subparser.add_argument("xml_file", help="path to XML file containing the data")
     subparser.add_argument("--skip-validation", action="store_true", help="Skip the SHACL schema validation")
-    subparser.add_argument("--skip-ontology-validation", action="store_true", help="skip the ontology validation")
+    subparser.add_argument(
+        "--skip-ontology-validation",
+        action="store_true",
+        help=(
+            "don't validate the ontology itself, only the data. "
+            "This is intended for projects that are already on the production server"
+        ),
+    )
     subparser.add_argument(
         "--id2iri-replacement-with-file",
-        help="replaces internal IDs of an XML file by IRIs provided in this mapping file",
+        help=(
+            "replaces internal IDs of an XML file (links and stand-off links inside richtext) "
+            "by IRIs provided in this mapping file"
+        ),
+    )
+    subparser.add_argument(
+        "--do-not-request-resource-metadata-from-db",
+        action="store_true",
+        help=(
+            "Do not request IRIs of existing resources from the db (references to existing resources won't be checked)"
+        ),
     )
 
 
@@ -261,13 +278,24 @@ def _add_xmlupload(
         "-i", "--imgdir", default=".", help="folder from where the paths in the <bitstream> tags are evaluated"
     )
     subparser.add_argument(
-        "-V", "--validate-only", action="store_true", help="validate the XML file without uploading it"
+        "-V", "--validate-only", action="store_true", help="run the XML Schema validation without uploading the XML"
     )
     subparser.add_argument("--skip-validation", action="store_true", help="Skip the SHACL schema validation")
-    subparser.add_argument("--skip-ontology-validation", action="store_true", help="skip the ontology validation")
+    subparser.add_argument(
+        "--skip-ontology-validation",
+        action="store_true",
+        help=(
+            "don't validate the ontology itself, only the data. "
+            "This is intended for projects that are already on the production server"
+        ),
+    )
     subparser.add_argument("--interrupt-after", type=int, default=-1, help="interrupt after this number of resources")
     subparser.add_argument("xmlfile", help="path to the XML file containing the data")
-    subparser.add_argument("--no-iiif-uri-validation", action="store_true", help="skip the IIIF URI validation")
+    subparser.add_argument(
+        "--no-iiif-uri-validation",
+        action="store_true",
+        help="don't check if the IIIF links are valid URLs that can be reached online",
+    )
     subparser.add_argument(
         "--ignore-duplicate-files-warning",
         action="store_true",
@@ -276,12 +304,25 @@ def _add_xmlupload(
     subparser.add_argument(
         "--validation-severity",
         choices=["error", "warning", "info"],
-        help="Which severity level of validation message should be printed out",
+        help=(
+            "Which severity level of validation message should be printed out. "
+            "Each level of severity includes the higher levels."
+        ),
         default="info",
     )
+    subparser.add_argument(
+        "--do-not-request-resource-metadata-from-db",
+        action="store_true",
+        help=(
+            "Do not request IRIs of existing resources from the db (references to existing resources won't be checked)"
+        ),
+    )
     subparser.add_argument(
         "--id2iri-replacement-with-file",
-        help="replaces internal IDs of an XML file by IRIs provided in this mapping file",
+        help=(
+            "replaces internal IDs of an XML file (links and stand-off links inside richtext) "
+            "by IRIs provided in this mapping file"
+        ),
     )
 
 
@@ -301,16 +342,35 @@ def _add_validate_data(
         action="store_true",
         help="don't check if multimedia files are referenced more than once",
     )
-    subparser.add_argument("--skip-ontology-validation", action="store_true", help="skip the ontology validation")
+    subparser.add_argument(
+        "--skip-ontology-validation",
+        action="store_true",
+        help=(
+            "don't validate the ontology itself, only the data. "
+            "This is intended for projects that are already on the production server"
+        ),
+    )
     subparser.add_argument(
         "-s", "--server", default=default_dsp_api_url, help="URL of the DSP server where DSP-TOOLS sends the data to"
     )
     subparser.add_argument(
         "--id2iri-replacement-with-file",
-        help="replaces internal IDs of an XML file by IRIs provided in this mapping file",
+        help=(
+            "replaces internal IDs of an XML file (links and stand-off links inside richtext) "
+            "by IRIs provided in this mapping file"
+        ),
     )
     subparser.add_argument(
-        "--save-graphs", action="store_true", help="Save the data, onto and shacl graph as ttl files."
+        "--do-not-request-resource-metadata-from-db",
+        action="store_true",
+        help=(
+            "Do not request IRIs of existing resources from the db (references to existing resources won't be checked)"
+        ),
+    )
+    subparser.add_argument(
+        "--save-graphs",
+        action="store_true",
+        help="Save the data, onto and shacl graph as ttl files. This is primarily intended for development use.",
     )
 
 

dsp_tools-18.0.0/src/dsp_tools/cli/utils.py

@@ -0,0 +1,87 @@
+import argparse
+import subprocess
+from pathlib import Path
+
+import requests
+from loguru import logger
+
+from dsp_tools.cli.args import NetworkRequirements
+from dsp_tools.cli.args import PathDependencies
+from dsp_tools.cli.args import ServerCredentials
+from dsp_tools.error.exceptions import DockerNotReachableError
+from dsp_tools.error.exceptions import DspApiNotReachableError
+from dsp_tools.error.exceptions import UserDirectoryNotFoundError
+from dsp_tools.error.exceptions import UserFilepathNotFoundError
+
+LOCALHOST_API = "http://0.0.0.0:3333"
+
+
+def get_creds(args: argparse.Namespace) -> ServerCredentials:
+    return ServerCredentials(
+        server=args.server,
+        user=args.user,
+        password=args.password,
+        dsp_ingest_url=args.dsp_ingest_url,
+    )
+
+
+def check_input_dependencies(
+    paths: PathDependencies | None = None, network_dependencies: NetworkRequirements | None = None
+) -> None:
+    if paths:
+        check_path_dependencies(paths)
+    if network_dependencies:
+        check_network_health(network_dependencies)
+
+
+def check_path_dependencies(paths: PathDependencies) -> None:
+    for f_path in paths.required_files:
+        _check_filepath_exists(f_path)
+    for dir_path in paths.required_directories:
+        _check_directory_exists(dir_path)
+
+
+def _check_filepath_exists(file_path: Path) -> None:
+    if not file_path.exists():
+        raise UserFilepathNotFoundError(file_path)
+
+
+def _check_directory_exists(dir_path: Path) -> None:
+    if not dir_path.is_dir():
+        raise UserDirectoryNotFoundError(dir_path)
+
+
+def check_network_health(network_requirements: NetworkRequirements) -> None:
+    if network_requirements.api_url == LOCALHOST_API or network_requirements.always_requires_docker:
+        check_docker_health()
+    _check_api_health(network_requirements.api_url)
+
+
+def check_docker_health() -> None:
+    if subprocess.run("docker stats --no-stream".split(), check=False, capture_output=True).returncode != 0:
+        raise DockerNotReachableError()
+
+
+def _check_api_health(api_url: str) -> None:
+    health_url = f"{api_url}/health"
+    msg = (
+        "The DSP-API could not be reached. Please check if your stack is healthy "
+        "or start a stack with 'dsp-tools start-stack' if none is running."
+    )
+    try:
+        response = requests.get(health_url, timeout=2)
+        if not response.ok:
+            if api_url != LOCALHOST_API:
+                msg = (
+                    f"The DSP-API could not be reached (returned status {response.status_code}). "
+                    f"Please contact the DaSCH engineering team for help."
+                )
+            logger.error(msg)
+            raise DspApiNotReachableError(msg)
+        logger.debug(f"DSP API health check passed: {health_url}")
+    except requests.exceptions.RequestException as e:
+        logger.error(e)
+        if api_url != LOCALHOST_API:
+            msg = "The DSP-API responded with a request exception. Please contact the DaSCH engineering team for help."
+        logger.error(msg)
+        raise DspApiNotReachableError(msg) from None