vws-python 2026.8.14__py3-none-any.whl

vws/exceptions/__init__.py

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

vws/exceptions/base_exceptions.py

@@ -0,0 +1,74 @@
+"""
+Base exceptions for errors returned by Vuforia Web Services or the
+Vuforia
+Cloud Recognition Web API.
+"""
+
+from collections.abc import Mapping  # noqa: TC003
+from typing import ClassVar
+
+from beartype import beartype
+
+from vws.response import Response  # noqa: TC001
+
+
+@beartype
+class CloudRecoError(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
+
+
+@beartype
+class VWSError(Exception):
+    """Base class for Vuforia Web Services errors.
+
+    These errors are defined at
+    https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#result-codes.
+    """
+
+    _exceptions_by_result_code: ClassVar[dict[str, type[VWSError]]] = {}
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to Vuforia.
+        """
+        super().__init__()
+        self._response = response
+
+    @classmethod
+    def register_exceptions_by_result_code(
+        cls,
+        *,
+        exceptions_by_result_code: Mapping[str, type[VWSError]],
+    ) -> None:
+        """Register ``result_code`` to exception mappings."""
+        cls._exceptions_by_result_code.update(exceptions_by_result_code)
+
+    @classmethod
+    def from_result_code(
+        cls,
+        *,
+        result_code: str,
+        response: Response,
+    ) -> VWSError:
+        """Create the mapped exception for a VWS ``result_code``."""
+        exception_type = cls._exceptions_by_result_code[result_code]
+        return exception_type(response=response)
+
+    @property
+    def response(self) -> Response:
+        """The response returned by Vuforia which included this error."""
+        return self._response

vws/exceptions/cloud_reco_exceptions.py

@@ -0,0 +1,44 @@
+"""Exceptions which match errors raised by the Vuforia Cloud Recognition
+Web
+APIs.
+"""
+
+from beartype import beartype
+
+from vws.exceptions.base_exceptions import CloudRecoError
+
+
+@beartype
+class MaxNumResultsOutOfRangeError(CloudRecoError):
+    """
+    Exception raised when the ``max_num_results`` given to the Cloud
+    Recognition Web API query endpoint is out of range.
+    """
+
+
+@beartype
+class InactiveProjectError(CloudRecoError):
+    """Exception raised when Vuforia returns a response with a result code
+    'InactiveProject'.
+    """
+
+
+@beartype
+class BadImageError(CloudRecoError):
+    """Exception raised when Vuforia returns a response with a result code
+    'BadImage'.
+    """
+
+
+@beartype
+class AuthenticationFailureError(CloudRecoError):
+    """Exception raised when Vuforia returns a response with a result code
+    'AuthenticationFailure'.
+    """
+
+
+@beartype
+class RequestTimeTooSkewedError(CloudRecoError):
+    """Exception raised when Vuforia returns a response with a result code
+    'RequestTimeTooSkewed'.
+    """

vws/exceptions/custom_exceptions.py

@@ -0,0 +1,107 @@
+"""Exceptions which do not map to errors at the following URL, or simple
+errors given by the cloud recognition service.
+
+https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#result-codes
+"""
+
+from beartype import beartype
+
+from vws.response import Response  # noqa: TC001
+
+
+@beartype
+class RequestEntityTooLargeError(Exception):
+    """Exception raised when the given image is too large."""
+
+    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
+
+
+@beartype
+class TargetProcessingTimeoutError(Exception):
+    """Exception raised when waiting for a target to be processed times
+    out.
+    """
+
+
+@beartype
+class DatabaseIdNotSetError(Exception):
+    """Exception raised when an operation which needs a database ID is used
+    on a client which was not given one.
+    """
+
+
+@beartype
+class RecoCountsReportNotReadyError(Exception):
+    """Exception raised when a reco counts report is downloaded before
+    Vuforia has generated it.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response returned by the report's download URL.
+        """
+        super().__init__(response.text)
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """The response returned by the download URL."""
+        return self._response
+
+
+@beartype
+class RecoCountsReportDownloadError(Exception):
+    """Exception raised when downloading a reco counts report fails.
+
+    This is raised, for example, when the report's URL has expired.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response returned by the report's download URL.
+        """
+        super().__init__(response.text)
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """The response returned by the download URL."""
+        return self._response
+
+
+@beartype
+class RecoCountsReportTimeoutError(Exception):
+    """Exception raised when waiting for a reco counts report to be
+    generated times out.
+    """
+
+
+@beartype
+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

vws/exceptions/model_target_exceptions.py

@@ -0,0 +1,210 @@
+"""Exceptions raised by the Vuforia Model Target Web API.
+
+See
+https://developer.vuforia.com/library/vuforia-engine/web-api/model-target-web-api/.
+"""
+
+import json
+from typing import Any
+
+from beartype import beartype
+
+from vws.reports import ModelTargetGenerationDetail
+from vws.response import Response  # noqa: TC001
+
+
+@beartype
+def _is_json_object(*, value: object) -> bool:
+    """Get whether a decoded JSON value is an object.
+
+    Args:
+        value: A decoded JSON value.
+
+    Returns:
+        Whether the value is a JSON object.
+    """
+    return isinstance(value, dict)
+
+
+@beartype
+def _json_object(*, value: str) -> dict[str, Any]:
+    """Get a JSON object from a string.
+
+    Args:
+        value: A string which may be a JSON object.
+
+    Returns:
+        The JSON object, or an empty dictionary if the string is not a
+        JSON object.
+    """
+    try:
+        loaded: Any = json.loads(s=value)
+    except json.JSONDecodeError:
+        return {}
+
+    if not _is_json_object(value=loaded):
+        return {}
+
+    json_object: dict[str, Any] = loaded
+    return json_object
+
+
+@beartype
+def _error_dict(*, response: Response) -> dict[str, Any]:
+    """Get the error object of a Model Target Web API error response.
+
+    Args:
+        response: The response returned by Vuforia.
+
+    Returns:
+        The error object, or an empty dictionary if the response has no
+        error object. Some errors, such as those given by the load
+        balancer in front of Vuforia, are not shaped like Model Target
+        Web API errors.
+    """
+    body = _json_object(value=response.text)
+    if "error" not in body:
+        return {}
+
+    error: Any = body["error"]
+    if not _is_json_object(value=error):
+        return {}
+
+    error_dict: dict[str, Any] = error
+    return error_dict
+
+
+@beartype
+class ModelTargetError(Exception):
+    """Base class for Vuforia Model Target 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
+
+    @property
+    def code(self) -> str:
+        """The error code given by Vuforia, or an empty string."""
+        error = _error_dict(response=self._response)
+        return str(object=error["code"]) if "code" in error else ""
+
+    @property
+    def message(self) -> str:
+        """The error message given by Vuforia, or an empty string."""
+        error = _error_dict(response=self._response)
+        return str(object=error["message"]) if "message" in error else ""
+
+    @property
+    def target(self) -> str:
+        """The error target given by Vuforia, or an empty string."""
+        error = _error_dict(response=self._response)
+        return str(object=error["target"]) if "target" in error else ""
+
+    @property
+    def details(self) -> list[ModelTargetGenerationDetail]:
+        """The error details given by Vuforia.
+
+        Vuforia gives one detail per validation problem it found with a
+        dataset creation request.
+        """
+        error = _error_dict(response=self._response)
+        if "details" not in error:
+            return []
+
+        return [
+            ModelTargetGenerationDetail(
+                code=detail["code"],
+                message=detail["message"],
+            )
+            for detail in error["details"]
+        ]
+
+
+@beartype
+class ModelTargetAuthenticationError(ModelTargetError):
+    """Exception raised when a Model Target Web API request is not
+    authenticated.
+
+    For example, the bearer token may be missing, malformed or expired.
+    """
+
+
+@beartype
+class ModelTargetValidationError(ModelTargetError):
+    """Exception raised when Vuforia rejects a Model Target dataset
+    creation
+    request.
+
+    See :attr:`~.ModelTargetError.details` for the problems which Vuforia
+    found.
+    """
+
+
+@beartype
+class UnknownModelTargetDatasetError(ModelTargetError):
+    """Exception raised when no Model Target dataset matches a given UUID.
+
+    Standard and advanced datasets are separate resources, so this is also
+    raised when the given UUID matches a dataset of the other type.
+    """
+
+
+@beartype
+class ModelTargetDatasetNotDoneError(ModelTargetError):
+    """Exception raised when a Model Target dataset is downloaded before
+    Vuforia has generated it.
+    """
+
+
+@beartype
+class ModelTargetOAuth2Error(Exception):
+    """Exception raised when Vuforia does not give an access token.
+
+    For example, the given client ID and client secret may not match a set
+    of Model Target Web API credentials.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to Vuforia's token
+                endpoint.
+        """
+        super().__init__(response.text)
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """The response returned by Vuforia which included this error."""
+        return self._response
+
+    @property
+    def error(self) -> str:
+        """The OAuth2 error code, or an empty string."""
+        body = _json_object(value=self._response.text)
+        return str(object=body["error"]) if "error" in body else ""
+
+    @property
+    def error_description(self) -> str:
+        """The OAuth2 error description, or an empty string."""
+        body = _json_object(value=self._response.text)
+        if "error_description" not in body:
+            return ""
+
+        return str(object=body["error_description"])
+
+
+@beartype
+class ModelTargetDatasetTimeoutError(Exception):
+    """Exception raised when waiting for a Model Target dataset to be
+    generated times out.
+    """

vws/exceptions/vws_exceptions.py

@@ -0,0 +1,256 @@
+"""
+Exception raised when Vuforia returns a response with a result code
+matching
+one of those documented at
+https://developer.vuforia.com/library/web-api/cloud-targets-web-services-
+api#result-codes.
+"""
+
+import json
+from urllib.parse import urlparse
+
+from beartype import beartype
+
+from vws.exceptions.base_exceptions import VWSError
+
+
+def _target_id_from_url(*, url: str) -> str:
+    """Return the target ID from a VWS response URL.
+
+    Paths may include a custom base URL prefix. The target ID is the
+    path segment after ``targets``, ``summary``, or ``duplicates``.
+    """
+    path = urlparse(url=url).path
+    parts = [part for part in path.split(sep="/") if part]
+    for marker in ("targets", "summary", "duplicates"):
+        try:
+            marker_index = parts.index(marker)
+        except ValueError:
+            continue
+        return parts[marker_index + 1]
+    message = f"Could not find a target ID in URL path {path!r}"
+    raise ValueError(message)
+
+
+@beartype
+class UnknownTargetError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'UnknownTarget'.
+    """
+
+    @property
+    def target_id(self) -> str:
+        """The unknown target ID."""
+        return _target_id_from_url(url=self.response.url)
+
+
+@beartype
+class FailError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'Fail'.
+    """
+
+
+@beartype
+class BadImageError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'BadImage'.
+    """
+
+
+@beartype
+class AuthenticationFailureError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'AuthenticationFailure'.
+    """
+
+
+@beartype
+class RequestQuotaReachedError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'RequestQuotaReached'.
+    """
+
+
+@beartype
+class TargetStatusProcessingError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'TargetStatusProcessing'.
+    """
+
+    @property
+    def target_id(self) -> str:
+        """The processing target ID."""
+        return _target_id_from_url(url=self.response.url)
+
+
+# This is not simulated by the mock.
+@beartype
+class DateRangeError(VWSError):  # pragma: no cover
+    """Exception raised when Vuforia returns a response with a result code
+    'DateRangeError'.
+    """
+
+
+@beartype
+class TargetQuotaReachedError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'TargetQuotaReached'.
+    """
+
+
+@beartype
+class ProjectSuspendedError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'ProjectSuspended'.
+    """
+
+
+@beartype
+class ProjectHasNoAPIAccessError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'ProjectHasNoApiAccess'.
+    """
+
+
+@beartype
+class ProjectInactiveError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'ProjectInactive'.
+    """
+
+
+@beartype
+class MetadataTooLargeError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'MetadataTooLarge'.
+    """
+
+
+@beartype
+class RequestTimeTooSkewedError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'RequestTimeTooSkewed'.
+    """
+
+
+@beartype
+class TargetNameExistError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'TargetNameExist'.
+    """
+
+    @property
+    def target_name(self) -> str:
+        """The target name which already exists."""
+        response_body = self.response.request_body or b""
+        request_json = json.loads(s=response_body)
+        return str(object=request_json["name"])
+
+
+@beartype
+class ImageTooLargeError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'ImageTooLarge'.
+    """
+
+
+@beartype
+class TargetStatusNotSuccessError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    'TargetStatusNotSuccess'.
+    """
+
+    @property
+    def target_id(self) -> str:
+        """The unknown target ID."""
+        return _target_id_from_url(url=self.response.url)
+
+
+@beartype
+class TooManyRequestsError(VWSError):  # pragma: no cover
+    """Exception raised when Vuforia returns a response with a result code
+    'TooManyRequests'.
+    """
+
+
+# This is not simulated by client code because the accept parameter uses
+# the VuMarkAccept enum, which only allows valid values.
+@beartype
+class InvalidAcceptHeaderError(VWSError):  # pragma: no cover
+    """Exception raised when Vuforia returns a response with a result code
+    ``InvalidAcceptHeader``.
+    """
+
+
+@beartype
+class InvalidInstanceIdError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    ``InvalidInstanceId``.
+    """
+
+
+# This is not simulated by client code because the request body
+# is always valid JSON when using this client.
+@beartype
+class BadRequestError(VWSError):  # pragma: no cover
+    """Exception raised when Vuforia returns a response with a result code
+    ``BadRequest``.
+    """
+
+
+@beartype
+class InvalidTargetTypeError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    ``InvalidTargetType``.
+    """
+
+
+@beartype
+class QuotaExceededError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    ``QuotaExceeded``.
+    """
+
+
+@beartype
+class LicenseCheckFailedError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    ``LicenseCheckFailed``.
+    """
+
+
+@beartype
+class AuthorizationFailedError(VWSError):
+    """Exception raised when Vuforia returns a response with a result code
+    ``AuthorizationFailed``.
+    """
+
+
+VWSError.register_exceptions_by_result_code(
+    exceptions_by_result_code={
+        "AuthenticationFailure": AuthenticationFailureError,
+        "AuthorizationFailed": AuthorizationFailedError,
+        "BadImage": BadImageError,
+        "BadRequest": BadRequestError,
+        "DateRangeError": DateRangeError,
+        "Fail": FailError,
+        "ImageTooLarge": ImageTooLargeError,
+        "InvalidAcceptHeader": InvalidAcceptHeaderError,
+        "InvalidInstanceId": InvalidInstanceIdError,
+        "InvalidTargetType": InvalidTargetTypeError,
+        "LicenseCheckFailed": LicenseCheckFailedError,
+        "MetadataTooLarge": MetadataTooLargeError,
+        "ProjectHasNoApiAccess": ProjectHasNoAPIAccessError,
+        "ProjectInactive": ProjectInactiveError,
+        "ProjectSuspended": ProjectSuspendedError,
+        "QuotaExceeded": QuotaExceededError,
+        "RequestQuotaReached": RequestQuotaReachedError,
+        "RequestTimeTooSkewed": RequestTimeTooSkewedError,
+        "TargetNameExist": TargetNameExistError,
+        "TargetQuotaReached": TargetQuotaReachedError,
+        "TargetStatusNotSuccess": TargetStatusNotSuccessError,
+        "TargetStatusProcessing": TargetStatusProcessingError,
+        "UnknownTarget": UnknownTargetError,
+    },
+)