⬆️ update error mgmt (#181)

Author: sebastianMindee

mindee/cli.py

@@ -5,6 +5,7 @@
 
 from mindee import product
 from mindee.client import Client, Endpoint
+from mindee.error.mindee_error import MindeeClientError
 from mindee.input.page_options import PageOptions
 from mindee.input.sources import LocalInputSource, UrlInputSource
 from mindee.parsing.common.async_predict_response import AsyncPredictResponse
@@ -188,7 +189,7 @@ def call_feedback(self) -> None:
                 self.parsed_args.api_version,
             )
         if self.feedback is None:
-            raise RuntimeError("Invalid feedback provided.")
+            raise MindeeClientError("Invalid feedback provided.")
 
         response: FeedbackResponse = self.client.send_feedback(
             self.document_info.doc_class,
@@ -222,7 +223,7 @@ def call_parse(self) -> None:
             print(response.raw_http)
         else:
             if response.document is None:
-                raise RuntimeError("Something went wrong during async parsing.")
+                raise MindeeClientError("Something went wrong during async parsing.")
             print(self._doc_str(self.parsed_args.output_type, response.document))
 
     def _parse_sync(self) -> PredictResponse:
@@ -471,9 +472,9 @@ def _get_feedback_doc(self) -> StringDict:
                 not self.parsed_args.feedback
                 or not "feedback" in self.parsed_args.feedback
             ):
-                raise RuntimeError("Invalid feedback.")
+                raise MindeeClientError("Invalid feedback.")
         if not json_doc or "feedback" not in json_doc:
-            raise RuntimeError("Invalid feedback.")
+            raise MindeeClientError("Invalid feedback.")
         return json_doc
 
     def _set_input(self) -> None:

mindee/client.py

@@ -2,6 +2,8 @@
 from time import sleep
 from typing import BinaryIO, Dict, Optional, Type, Union
 
+from mindee.error.mindee_error import MindeeClientError, MindeeError
+from mindee.error.mindee_http_error import handle_error
 from mindee.input.page_options import PageOptions
 from mindee.input.sources import (
     Base64Input,
@@ -13,7 +15,6 @@
 )
 from mindee.logger import logger
 from mindee.mindee_http.endpoint import CustomEndpoint, Endpoint
-from mindee.mindee_http.error import handle_error
 from mindee.mindee_http.mindee_api import MindeeApi
 from mindee.parsing.common.async_predict_response import AsyncPredictResponse
 from mindee.parsing.common.feedback_response import FeedbackResponse
@@ -96,7 +97,7 @@ def parse(
         :param endpoint: For custom endpoints, an endpoint has to be given.
         """
         if input_source is None:
-            raise TypeError("No input document provided.")
+            raise MindeeClientError("No input document provided.")
 
         if not endpoint:
             endpoint = self._initialize_ots_endpoint(product_class)
@@ -148,7 +149,7 @@ def enqueue(
         :param endpoint: For custom endpoints, an endpoint has to be given.
         """
         if input_source is None:
-            raise TypeError("No input document provided.")
+            raise MindeeClientError("No input document provided.")
 
         if not endpoint:
             endpoint = self._initialize_ots_endpoint(product_class)
@@ -191,9 +192,13 @@ def _validate_async_params(
         self, initial_delay_sec: float, delay_sec: float
     ) -> None:
         if delay_sec < 2:
-            raise TypeError("Cannot set auto-parsing delay to less than 2 seconds.")
+            raise MindeeClientError(
+                "Cannot set auto-parsing delay to less than 2 seconds."
+            )
         if initial_delay_sec < 4:
-            raise TypeError("Cannot set initial parsing delay to less than 4 seconds.")
+            raise MindeeClientError(
+                "Cannot set initial parsing delay to less than 4 seconds."
+            )
 
     def enqueue_and_parse(
         self,
@@ -271,7 +276,7 @@ def enqueue_and_parse(
             )
 
         if poll_results.job.status != "completed":
-            raise RuntimeError(
+            raise MindeeError(
                 f"Couldn't retrieve document after {retry_counter} tries."
             )
 
@@ -295,7 +300,7 @@ def send_feedback(
         :param endpoint: For custom endpoints, an endpoint has to be given.
         """
         if not document_id or len(document_id) == 0:
-            raise RuntimeError("Invalid document_id.")
+            raise MindeeClientError("Invalid document_id.")
         if not endpoint:
             endpoint = self._initialize_ots_endpoint(product_class)
 
@@ -348,7 +353,7 @@ def _predict_async(
         :param doc_config: Configuration of the document.
         """
         if input_source is None:
-            raise TypeError("No input document provided")
+            raise MindeeClientError("No input document provided")
         if not endpoint:
             endpoint = self._initialize_ots_endpoint(product_class)
         response = endpoint.predict_async_req_post(
@@ -396,7 +401,7 @@ def _get_queued_document(
 
     def _initialize_ots_endpoint(self, product_class: Type[Inference]) -> Endpoint:
         if product_class.__name__ == "CustomV1":
-            raise TypeError("Missing endpoint specifications for custom build.")
+            raise MindeeClientError("Missing endpoint specifications for custom build.")
         endpoint_info: Dict[str, str] = product_class.get_endpoint_info(product_class)
         return self._build_endpoint(
             endpoint_info["name"], OTS_OWNER, endpoint_info["version"]
@@ -432,7 +437,7 @@ def create_endpoint(
             Must inherit from ``mindee.product.base.Document``.
         """
         if len(endpoint_name) == 0:
-            raise TypeError("Custom endpoint require a valid 'endpoint_name'.")
+            raise MindeeClientError("Custom endpoint require a valid 'endpoint_name'.")
         account_name = _clean_account_name(account_name)
         if not version or len(version) < 1:
             logger.debug(

mindee/error/__init__.py

@@ -0,0 +1,6 @@
+from mindee.error.mindee_error import MindeeClientError, MindeeError
+from mindee.error.mindee_http_error import (
+    MindeeHTTPClientError,
+    MindeeHTTPError,
+    MindeeHTTPServerError,
+)

mindee/error/mindee_error.py

@@ -0,0 +1,14 @@
+class MindeeError(RuntimeError):
+    """A generic exception relating to various client errors."""
+
+
+class MindeeClientError(MindeeError):
+    """An exception relating to document parsing."""
+
+
+class MindeeApiError(MindeeError):
+    """An exception relating to settings of the MindeeClient."""
+
+
+class MindeeSourceError(MindeeError):
+    """An exception relating to document loading."""

mindee/mindee_http/error.py renamed to mindee/error/mindee_http_error.py

@@ -1,9 +1,10 @@
 from typing import Union
 
+from mindee.error.mindee_error import MindeeError
 from mindee.parsing.common.string_dict import StringDict
 
 
-class MindeeHTTPException(RuntimeError):
+class MindeeHTTPError(RuntimeError):
     """An exception relating to HTTP calls."""
 
     status_code: int
@@ -28,14 +29,6 @@ def __init__(self, http_error: StringDict, url: str, code: int) -> None:
         )
 
 
-class MindeeHTTPClientException(MindeeHTTPException):
-    """API Client HTTP exception."""
-
-
-class MindeeHTTPServerException(MindeeHTTPException):
-    """API Server HTTP exception."""
-
-
 def create_error_obj(response: Union[StringDict, str]) -> StringDict:
     """
     Creates an error object based on a requests' payload.
@@ -46,7 +39,7 @@ def create_error_obj(response: Union[StringDict, str]) -> StringDict:
     if not isinstance(response, str):
         if "api_request" in response and "error" in response["api_request"]:
             return response["api_request"]["error"]
-        raise RuntimeError(f"Could not build specific HTTP exception from '{response}'")
+        raise MindeeError(f"Could not build specific HTTP exception from '{response}'")
     error_dict = {}
     if "Maximum pdf pages" in response:
         error_dict = {
@@ -87,7 +80,15 @@ def create_error_obj(response: Union[StringDict, str]) -> StringDict:
     return error_dict
 
 
-def handle_error(url: str, response: StringDict, code: int) -> MindeeHTTPException:
+class MindeeHTTPClientError(MindeeHTTPError):
+    """API Client HTTP exception."""
+
+
+class MindeeHTTPServerError(MindeeHTTPError):
+    """API Server HTTP exception."""
+
+
+def handle_error(url: str, response: StringDict, code: int) -> MindeeHTTPError:
     """
     Creates an appropriate HTTP error exception, based on retrieved HTTP error code.
 
@@ -96,7 +97,7 @@ def handle_error(url: str, response: StringDict, code: int) -> MindeeHTTPExcepti
     """
     error_obj = create_error_obj(response)
     if 400 <= code <= 499:
-        return MindeeHTTPClientException(error_obj, url, code)
+        return MindeeHTTPClientError(error_obj, url, code)
     if 500 <= code <= 599:
-        return MindeeHTTPServerException(error_obj, url, code)
-    return MindeeHTTPException(error_obj, url, code)
+        return MindeeHTTPServerError(error_obj, url, code)
+    return MindeeHTTPError(error_obj, url, code)

mindee/input/sources.py

@@ -8,6 +8,7 @@
 
 import pikepdf
 
+from mindee.error.mindee_error import MindeeSourceError
 from mindee.input.page_options import KEEP_ONLY, REMOVE
 from mindee.logger import logger
 
@@ -90,7 +91,7 @@ def process_pdf(
     ) -> None:
         """Run any required processing on a PDF file."""
         if self.is_pdf_empty():
-            raise AssertionError(f"PDF pages are empty in: {self.filename}")
+            raise MindeeSourceError(f"PDF pages are empty in: {self.filename}")
         pages_count = self.count_doc_pages()
         if on_min_pages > pages_count:
             return
@@ -111,10 +112,10 @@ def process_pdf(
                     logger.warning("Page index not in source document: %s", page_id)
             pages_to_keep = pages_to_remove.symmetric_difference(set(all_pages))
         else:
-            raise AssertionError(f"Invalid cut behavior specified: {behavior}")
+            raise MindeeSourceError(f"Invalid cut behavior specified: {behavior}")
 
         if len(pages_to_keep) < 1:
-            raise RuntimeError("Resulting PDF would have no pages left.")
+            raise MindeeSourceError("Resulting PDF would have no pages left.")
         self.merge_pdf_pages(pages_to_keep)
 
     def merge_pdf_pages(self, page_numbers: set) -> None:
@@ -260,7 +261,7 @@ def __init__(self, url: str) -> None:
         :param url: URL to send, must be HTTPS
         """
         if not url.lower().startswith("https"):
-            raise AssertionError("URL must be HTTPS")
+            raise MindeeSourceError("URL must be HTTPS")
 
         self.input_type = InputType.URL
 

mindee/mindee_http/mindee_api.py

@@ -2,6 +2,7 @@
 from dataclasses import dataclass
 from typing import Dict, Optional, Union
 
+from mindee.error.mindee_error import MindeeApiError
 from mindee.logger import logger
 from mindee.versions import __version__, get_platform, python_version
 
@@ -36,7 +37,7 @@ def __init__(
     ):
         self._set_api_key(api_key)
         if not self.api_key or len(self.api_key) == 0:
-            raise RuntimeError(
+            raise MindeeApiError(
                 (
                     f"Missing API key for '{endpoint_name} v{version}' (belonging to {account_name}),"
                     " check your Client configuration.\n"

mindee/parsing/common/inference.py

@@ -1,5 +1,6 @@
 from typing import Dict, Generic, List, Optional, TypeVar
 
+from mindee.error.mindee_error import MindeeError
 from mindee.parsing.common.page import TypePage
 from mindee.parsing.common.prediction import TypePrediction
 from mindee.parsing.common.product import Product
@@ -62,7 +63,7 @@ def get_endpoint_info(klass) -> Dict[str, str]:
         """
         if klass.endpoint_name and klass.endpoint_version:
             return {"name": klass.endpoint_name, "version": klass.endpoint_version}
-        raise TypeError("Can't get endpoint information for {klass.__name__}")
+        raise MindeeError("Can't get endpoint information for {klass.__name__}")
 
 
 TypeInference = TypeVar("TypeInference", bound=Inference)

tests/mindee_http/test_error.py

@@ -4,12 +4,12 @@
 import pytest
 
 from mindee import Client, product
-from mindee.input.sources import PathInput
-from mindee.mindee_http.error import (
-    MindeeHTTPClientException,
-    MindeeHTTPServerException,
+from mindee.error.mindee_http_error import (
+    MindeeHTTPClientError,
+    MindeeHTTPServerError,
     handle_error,
 )
+from mindee.input.sources import PathInput
 from tests.test_inputs import FILE_TYPES_DIR
 from tests.utils import clear_envvars, dummy_envvars
 
@@ -36,32 +36,32 @@ def dummy_file(monkeypatch) -> PathInput:
 
 
 def test_http_client_error(dummy_client: Client, dummy_file: PathInput):
-    with pytest.raises(MindeeHTTPClientException):
+    with pytest.raises(MindeeHTTPClientError):
         dummy_client.parse(product.InvoiceV4, dummy_file)
 
 
 def test_http_enqueue_client_error(dummy_client: Client, dummy_file: PathInput):
-    with pytest.raises(MindeeHTTPClientException):
+    with pytest.raises(MindeeHTTPClientError):
         dummy_client.enqueue(product.InvoiceV4, dummy_file)
 
 
 def test_http_parse_client_error(dummy_client: Client, dummy_file: PathInput):
-    with pytest.raises(MindeeHTTPClientException):
+    with pytest.raises(MindeeHTTPClientError):
         dummy_client.parse_queued(product.InvoiceV4, "dummy-queue-id")
 
 
 def test_http_enqueue_and_parse_client_error(
     dummy_client: Client, dummy_file: PathInput
 ):
-    with pytest.raises(MindeeHTTPClientException):
+    with pytest.raises(MindeeHTTPClientError):
         dummy_client.enqueue_and_parse(product.InvoiceV4, dummy_file)
 
 
 def test_http_400_error():
     error_ref = open(ERROR_DATA_DIR / "error_400_no_details.json")
     error_obj = json.load(error_ref)
     error_400 = handle_error("dummy-url", error_obj, 400)
-    with pytest.raises(MindeeHTTPClientException):
+    with pytest.raises(MindeeHTTPClientError):
         raise error_400
     assert error_400.status_code == 400
     assert error_400.api_code == "SomeCode"
@@ -73,7 +73,7 @@ def test_http_401_error():
     error_ref = open(ERROR_DATA_DIR / "error_401_invalid_token.json")
     error_obj = json.load(error_ref)
     error_401 = handle_error("dummy-url", error_obj, 401)
-    with pytest.raises(MindeeHTTPClientException):
+    with pytest.raises(MindeeHTTPClientError):
         raise error_401
     assert error_401.status_code == 401
     assert error_401.api_code == "Unauthorized"
@@ -85,7 +85,7 @@ def test_http_429_error():
     error_ref = open(ERROR_DATA_DIR / "error_429_too_many_requests.json")
     error_obj = json.load(error_ref)
     error_429 = handle_error("dummy-url", error_obj, 429)
-    with pytest.raises(MindeeHTTPClientException):
+    with pytest.raises(MindeeHTTPClientError):
         raise error_429
     assert error_429.status_code == 429
     assert error_429.api_code == "TooManyRequests"
@@ -97,7 +97,7 @@ def test_http_500_error():
     error_ref = open(ERROR_DATA_DIR / "error_500_inference_fail.json")
     error_obj = json.load(error_ref)
     error_500 = handle_error("dummy-url", error_obj, 500)
-    with pytest.raises(MindeeHTTPServerException):
+    with pytest.raises(MindeeHTTPServerError):
         raise error_500
     assert error_500.status_code == 500
     assert error_500.api_code == "failure"
@@ -108,7 +108,7 @@ def test_http_500_error():
 def test_http_500_html_error():
     error_ref_contents = open(ERROR_DATA_DIR / "error_50x.html").read()
     error_500 = handle_error("dummy-url", error_ref_contents, 500)
-    with pytest.raises(MindeeHTTPServerException):
+    with pytest.raises(MindeeHTTPServerError):
         raise error_500
     assert error_500.status_code == 500
     assert error_500.api_code == "UnknownError"