Add application metadata parameter to add_target

Author: adamtheturtle

src/vws/exceptions.py

@@ -33,3 +33,18 @@ def __init__(self, response: Response) -> None:
         """
         super().__init__()
         self.response = response
+
+
+class MetadataTooLarge(Exception):
+    """
+    Exception raised when Vuforia returns a response with a result code
+    'MetadataTooLarge'.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to Vuforia.
+        """
+        super().__init__()
+        self.response = response

src/vws/vws.py

@@ -7,15 +7,19 @@
 import json
 from enum import Enum
 from time import sleep
-from typing import Dict, List, Union
+from typing import Dict, List, Optional, Union
 from urllib.parse import urljoin
 
 import requests
 import timeout_decorator
 from requests import Response
 
 from vws._authorization import authorization_header, rfc_1123_date
-from vws.exceptions import TargetStatusProcessing, UnknownTarget
+from vws.exceptions import (
+    MetadataTooLarge,
+    TargetStatusProcessing,
+    UnknownTarget,
+)
 
 
 def _target_api_request(
@@ -107,6 +111,7 @@ class _ResultCodes(Enum):
 _EXCEPTIONS = {
     _ResultCodes.UNKNOWN_TARGET: UnknownTarget,
     _ResultCodes.TARGET_STATUS_PROCESSING: TargetStatusProcessing,
+    _ResultCodes.METADATA_TOO_LARGE: MetadataTooLarge,
 }
 
 
@@ -137,6 +142,7 @@ def add_target(
         width: Union[int, float],
         image: io.BytesIO,
         active_flag: bool = True,
+        application_metadata: Optional[bytes] = None,
     ) -> str:
         """
         Add a target to a Vuforia Web Services database.
@@ -149,18 +155,26 @@ def add_target(
             width: The width of the target.
             image: The image of the target.
             active_flag: Whether or not the target is active for query.
+            application_metadata: The application metadata of the target.
+                This will be base64 encoded.
 
         Returns:
             The target ID of the new target.
         """
         image_data = image.getvalue()
         image_data_encoded = base64.b64encode(image_data).decode('ascii')
+        if application_metadata is None:
+            metadata_encoded = None
+        else:
+            metadata_encoded_str = base64.b64encode(application_metadata)
+            metadata_encoded = metadata_encoded_str.decode('ascii')
 
         data = {
             'name': name,
             'width': width,
             'image': image_data_encoded,
             'active_flag': active_flag,
+            'application_metadata': metadata_encoded,
         }
 
         content = bytes(json.dumps(data), encoding='utf-8')
@@ -174,7 +188,12 @@ def add_target(
             base_vws_url=self._base_vws_url,
         )
 
-        return str(response.json()['target_id'])
+        result_code = response.json()['result_code']
+        if _ResultCodes(result_code) == _ResultCodes.TARGET_CREATED:
+            return str(response.json()['target_id'])
+
+        exception = _EXCEPTIONS[_ResultCodes(result_code)]
+        raise exception(response=response)
 
     def get_target_record(self, target_id: str) -> Dict[str, Union[str, int]]:
         """

tests/test_add_target.py

@@ -6,8 +6,10 @@
 
 import pytest
 from mock_vws import MockVWS
+from requests import codes
 
 from vws import VWS
+from vws.exceptions import MetadataTooLarge
 
 
 class TestSuccess:
@@ -42,6 +44,8 @@ def test_add_two_targets(
     ) -> None:
         """
         No exception is raised when adding two targets with different names.
+
+        This demonstrates that the image seek position is not changed.
         """
         client.add_target(name='x', width=1, image=high_quality_image)
         client.add_target(name='a', width=1, image=high_quality_image)
@@ -72,6 +76,57 @@ def test_custom_base_url(self, high_quality_image: io.BytesIO) -> None:
             )
 
 
+class TestApplicationMetadata:
+    """
+    Tests for the ``application_metadata`` parameter to ``add_target``.
+    """
+
+    def test_none(self, client: VWS, high_quality_image: io.BytesIO) -> None:
+        """
+        No exception is raised when ``None`` is given.
+        """
+        client.add_target(
+            name='x',
+            width=1,
+            image=high_quality_image,
+            application_metadata=None,
+        )
+
+    def test_given(
+        self,
+        client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """
+        No exception is raised when bytes are given.
+        """
+        client.add_target(
+            name='x',
+            width=1,
+            image=high_quality_image,
+            application_metadata=b'a',
+        )
+
+    def test_too_large(
+        self,
+        client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """
+        A ``MetadataTooLarge`` exception is raised if the metadata given is too
+        large.
+        """
+        with pytest.raises(MetadataTooLarge) as exc:
+            client.add_target(
+                name='x',
+                width=1,
+                image=high_quality_image,
+                application_metadata=b'a' * 1024 * 1024,
+            )
+
+        assert exc.value.response.status_code == codes.UNPROCESSABLE_ENTITY
+
+
 class TestActiveFlag:
     """
     Tests for the ``active_flag`` parameter to ``add_target``.