Merge pull request #1292 from VWS-Python/conn-error-test

Move exceptions around a little, separating the VWS Exceptions from the custom exceptions

Author: adamtheturtle

CHANGELOG.rst

@@ -6,6 +6,12 @@ Changelog
 Next
 ----
 
+* Breaking change: Move exceptions and create base exceptions.
+  It is now possible to, for example, catch
+  ``vws.exceptions.base_exceptions.VWSException`` to catch many of the
+  exceptions raised by the ``VWS`` client.
+  Credit to ``@laymonage`` for this change.
+
 2020.08.21.0
 ------------
 

docs/source/exceptions.rst

@@ -1,7 +1,39 @@
 Exceptions
 ==========
 
-.. automodule:: vws.exceptions
+.. contents::
+
+Base exceptions
+---------------
+
+.. automodule:: vws.exceptions.base_exceptions
+   :members:
+   :show-inheritance:
+   :inherited-members: Exception
+   :exclude-members: errno, filename, filename2, strerror
+
+VWS exceptions
+--------------
+
+.. automodule:: vws.exceptions.vws_exceptions
+   :members:
+   :show-inheritance:
+   :inherited-members: Exception
+   :exclude-members: errno, filename, filename2, strerror
+
+CloudRecoService exceptions
+---------------------------
+
+.. automodule:: vws.exceptions.cloud_reco_exceptions
+   :members:
+   :show-inheritance:
+   :inherited-members: Exception
+   :exclude-members: errno, filename, filename2, strerror
+
+Custom exceptions
+-----------------
+
+.. automodule:: vws.exceptions.custom_exceptions
    :members:
    :show-inheritance:
    :inherited-members: Exception

src/vws/_result_codes.py

@@ -0,0 +1,3 @@
+"""
+Custom exceptions raised by this package.
+"""

src/vws/exceptions/__init__.py

@@ -0,0 +1,51 @@
+"""
+Base exceptions for errors returned by Vuforia Web Services or the Vuforia
+Cloud Recognition Web API.
+"""
+
+from requests import Response
+
+
+class CloudRecoException(Exception):
+    """
+    Base class for Vuforia Cloud Recognition Web API exceptions.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to 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 VWSException(Exception):
+    """
+    Base class for Vuforia Web Services errors.
+
+    These errors are defined at
+    https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API#How-To-Interperete-VWS-API-Result-Codes.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to Vuforia.
+        """
+        super().__init__()
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """
+        The response returned by Vuforia which included this error.
+        """
+        return self._response

src/vws/exceptions/base_exceptions.py

@@ -0,0 +1,48 @@
+"""
+Exceptions which match errors raised by the Vuforia Cloud Recognition Web APIs.
+"""
+
+
+from vws.exceptions.base_exceptions import CloudRecoException
+
+
+class MatchProcessing(CloudRecoException):
+    """
+    Exception raised when a query is made with an image which matches a target
+    which is processing or has recently been deleted.
+    """
+
+
+class MaxNumResultsOutOfRange(CloudRecoException):
+    """
+    Exception raised when the ``max_num_results`` given to the Cloud
+    Recognition Web API query endpoint is out of range.
+    """
+
+
+class InactiveProject(CloudRecoException):
+    """
+    Exception raised when Vuforia returns a response with a result code
+    'InactiveProject'.
+    """
+
+
+class BadImage(CloudRecoException):
+    """
+    Exception raised when Vuforia returns a response with a result code
+    'BadImage'.
+    """
+
+
+class AuthenticationFailure(CloudRecoException):
+    """
+    Exception raised when Vuforia returns a response with a result code
+    'AuthenticationFailure'.
+    """
+
+
+class RequestTimeTooSkewed(CloudRecoException):
+    """
+    Exception raised when Vuforia returns a response with a result code
+    'RequestTimeTooSkewed'.
+    """

src/vws/exceptions/cloud_reco_exceptions.py

@@ -0,0 +1,29 @@
+"""
+Exceptions which do not map to errors at
+https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API#How-To-Interperete-VWS-API-Result-Codes
+or simple errors given by the cloud recognition service.
+"""
+
+import requests
+
+
+class UnknownVWSErrorPossiblyBadName(Exception):
+    """
+    Exception raised when VWS returns an HTML page which says "Oops, an error
+    occurred".
+
+    This has been seen to happen when the given name includes a bad character.
+    """
+
+
+class ConnectionErrorPossiblyImageTooLarge(requests.ConnectionError):
+    """
+    Exception raised when a ConnectionError is raised from a query. This has
+    been seen to happen when the given image is too large.
+    """
+
+
+class TargetProcessingTimeout(Exception):
+    """
+    Exception raised when waiting for a target to be processed times out.
+    """