Merge remote-tracking branch 'origin/master' into delete-document-errors

Author: adamtheturtle

src/vws/vws.py

@@ -190,7 +190,8 @@ def add_target(
         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.
+        https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API#How-To-Add-a-Target
+        for parameter details.
 
         Args:
             name: The name of the target.
@@ -275,14 +276,18 @@ def get_target_record(self, target_id: str) -> Dict[str, Union[str, int]]:
 
         return dict(response.json()['target_record'])
 
-    @timeout_decorator.timeout(seconds=60 * 5)
-    def wait_for_target_processed(self, target_id: str) -> None:
+    def _wait_for_target_processed(
+        self,
+        target_id: str,
+        seconds_between_requests: float,
+    ) -> None:
         """
-        Wait up to five minutes (arbitrary) for a target to get past the
-        processing stage.
+        Wait indefinitely for a target to get past the processing stage.
 
         Args:
             target_id: The ID of the target to wait for.
+            seconds_between_requests: The number of seconds to wait between
+                requests made while polling the target status.
 
         Raises:
             ~vws.exceptions.AuthenticationFailure: The secret key is not
@@ -299,10 +304,35 @@ def wait_for_target_processed(self, target_id: str) -> None:
             if report['status'] != 'processing':
                 return
 
-            # We wait 0.2 seconds rather than less than that to decrease the
-            # number of calls made to the API, to decrease the likelihood of
-            # hitting the request quota.
-            sleep(0.2)
+            sleep(seconds_between_requests)
+
+    @timeout_decorator.timeout(seconds=60 * 5)
+    def wait_for_target_processed(self, target_id: str) -> None:
+        """
+        Wait up to five minutes (arbitrary) for a target to get past the
+        processing stage.
+
+        Args:
+            target_id: The ID of the target to wait for.
+
+        Raises:
+            ~vws.exceptions.AuthenticationFailure: The secret key is not
+                correct.
+            ~vws.exceptions.Fail: There was an error with the request. For
+                example, the given access key does not match a known database.
+            TimeoutError: The target remained in the processing stage for more
+                than five minutes.
+            ~vws.exceptions.UnknownTarget: The given target ID does not match a
+                target in the database.
+        """
+        # We wait 0.2 seconds rather than less than that to decrease the
+        # number of calls made to the API, to decrease the likelihood of
+        # hitting the request quota.
+        seconds_between_requests = 0.2
+        self._wait_for_target_processed(
+            target_id=target_id,
+            seconds_between_requests=seconds_between_requests,
+        )
 
     def list_targets(self) -> List[str]:
         """
@@ -413,3 +443,34 @@ def delete_target(self, target_id: str) -> None:
             request_path=f'/targets/{target_id}',
             expected_result_code='Success',
         )
+
+    def get_duplicate_targets(self, target_id: str) -> List[str]:
+        """
+        Get targets which may be considered duplicates of a given target.
+
+        See
+        https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API.html#How-To-Check-for-Duplicate-Targets.
+
+        Args:
+            target_id: The ID of the target to delete.
+
+        Returns:
+            The target IDs of duplicate targets.
+
+        Raises:
+            ~vws.exceptions.AuthenticationFailure: The secret key is not
+                correct.
+            ~vws.exceptions.Fail: There was an error with the request. For
+                example, the given access key does not match a known database.
+            ~vws.exceptions.UnknownTarget: The given target ID does not match a
+                target in the database.
+            ~vws.exceptions.ProjectInactive: The project is inactive.
+        """
+        response = self._make_request(
+            method='GET',
+            content=b'',
+            request_path=f'/duplicates/{target_id}',
+            expected_result_code='Success',
+        )
+
+        return list(response.json()['similar_targets'])

tests/test_vws.py

@@ -1,5 +1,5 @@
 """
-Tests for helper function for adding a target to a Vuforia database.
+Tests for helper functions for managing a Vuforia database.
 """
 
 import io
@@ -278,3 +278,33 @@ def test_wait_for_target_processed(
         client.wait_for_target_processed(target_id=target_id)
         report = client.get_target_summary_report(target_id=target_id)
         assert report['status'] != 'processing'
+
+
+class TestGetDuplicateTargets:
+    """
+    Tests for getting duplicate targets.
+    """
+
+    def test_get_duplicate_targets(
+        self,
+        client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """
+        It is possible to get the IDs of similar targets.
+        """
+        target_id = client.add_target(
+            name='x',
+            width=1,
+            image=high_quality_image,
+        )
+        similar_target_id = client.add_target(
+            name='a',
+            width=1,
+            image=high_quality_image,
+        )
+
+        client.wait_for_target_processed(target_id=target_id)
+        client.wait_for_target_processed(target_id=similar_target_id)
+        duplicates = client.get_duplicate_targets(target_id=target_id)
+        assert duplicates == [similar_target_id]