Document ServerError might be raised in functions which might raise it

Author: adamtheturtle

src/vws/exceptions/custom_exceptions.py

@@ -63,3 +63,25 @@ 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

@@ -95,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.

src/vws/vws.py

@@ -20,6 +20,7 @@
     OopsAnErrorOccurredPossiblyBadName,
     ServerError,
     TargetProcessingTimeout,
+    TooManyRequests,
 )
 from vws.exceptions.vws_exceptions import (
     AuthenticationFailure,
@@ -37,7 +38,6 @@
     TargetQuotaReached,
     TargetStatusNotSuccess,
     TargetStatusProcessing,
-    TooManyRequests,
     UnknownTarget,
 )
 from vws.reports import (
@@ -167,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.
@@ -274,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")
@@ -320,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",
@@ -377,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:
@@ -408,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",
@@ -441,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",
@@ -480,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",
@@ -526,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",
@@ -559,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",
@@ -618,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] = {}