Add VuMark generation support

Implement VuMark instance generation API with support for multiple image formats (PNG, SVG, PDF). Add InvalidAcceptHeaderError and InvalidInstanceIdError exceptions for proper error handling. Includes comprehensive tests for all VuMark formats.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: adamtheturtle

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:

pyproject.toml

@@ -82,7 +82,7 @@ optional-dependencies.dev = [
     "ty==0.0.17",
     "types-requests==2.32.4.20260107",
     "vulture==2.14",
-    "vws-python-mock==2026.2.18",
+    "vws-python-mock==2026.2.18.1",
     "vws-test-fixtures==2023.3.5",
     "yamlfix==1.19.1",
     "zizmor==1.22.0",
@@ -363,6 +363,9 @@ ignore_names = [
     "pytest_plugins",
     # pytest fixtures - we name fixtures like this for this purpose
     "fixture_*",
+    # Enum members used dynamically
+    "PDF",
+    "SVG",
     # Sphinx
     "autoclass_content",
     "autoclass_content",

src/vws/exceptions/vws_exceptions.py

@@ -167,3 +167,19 @@ 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'.
+    """

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/vws.py

@@ -23,6 +23,8 @@
     DateRangeError,
     FailError,
     ImageTooLargeError,
+    InvalidAcceptHeaderError,
+    InvalidInstanceIdError,
     MetadataTooLargeError,
     ProjectHasNoAPIAccessError,
     ProjectInactiveError,
@@ -44,6 +46,7 @@
     TargetSummaryReport,
 )
 from vws.response import Response
+from vws.vumark_accept import VuMarkAccept
 
 _ImageType = io.BytesIO | BinaryIO
 
@@ -700,3 +703,116 @@ def update_target(
             expected_result_code="Success",
             content_type="application/json",
         )
+
+    def generate_vumark_instance(
+        self,
+        *,
+        target_id: str,
+        instance_id: str,
+        accept: VuMarkAccept = VuMarkAccept.PNG,
+    ) -> 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.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",
+        )
+        date_string = rfc_1123_date()
+
+        signature_string = authorization_header(
+            access_key=self._server_access_key,
+            secret_key=self._server_secret_key,
+            method=HTTPMethod.POST,
+            content=request_data,
+            content_type=content_type,
+            date=date_string,
+            request_path=request_path,
+        )
+
+        headers = {
+            "Authorization": signature_string,
+            "Date": date_string,
+            "Content-Type": content_type,
+            "Accept": accept,
+        }
+
+        url = urljoin(base=self._base_vws_url, url=request_path)
+
+        requests_response = requests.request(
+            method=HTTPMethod.POST,
+            url=url,
+            headers=headers,
+            data=request_data,
+            timeout=self._request_timeout_seconds,
+        )
+
+        if requests_response.status_code == HTTPStatus.OK:
+            return bytes(requests_response.content)
+
+        response = 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(),
+        )
+
+        if (
+            requests_response.status_code == HTTPStatus.TOO_MANY_REQUESTS
+        ):  # pragma: no cover
+            raise TooManyRequestsError(response=response)
+
+        if (
+            requests_response.status_code >= HTTPStatus.INTERNAL_SERVER_ERROR
+        ):  # pragma: no cover
+            raise ServerError(response=response)
+
+        result_code = json.loads(s=response.text)["result_code"]
+
+        exception = {
+            "AuthenticationFailure": AuthenticationFailureError,
+            "DateRangeError": DateRangeError,
+            "Fail": FailError,
+            "InvalidAcceptHeader": InvalidAcceptHeaderError,
+            "InvalidInstanceId": InvalidInstanceIdError,
+            "RequestTimeTooSkewed": RequestTimeTooSkewedError,
+            "TargetStatusNotSuccess": TargetStatusNotSuccessError,
+            "UnknownTarget": UnknownTargetError,
+        }[result_code]
+
+        raise exception(response=response)

tests/test_vws.py

@@ -21,6 +21,7 @@
     TargetStatuses,
     TargetSummaryReport,
 )
+from vws.vumark_accept import VuMarkAccept
 
 
 class TestAddTarget:
@@ -729,3 +730,55 @@ def test_no_fields_given(
         )
         vws_client.wait_for_target_processed(target_id=target_id)
         vws_client.update_target(target_id=target_id)
+
+
+class TestGenerateVumarkInstance:
+    """Tests for generating VuMark instances."""
+
+    @staticmethod
+    @pytest.mark.parametrize(
+        argnames="accept",
+        argvalues=list(VuMarkAccept),
+    )
+    def test_generate_vumark_instance(
+        vws_client: VWS,
+        high_quality_image: io.BytesIO,
+        accept: VuMarkAccept,
+    ) -> None:
+        """Bytes are returned when generating a VuMark instance."""
+        target_id = vws_client.add_target(
+            name="x",
+            width=1,
+            image=high_quality_image,
+            active_flag=True,
+            application_metadata=None,
+        )
+        vws_client.wait_for_target_processed(target_id=target_id)
+        result = vws_client.generate_vumark_instance(
+            target_id=target_id,
+            instance_id="12345",
+            accept=accept,
+        )
+        assert isinstance(result, bytes)
+        assert len(result) > 0
+
+    @staticmethod
+    def test_generate_vumark_default_accept(
+        vws_client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """By default, PNG is returned."""
+        target_id = vws_client.add_target(
+            name="x",
+            width=1,
+            image=high_quality_image,
+            active_flag=True,
+            application_metadata=None,
+        )
+        vws_client.wait_for_target_processed(target_id=target_id)
+        result = vws_client.generate_vumark_instance(
+            target_id=target_id,
+            instance_id="12345",
+        )
+        assert isinstance(result, bytes)
+        assert len(result) > 0

tests/test_vws_exceptions.py

@@ -21,6 +21,8 @@
     DateRangeError,
     FailError,
     ImageTooLargeError,
+    InvalidAcceptHeaderError,
+    InvalidInstanceIdError,
     MetadataTooLargeError,
     ProjectHasNoAPIAccessError,
     ProjectInactiveError,
@@ -342,6 +344,8 @@ def test_vwsexception_inheritance() -> None:
         DateRangeError,
         FailError,
         ImageTooLargeError,
+        InvalidAcceptHeaderError,
+        InvalidInstanceIdError,
         MetadataTooLargeError,
         ProjectInactiveError,
         ProjectHasNoAPIAccessError,
@@ -358,6 +362,31 @@ def test_vwsexception_inheritance() -> None:
         assert issubclass(subclass, VWSError)
 
 
+def test_invalid_instance_id(
+    vws_client: VWS,
+    high_quality_image: io.BytesIO,
+) -> None:
+    """
+    An ``InvalidInstanceId`` exception is raised when an empty instance
+    ID is given.
+    """
+    target_id = vws_client.add_target(
+        name="x",
+        width=1,
+        image=high_quality_image,
+        active_flag=True,
+        application_metadata=None,
+    )
+    vws_client.wait_for_target_processed(target_id=target_id)
+    with pytest.raises(expected_exception=InvalidInstanceIdError) as exc:
+        vws_client.generate_vumark_instance(
+            target_id=target_id,
+            instance_id="",
+        )
+
+    assert exc.value.response.status_code == HTTPStatus.UNPROCESSABLE_ENTITY
+
+
 def test_base_exception(
     vws_client: VWS,
     high_quality_image: io.BytesIO,