Merge pull request #2108 from VWS-Python/server-error

Return a new error when the server returns a 5xx status code.

Author: adamtheturtle

CHANGELOG.rst

@@ -4,6 +4,8 @@ Changelog
 Next
 ----
 
+* Return a new error (``vws.custom_exceptions.ServerError``) when the server returns a 5xx status code.
+
 2023.12.27
 ------------
 

src/vws/exceptions/custom_exceptions.py

@@ -42,3 +42,46 @@ class TargetProcessingTimeout(Exception):
     """
     Exception raised when waiting for a target to be processed times out.
     """
+
+
+class ServerError(Exception):  # pragma: no cover
+    """
+    Exception raised when VWS returns a server error.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response returned by Vuforia.
+        """
+        super().__init__(response.text)
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """
+        The response returned by Vuforia which included this error.
+        """
+        return self._response
+
+
+class TooManyRequests(Exception):  # pragma: no cover
+    """
+    Exception raised when Vuforia returns a response with a result code
+    'TooManyRequests'.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response returned by Vuforia.
+        """
+        super().__init__(response.text)
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """
+        The response returned by Vuforia which included this error.
+        """
+        return self._response

src/vws/exceptions/vws_exceptions.py

@@ -56,13 +56,6 @@ class RequestQuotaReached(VWSException):  # pragma: no cover
     """
 
 
-class TooManyRequests(VWSException):  # pragma: no cover
-    """
-    Exception raised when Vuforia returns a response with a result code
-    'TooManyRequests'.
-    """
-
-
 class TargetStatusProcessing(VWSException):
     """
     Exception raised when Vuforia returns a response with a result code

src/vws/query.py

@@ -22,6 +22,7 @@
 )
 from vws.exceptions.custom_exceptions import (
     RequestEntityTooLarge,
+    ServerError,
 )
 from vws.include_target_data import CloudRecoIncludeTargetData
 from vws.reports import QueryResult, TargetData
@@ -94,6 +95,8 @@ def query(
                 file in the grayscale or RGB color space.
             ~vws.exceptions.custom_exceptions.RequestEntityTooLarge: The given
                 image is too large.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
 
         Returns:
             An ordered list of target details of matching targets.
@@ -145,6 +148,11 @@ def query(
         if "Integer out of range" in response.text:
             raise MaxNumResultsOutOfRange(response=response)
 
+        if (
+            response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR
+        ):  # pragma: no cover
+            raise ServerError(response=response)
+
         result_code = response.json()["result_code"]
         if result_code != "Success":
             exception = {

src/vws/vws.py

@@ -18,7 +18,9 @@
 
 from vws.exceptions.custom_exceptions import (
     OopsAnErrorOccurredPossiblyBadName,
+    ServerError,
     TargetProcessingTimeout,
+    TooManyRequests,
 )
 from vws.exceptions.vws_exceptions import (
     AuthenticationFailure,
@@ -36,7 +38,6 @@
     TargetQuotaReached,
     TargetStatusNotSuccess,
     TargetStatusProcessing,
-    TooManyRequests,
     UnknownTarget,
 )
 from vws.reports import (
@@ -166,6 +167,10 @@ def _make_request(
                 an HTML page with the text "Oops, an error occurred". This has
                 been seen to happen when the given name includes a bad
                 character.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
             json.decoder.JSONDecodeError: The server did not respond with valid
                 JSON. This may happen if the server address is not a valid
                 Vuforia server.
@@ -188,6 +193,11 @@ def _make_request(
             # The Vuforia API returns a 429 response with no JSON body.
             raise TooManyRequests(response=response)
 
+        if (
+            response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR
+        ):  # pragma: no cover
+            raise ServerError(response=response)
+
         result_code = response.json()["result_code"]
 
         if result_code == expected_result_code:
@@ -268,6 +278,10 @@ def add_target(
                 Vuforia returns an HTML page with the text "Oops, an error
                 occurred". This has been seen to happen when the given name
                 includes a bad character.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         image_data = _get_image_data(image=image)
         image_data_encoded = base64.b64encode(image_data).decode("ascii")
@@ -314,6 +328,10 @@ def get_target_record(self, target_id: str) -> TargetStatusAndRecord:
                 does not match a target in the database.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         response = self._make_request(
             method="GET",
@@ -371,6 +389,10 @@ def wait_for_target_processed(
                 does not match a target in the database.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         start_time = time.monotonic()
         while True:
@@ -402,6 +424,10 @@ def list_targets(self) -> list[str]:
                 known database.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         response = self._make_request(
             method="GET",
@@ -435,6 +461,10 @@ def get_target_summary_report(self, target_id: str) -> TargetSummaryReport:
                 does not match a target in the database.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         response = self._make_request(
             method="GET",
@@ -474,6 +504,10 @@ def get_database_summary_report(self) -> DatabaseSummaryReport:
                 known database.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         response = self._make_request(
             method="GET",
@@ -520,6 +554,10 @@ def delete_target(self, target_id: str) -> None:
                 target is in the processing state.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         self._make_request(
             method="DELETE",
@@ -553,6 +591,10 @@ def get_duplicate_targets(self, target_id: str) -> list[str]:
                 inactive.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         response = self._make_request(
             method="GET",
@@ -612,6 +654,10 @@ def update_target(
                 inactive.
             ~vws.exceptions.vws_exceptions.RequestTimeTooSkewed: There is an
                 error with the time sent to Vuforia.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.custom_exceptions.TooManyRequests: Vuforia is rate
+                limiting access.
         """
         data: dict[str, str | bool | float | int] = {}