Feature/error typology (#183)

* Exceptions

* Some tests, and make InvalidRequest compatible with no message

* QA

Author: EddyCMWF

cads_adaptors/adaptors/cadsobs/adaptor.py

@@ -4,6 +4,7 @@
 
 from cads_adaptors.adaptors.cadsobs.api_client import CadsobsApiClient
 from cads_adaptors.adaptors.cds import AbstractCdsAdaptor
+from cads_adaptors.exceptions import CadsObsRuntimeError
 
 logger = logging.getLogger(__name__)
 
@@ -119,7 +120,7 @@ def handle_sources_list(self, dataset_source: list | str) -> str:
                     "Asking for more than one observation_types in the same"
                     "request is currently unsupported."
                 )
-                raise RuntimeError(
+                raise CadsObsRuntimeError(
                     "Asking for more than one observation_types in the same"
                     "request is currently unsupported."
                 )

cads_adaptors/adaptors/cadsobs/retrieve.py

@@ -12,6 +12,7 @@
     _get_char_sizes,
     _get_output_path,
 )
+from cads_adaptors.exceptions import CadsObsRuntimeError
 
 logger = logging.getLogger(__name__)
 
@@ -51,7 +52,7 @@ def retrieve_data(
             )
         # Check if the resulting file is empty
         if len(oncobj.variables) == 0 or len(oncobj.variables["report_timestamp"]) == 0:
-            raise RuntimeError(
+            raise CadsObsRuntimeError(
                 "No data was found, try a different parameter combination."
             )
         # Add atributes

cads_adaptors/adaptors/cadsobs/utils.py

@@ -15,6 +15,7 @@
     RetrieveFormat,
     RetrieveParams,
 )
+from cads_adaptors.exceptions import CadsObsRuntimeError
 
 logger = logging.getLogger(__name__)
 MAX_NUMBER_OF_GROUPS = 10
@@ -197,7 +198,7 @@ def _get_param_name_in_data(retrieved_dataset: h5netcdf.File, param_name: str) -
             else:
                 param_name_in_data = f"{coord}|station_configuration"
         case _:
-            raise RuntimeError(f"Unknown parameter name {param_name}")
+            raise CadsObsRuntimeError(f"Unknown parameter name {param_name}")
     return param_name_in_data
 
 
@@ -332,7 +333,7 @@ def _get_code_mapping(
     elif isinstance(incobj, xarray.Dataset):
         attrs = incobj["observed_variable"].attrs
     else:
-        raise RuntimeError("Unsupported input type")
+        raise CadsObsRuntimeError("Unsupported input type")
     if inverse:
         mapping = {c: v for v, c in zip(attrs["labels"], attrs["codes"])}
     else:

cads_adaptors/adaptors/mars.py

@@ -2,6 +2,7 @@
 from typing import Any, BinaryIO, Union
 
 from cads_adaptors.adaptors import Context, Request, cds
+from cads_adaptors.exceptions import MarsNoDataError, MarsRuntimeError, MarsSystemError
 from cads_adaptors.tools import adaptor_tools
 from cads_adaptors.tools.date_tools import implement_embargo
 from cads_adaptors.tools.general import ensure_list, split_requests_on_keys
@@ -40,7 +41,7 @@ def get_mars_server_list(config) -> list[str]:
         with open(mars_server_list) as f:
             mars_servers = f.read().splitlines()
     else:
-        raise SystemError(
+        raise MarsSystemError(
             "MARS servers cannot be found, this is an error at the system level."
         )
     return mars_servers
@@ -94,7 +95,7 @@ def execute_mars(
         context.add_user_visible_error(message=error_message)
 
         error_message += f"Exception: {reply.error}\n"
-        raise RuntimeError(error_message)
+        raise MarsRuntimeError(error_message)
 
     if not os.path.getsize(target):
         error_message = (
@@ -104,7 +105,7 @@ def execute_mars(
         context.add_user_visible_error(
             message=error_message,
         )
-        raise RuntimeError(error_message)
+        raise MarsNoDataError(error_message)
 
     return target
 

cads_adaptors/adaptors/multi.py

@@ -3,6 +3,7 @@
 
 from cads_adaptors import AbstractCdsAdaptor, mapping
 from cads_adaptors.adaptors import Request
+from cads_adaptors.exceptions import MultiAdaptorNoDataError
 from cads_adaptors.tools.general import ensure_list
 
 
@@ -109,7 +110,7 @@ def retrieve(self, request: Request):
                 results += this_result
 
         if len(results) == 0:
-            raise RuntimeError(
+            raise MultiAdaptorNoDataError(
                 "MultiAdaptor returned no results, the error logs of the sub-adaptors is as follows:\n"
                 f"{exception_logs}"
             )

cads_adaptors/adaptors/roocs/__init__.py

@@ -4,6 +4,7 @@
 
 from cads_adaptors import mapping
 from cads_adaptors.adaptors.cds import AbstractCdsAdaptor, Request
+from cads_adaptors.exceptions import RoocsRuntimeError, RoocsValueError
 
 ROOK_URL = "http://compute.mips.copernicus-climate.eu/wps"
 
@@ -33,7 +34,7 @@ def retrieve(self, request: Request) -> BinaryIO:
         try:
             urls = response.download_urls()
         except Exception:
-            raise Exception(response.status)
+            raise RoocsRuntimeError(response.status)
         urls += [response.provenance(), response.provenance_image()]
 
         paths = url_tools.try_download(urls, context=self.context)
@@ -143,7 +144,7 @@ def find_facets(self, request):
                     matched_facets.append(raw_candidate)
 
         if not matched_facets:
-            raise ValueError(f"No data found for request {request}")
+            raise RoocsValueError(f"No data found for request {request}")
 
         # raise ValueError(str(raw_candidate) + " | " + str(self.facets_order))
         return [

cads_adaptors/adaptors/roocs/operators.py

@@ -2,6 +2,8 @@
 import types
 import typing as T
 
+from cads_adaptors.exceptions import RoocsValueError
+
 DEFAULT_DATE_FORMAT = "%Y-%m-%d"
 
 
@@ -141,7 +143,7 @@ def area(self):
                     extents = extents.split(delimiter)
                     break
             else:
-                raise ValueError(f"invalid area argument: {extents}")
+                raise RoocsValueError(f"invalid area argument: {extents}")
 
         # reorder extents from MARS-style (NWSE) to rooki-style (WSEN)
         extents_order = [1, 2, 3, 0]

cads_adaptors/exceptions.py

@@ -22,9 +22,43 @@ class ParameterError(TypeError):
 class InvalidRequest(Exception):
     """Raised when an invalid request is sent to the adaptor."""
 
-    def __init__(self, msgs):
+    def __init__(self, msgs: None | str | list[str] = None):
         if isinstance(msgs, str):
             msgs = [msgs]
-        super().__init__("\n".join(msgs))
 
-        self.messages = deepcopy(msgs)
+        if msgs is not None:
+            super().__init__("\n".join(msgs))
+
+            self.messages = deepcopy(msgs)
+
+
+class MarsRuntimeError(RuntimeError):
+    """Raised when a MARS request fails."""
+
+
+class MarsNoDataError(InvalidRequest):
+    """Raised when a MARS request returns no data."""
+
+
+class MarsSystemError(SystemError):
+    """Raised when a MARS request fails due to a system error."""
+
+
+class UrlNoDataError(InvalidRequest):
+    """Raised when a MARS request returns no data."""
+
+
+class MultiAdaptorNoDataError(InvalidRequest):
+    """Raised when a MultiAdaptor request returns no data."""
+
+
+class CadsObsRuntimeError(RuntimeError):
+    """Raised when a CADS-observation repository request fails."""
+
+
+class RoocsRuntimeError(RuntimeError):
+    """Raised when a ROOCS request fails."""
+
+
+class RoocsValueError(ValueError):
+    """Raised when a ROOCS request fails due to a value error."""

cads_adaptors/tools/url_tools.py

@@ -12,6 +12,7 @@
 from tqdm import tqdm
 
 from cads_adaptors.adaptors import Context
+from cads_adaptors.exceptions import InvalidRequest, UrlNoDataError
 from cads_adaptors.tools import hcube_tools
 
 
@@ -66,17 +67,18 @@ def try_download(urls: List[str], context: Context, **kwargs) -> List[str]:
     if len(paths) == 0:
         context.add_user_visible_error(
             "Your request has not found any data, please check your selection.\n"
-            "If you believe this to be a data store error, please contact user support."
+            "This may be due to temporary connectivity issues with the source data.\n"
+            "If this problem persists, please contact user support."
         )
-        raise RuntimeError(
+        raise UrlNoDataError(
             f"Request empty. No data found from the following URLs:"
             f"\n{yaml.safe_dump(urls, indent=2)} "
         )
     # TODO: raise a warning if len(paths)<len(urls). Need to check who sees this warning
     return paths
 
 
-# TODO use targzstream
+# TODO: remove unused function
 def download_zip_from_urls(
     urls: List[str],
     base_target: str,
@@ -94,7 +96,7 @@ def download_zip_from_urls(
     return target
 
 
-# TODO zipstream for archive creation
+# TODO: remove unused function
 def download_tgz_from_urls(
     urls: List[str],
     base_target: str,
@@ -112,27 +114,29 @@ def download_tgz_from_urls(
     return target
 
 
+# TODO: remove unused function
 def download_from_urls(
     urls: List[str],
     context: Context,
-    data_format: str = "zip",
+    download_format: str = "zip",
 ) -> str:
     base_target = str(hash(tuple(urls)))
 
-    if data_format == "tgz":
+    if download_format == "tgz":
         target = download_tgz_from_urls(
             urls=urls, base_target=base_target, context=context
         )
-    elif data_format == "zip":
+    elif download_format == "zip":
         target = download_zip_from_urls(
             urls=urls, base_target=base_target, context=context
         )
     else:
-        raise ValueError(f"{data_format=} is not supported")
+        raise InvalidRequest(f"Download format '{download_format}' is not supported")
 
     return target
 
 
+# TODO: remove unused function
 def download_zip_from_urls_in_memory(
     urls: List[str], target: Optional[str] = None
 ) -> str:

tests/test_05_exceptions.py

@@ -0,0 +1,21 @@
+import pytest
+
+from cads_adaptors import exceptions
+
+
+@pytest.mark.parametrize(
+    "test_exception",
+    [
+        exceptions.MarsNoDataError,
+        exceptions.MarsRuntimeError,
+        exceptions.MarsSystemError,
+        exceptions.MultiAdaptorNoDataError,
+        exceptions.UrlNoDataError,
+        exceptions.RoocsRuntimeError,
+        exceptions.RoocsValueError,
+        exceptions.CadsObsRuntimeError,
+    ],
+)
+def test_exceptions_raise_as_expected(test_exception) -> None:
+    with pytest.raises(test_exception):
+        raise test_exception