Merge pull request #900 from adamtheturtle/update

Add Update option

Author: adamtheturtle

src/vws/exceptions.py

@@ -203,6 +203,21 @@ def response(self) -> Response:
         return self._response
 
 
+class TargetStatusNotSuccess(Exception):
+    """
+    Exception raised when Vuforia returns a response with a result code
+    'TargetStatusNotSuccess'.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to Vuforia.
+        """
+        super().__init__()
+        self.response = response
+
+
 class TargetProcessingTimeout(Exception):
     """
     Exception raised when waiting for a target to be processed times out.

src/vws/vws.py

@@ -23,6 +23,7 @@
     ProjectInactive,
     TargetNameExist,
     TargetProcessingTimeout,
+    TargetStatusNotSuccess,
     TargetStatusProcessing,
     UnknownTarget,
 )
@@ -111,6 +112,7 @@ def _raise_for_result_code(
         'ProjectInactive': ProjectInactive,
         'TargetNameExist': TargetNameExist,
         'TargetStatusProcessing': TargetStatusProcessing,
+        'TargetStatusNotSuccess': TargetStatusNotSuccess,
         'UnknownTarget': UnknownTarget,
     }[result_code]
 
@@ -490,3 +492,73 @@ def get_duplicate_targets(self, target_id: str) -> List[str]:
         )
 
         return list(response.json()['similar_targets'])
+
+    def update_target(
+        self,
+        target_id: str,
+        name: Optional[str] = None,
+        width: Optional[Union[int, float]] = None,
+        image: Optional[io.BytesIO] = None,
+        active_flag: Optional[bool] = None,
+        application_metadata: Optional[bytes] = None,
+    ) -> None:
+        """
+        Add a target to a Vuforia Web Services database.
+
+        See
+        https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API#How-To-Add-a-Target
+        for parameter details.
+
+        Args:
+            target_id: The ID of the target to get details of.
+            name: The name of the 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.
+
+        Raises:
+            ~vws.exceptions.AuthenticationFailure: The secret key is not
+                correct.
+            ~vws.exceptions.BadImage: There is a problem with the given image.
+                For example, it must be a JPEG or PNG file in the grayscale or
+                RGB color space.
+            ~vws.exceptions.Fail: There was an error with the request. For
+                example, the given access key does not match a known database.
+            ~vws.exceptions.MetadataTooLarge: The given metadata is too large.
+                The maximum size is 1 MB of data when Base64 encoded.
+            ~vws.exceptions.ImageTooLarge: The given image is too large.
+            ~vws.exceptions.TargetNameExist: A target with the given ``name``
+                already exists.
+            ~vws.exceptions.ProjectInactive: The project is inactive.
+        """
+        data: Dict[str, Union[str, bool, float, int]] = {}
+
+        if name is not None:
+            data['name'] = name
+
+        if width is not None:
+            data['width'] = width
+
+        if image is not None:
+            image_data = image.getvalue()
+            image_data_encoded = base64.b64encode(image_data).decode('ascii')
+            data['image'] = image_data_encoded
+
+        if active_flag is not None:
+            data['active_flag'] = active_flag
+
+        if application_metadata is not None:
+            metadata_encoded_str = base64.b64encode(application_metadata)
+            metadata_encoded = metadata_encoded_str.decode('ascii')
+            data['application_metadata'] = metadata_encoded
+
+        content = bytes(json.dumps(data), encoding='utf-8')
+
+        self._make_request(
+            method='PUT',
+            content=content,
+            request_path=f'/targets/{target_id}',
+            expected_result_code='Success',
+        )

tests/test_exceptions.py

@@ -21,6 +21,7 @@
     MetadataTooLarge,
     ProjectInactive,
     TargetNameExist,
+    TargetStatusNotSuccess,
     TargetStatusProcessing,
     UnknownTarget,
 )
@@ -225,3 +226,23 @@ def test_authentication_failure(high_quality_image: io.BytesIO) -> None:
             )
 
         assert exc.value.response.status_code == codes.UNAUTHORIZED
+
+
+def test_target_status_not_success(
+    client: VWS,
+    high_quality_image: io.BytesIO,
+) -> None:
+    """
+    A ``TargetStatusNotSuccess`` exception is raised when updating a target
+    which has a status which is not "Success".
+    """
+    target_id = client.add_target(
+        name='x',
+        width=1,
+        image=high_quality_image,
+    )
+
+    with pytest.raises(TargetStatusNotSuccess) as exc:
+        client.update_target(target_id=target_id)
+
+    assert exc.value.response.status_code == codes.FORBIDDEN

tests/test_vws.py

@@ -429,3 +429,56 @@ def test_get_duplicate_targets(
         client.wait_for_target_processed(target_id=similar_target_id)
         duplicates = client.get_duplicate_targets(target_id=target_id)
         assert duplicates == [similar_target_id]
+
+
+class TestUpdateTarget:
+    """
+    Tests for updating a target.
+    """
+
+    def test_update_target(
+        self,
+        client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """
+        It is possible to update a target.
+        """
+        target_id = client.add_target(
+            name='x',
+            width=1,
+            image=high_quality_image,
+            active_flag=True,
+        )
+        client.wait_for_target_processed(target_id=target_id)
+        client.update_target(
+            target_id=target_id,
+            name='x2',
+            width=2,
+            active_flag=False,
+            # These will be tested in
+            # https://github.com/adamtheturtle/vws-python/issues/809.
+            image=high_quality_image,
+            application_metadata=b'a',
+        )
+
+        target_details = client.get_target_record(target_id=target_id)
+        assert target_details['name'] == 'x2'
+        assert target_details['width'] == 2
+        assert not target_details['active_flag']
+
+    def test_no_fields_given(
+        self,
+        client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """
+        It is possible to give no update fields.
+        """
+        target_id = client.add_target(
+            name='x',
+            width=1,
+            image=high_quality_image,
+        )
+        client.wait_for_target_processed(target_id=target_id)
+        client.update_target(target_id=target_id)