Add VuMark generation support

docs/source/api-reference.rst

@@ -13,6 +13,10 @@ API Reference
    :undoc-members:
    :members:
 
+.. automodule:: vws.vumark_accept
+   :undoc-members:
+   :members:
+
 .. automodule:: vws.response
    :undoc-members:
    :members:

spelling_private_dict.txt

@@ -42,6 +42,7 @@ decodable
 dev
 dict
 docstring
+enum
 filename
 foo
 formdata
@@ -100,6 +101,7 @@ usefixtures
 validators
 vuforia
 vuforia's
+vumark
 vwq
 vws
 xxx

src/vws/__init__.py

@@ -1,9 +1,11 @@
 """A library for Vuforia Web Services."""
 
 from .query import CloudRecoService
+from .vumark_service import VuMarkService
 from .vws import VWS
 
 __all__ = [
     "VWS",
     "CloudRecoService",
+    "VuMarkService",
 ]

src/vws/_vws_request.py

@@ -0,0 +1,85 @@
+"""Internal helper for making authenticated requests to the Vuforia Target
+API.
+"""
+
+from urllib.parse import urljoin
+
+import requests
+from beartype import BeartypeConf, beartype
+from vws_auth_tools import authorization_header, rfc_1123_date
+
+from vws.response import Response
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+def target_api_request(
+    *,
+    content_type: str,
+    server_access_key: str,
+    server_secret_key: str,
+    method: str,
+    data: bytes,
+    request_path: str,
+    base_vws_url: str,
+    request_timeout_seconds: float | tuple[float, float],
+    extra_headers: dict[str, str],
+) -> Response:
+    """Make a request to the Vuforia Target API.
+
+    This uses `requests` to make a request against https://vws.vuforia.com.
+
+    Args:
+        content_type: The content type of the request.
+        server_access_key: A VWS server access key.
+        server_secret_key: A VWS server secret key.
+        method: The HTTP method which will be used in the request.
+        data: The request body which will be used in the request.
+        request_path: The path to the endpoint which will be used in the
+            request.
+        base_vws_url: The base URL for the VWS API.
+        request_timeout_seconds: The timeout for the request, as used by
+            ``requests.request``. This can be a float to set both the
+            connect and read timeouts, or a (connect, read) tuple.
+        extra_headers: Additional headers to include in the request.
+
+    Returns:
+        The response to the request made by `requests`.
+    """
+    date_string = rfc_1123_date()
+
+    signature_string = authorization_header(
+        access_key=server_access_key,
+        secret_key=server_secret_key,
+        method=method,
+        content=data,
+        content_type=content_type,
+        date=date_string,
+        request_path=request_path,
+    )
+
+    headers = {
+        "Authorization": signature_string,
+        "Date": date_string,
+        "Content-Type": content_type,
+        **extra_headers,
+    }
+
+    url = urljoin(base=base_vws_url, url=request_path)
+
+    requests_response = requests.request(
+        method=method,
+        url=url,
+        headers=headers,
+        data=data,
+        timeout=request_timeout_seconds,
+    )
+
+    return Response(
+        text=requests_response.text,
+        url=requests_response.url,
+        status_code=requests_response.status_code,
+        headers=dict(requests_response.headers),
+        request_body=requests_response.request.body,
+        tell_position=requests_response.raw.tell(),
+        content=bytes(requests_response.content),
+    )

src/vws/exceptions/vws_exceptions.py

@@ -24,9 +24,10 @@ class UnknownTargetError(VWSError):
     def target_id(self) -> str:
         """The unknown target ID."""
         path = urlparse(url=self.response.url).path
-        # Every HTTP path which can raise this error is in the format
-        # `/something/{target_id}`.
-        return path.split(sep="/", maxsplit=2)[-1]
+        # Every HTTP path which can raise this error has the target ID as the
+        # second path segment, e.g. `/something/{target_id}` or
+        # `/something/{target_id}/more`.
+        return path.split(sep="/")[2]
 
 
 @beartype
@@ -68,9 +69,10 @@ class TargetStatusProcessingError(VWSError):
     def target_id(self) -> str:
         """The processing target ID."""
         path = urlparse(url=self.response.url).path
-        # Every HTTP path which can raise this error is in the format
-        # `/something/{target_id}`.
-        return path.split(sep="/", maxsplit=2)[-1]
+        # Every HTTP path which can raise this error has the target ID as the
+        # second path segment, e.g. `/something/{target_id}` or
+        # `/something/{target_id}/more`.
+        return path.split(sep="/")[2]
 
 
 # This is not simulated by the mock.
@@ -157,13 +159,46 @@ class TargetStatusNotSuccessError(VWSError):
     def target_id(self) -> str:
         """The unknown target ID."""
         path = urlparse(url=self.response.url).path
-        # Every HTTP path which can raise this error is in the format
-        # `/something/{target_id}`.
-        return path.split(sep="/", maxsplit=2)[-1]
+        # Every HTTP path which can raise this error has the target ID as the
+        # second path segment, e.g. `/something/{target_id}` or
+        # `/something/{target_id}/more`.
+        return path.split(sep="/")[2]
 
 
 @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``.
+    """

src/vws/query.py

@@ -156,6 +156,7 @@ def query(
             headers=dict(requests_response.headers),
             request_body=requests_response.request.body,
             tell_position=requests_response.raw.tell(),
+            content=bytes(requests_response.content),
         )
 
         if response.status_code == HTTPStatus.REQUEST_ENTITY_TOO_LARGE:

src/vws/response.py

@@ -16,3 +16,4 @@ class Response:
     headers: dict[str, str]
     request_body: bytes | str | None
     tell_position: int
+    content: bytes

src/vws/vumark_accept.py

@@ -0,0 +1,18 @@
+"""Tools for managing ``VWS.generate_vumark_instance``'s ``accept``."""
+
+from enum import StrEnum, unique
+
+from beartype import beartype
+
+
+@beartype
+@unique
+class VuMarkAccept(StrEnum):
+    """
+    Options for the ``accept`` parameter of
+    ``VWS.generate_vumark_instance``.
+    """
+
+    PNG = "image/png"
+    SVG = "image/svg+xml"
+    PDF = "application/pdf"

src/vws/vumark_service.py

@@ -0,0 +1,143 @@
+"""Interface to the Vuforia VuMark Generation Web API."""
+
+import json
+from http import HTTPMethod, HTTPStatus
+
+from beartype import BeartypeConf, beartype
+
+from vws._vws_request import target_api_request
+from vws.exceptions.custom_exceptions import ServerError
+from vws.exceptions.vws_exceptions import (
+    AuthenticationFailureError,
+    BadRequestError,
+    DateRangeError,
+    FailError,
+    InvalidAcceptHeaderError,
+    InvalidInstanceIdError,
+    InvalidTargetTypeError,
+    RequestTimeTooSkewedError,
+    TargetStatusNotSuccessError,
+    TooManyRequestsError,
+    UnknownTargetError,
+)
+from vws.vumark_accept import VuMarkAccept
+
+
+@beartype(conf=BeartypeConf(is_pep484_tower=True))
+class VuMarkService:
+    """An interface to the Vuforia VuMark Generation Web API."""
+
+    def __init__(
+        self,
+        server_access_key: str,
+        server_secret_key: str,
+        base_vws_url: str = "https://vws.vuforia.com",
+        request_timeout_seconds: float | tuple[float, float] = 30.0,
+    ) -> None:
+        """
+        Args:
+            server_access_key: A VWS server access key.
+            server_secret_key: A VWS server secret key.
+            base_vws_url: The base URL for the VWS API.
+            request_timeout_seconds: The timeout for each HTTP request, as
+                used by ``requests.request``. This can be a float to set
+                both the connect and read timeouts, or a (connect, read)
+                tuple.
+        """
+        self._server_access_key = server_access_key
+        self._server_secret_key = server_secret_key
+        self._base_vws_url = base_vws_url
+        self._request_timeout_seconds = request_timeout_seconds
+
+    def generate_vumark_instance(
+        self,
+        *,
+        target_id: str,
+        instance_id: str,
+        accept: VuMarkAccept,
+    ) -> bytes:
+        """Generate a VuMark instance image.
+
+        See
+        https://developer.vuforia.com/library/vuforia-engine/web-api/vumark-generation-web-api/
+        for parameter details.
+
+        Args:
+            target_id: The ID of the VuMark target.
+            instance_id: The instance ID to encode in the VuMark.
+            accept: The image format to return.
+
+        Returns:
+            The VuMark instance image bytes.
+
+        Raises:
+            ~vws.exceptions.vws_exceptions.AuthenticationFailureError: The
+                secret key is not correct.
+            ~vws.exceptions.vws_exceptions.FailError: There was an error with
+                the request. For example, the given access key does not match a
+                known database.
+            ~vws.exceptions.vws_exceptions.InvalidAcceptHeaderError: The
+                Accept header value is not supported.
+            ~vws.exceptions.vws_exceptions.InvalidInstanceIdError: The
+                instance ID is invalid. For example, it may be empty.
+            ~vws.exceptions.vws_exceptions.InvalidTargetTypeError: The target
+                is not a VuMark template target.
+            ~vws.exceptions.vws_exceptions.RequestTimeTooSkewedError: There is
+                an error with the time sent to Vuforia.
+            ~vws.exceptions.vws_exceptions.TargetStatusNotSuccessError: The
+                target is not in the success state.
+            ~vws.exceptions.vws_exceptions.UnknownTargetError: The given target
+                ID does not match a target in the database.
+            ~vws.exceptions.custom_exceptions.ServerError: There is an error
+                with Vuforia's servers.
+            ~vws.exceptions.vws_exceptions.TooManyRequestsError: Vuforia is
+                rate limiting access.
+        """
+        request_path = f"/targets/{target_id}/instances"
+        content_type = "application/json"
+        request_data = json.dumps(obj={"instance_id": instance_id}).encode(
+            encoding="utf-8",
+        )
+
+        response = target_api_request(
+            content_type=content_type,
+            server_access_key=self._server_access_key,
+            server_secret_key=self._server_secret_key,
+            method=HTTPMethod.POST,
+            data=request_data,
+            request_path=request_path,
+            base_vws_url=self._base_vws_url,
+            request_timeout_seconds=self._request_timeout_seconds,
+            extra_headers={"Accept": accept},
+        )
+
+        if (
+            response.status_code == HTTPStatus.TOO_MANY_REQUESTS
+        ):  # pragma: no cover
+            # The Vuforia API returns a 429 response with no JSON body.
+            raise TooManyRequestsError(response=response)
+
+        if (
+            response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR
+        ):  # pragma: no cover
+            raise ServerError(response=response)
+
+        if response.status_code == HTTPStatus.OK:
+            return response.content
+
+        result_code = json.loads(s=response.text)["result_code"]
+
+        exception = {
+            "AuthenticationFailure": AuthenticationFailureError,
+            "BadRequest": BadRequestError,
+            "DateRangeError": DateRangeError,
+            "Fail": FailError,
+            "InvalidAcceptHeader": InvalidAcceptHeaderError,
+            "InvalidInstanceId": InvalidInstanceIdError,
+            "InvalidTargetType": InvalidTargetTypeError,
+            "RequestTimeTooSkewed": RequestTimeTooSkewedError,
+            "TargetStatusNotSuccess": TargetStatusNotSuccessError,
+            "UnknownTarget": UnknownTargetError,
+        }[result_code]
+
+        raise exception(response=response)