Merge pull request #1145 from adamtheturtle/query-result-obj

Query result obj

Author: adamtheturtle

src/vws/query.py

@@ -2,21 +2,23 @@
 Tools for interacting with the Vuforia Cloud Recognition Web APIs.
 """
 
+import datetime
 import io
-from typing import Any, Dict, List
+from typing import List, Optional
 from urllib.parse import urljoin
 
 import requests
 from urllib3.filepost import encode_multipart_formdata
 from vws_auth_tools import authorization_header, rfc_1123_date
 
-from ._result_codes import raise_for_result_code
-from .exceptions import (
+from vws._result_codes import raise_for_result_code
+from vws.exceptions import (
     ConnectionErrorPossiblyImageTooLarge,
     MatchProcessing,
     MaxNumResultsOutOfRange,
 )
-from .include_target_data import CloudRecoIncludeTargetData
+from vws.include_target_data import CloudRecoIncludeTargetData
+from vws.reports import QueryResult, TargetData
 
 
 class CloudRecoService:
@@ -46,7 +48,7 @@ def query(
         max_num_results: int = 1,
         include_target_data:
         CloudRecoIncludeTargetData = CloudRecoIncludeTargetData.TOP,
-    ) -> List[Dict[str, Any]]:
+    ) -> List[QueryResult]:
         """
         Use the Vuforia Web Query API to make an Image Recognition Query.
 
@@ -132,4 +134,28 @@ def query(
             response=response,
             expected_result_code='Success',
         )
-        return list(response.json()['results'])
+
+        result = []
+        result_list = list(response.json()['results'])
+        for item in result_list:
+            target_data: Optional[TargetData] = None
+            if 'target_data' in item:
+                target_data_dict = item['target_data']
+                metadata = target_data_dict['application_metadata']
+                timestamp_string = target_data_dict['target_timestamp']
+                target_timestamp = datetime.datetime.utcfromtimestamp(
+                    timestamp_string,
+                )
+                target_data = TargetData(
+                    name=target_data_dict['name'],
+                    application_metadata=metadata,
+                    target_timestamp=target_timestamp,
+                )
+
+            query_result = QueryResult(
+                target_id=item['target_id'],
+                target_data=target_data,
+            )
+
+            result.append(query_result)
+        return result

src/vws/reports.py

@@ -5,6 +5,7 @@
 import datetime
 from dataclasses import dataclass
 from enum import Enum
+from typing import Optional
 
 
 @dataclass
@@ -77,3 +78,27 @@ class TargetRecord:
     width: float
     tracking_rating: int
     reco_rating: str
+
+
+@dataclass
+class TargetData:
+    """
+    The target data optionally included with a query match.
+    """
+
+    name: str
+    application_metadata: Optional[str]
+    target_timestamp: datetime.datetime
+
+
+@dataclass
+class QueryResult:
+    """
+    One query match result.
+
+    See
+    https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query.
+    """
+
+    target_id: str
+    target_data: Optional[TargetData]

tests/test_query.py

@@ -51,7 +51,7 @@ def test_match(
         )
         vws_client.wait_for_target_processed(target_id=target_id)
         [matching_target] = cloud_reco_client.query(image=high_quality_image)
-        assert matching_target['target_id'] == target_id
+        assert matching_target.target_id == target_id
 
     def test_too_large(
         self,
@@ -101,8 +101,10 @@ def test_custom_base_url(self, high_quality_image: io.BytesIO) -> None:
                 base_vwq_url=base_vwq_url,
             )
 
-            [match] = cloud_reco_client.query(image=high_quality_image)
-            assert match['target_id'] == target_id
+            matches = cloud_reco_client.query(image=high_quality_image)
+            assert len(matches) == 1
+            match = matches[0]
+            assert match.target_id == target_id
 
 
 class TestMaxNumResults:
@@ -233,8 +235,8 @@ def test_default(
             image=high_quality_image,
             max_num_results=2,
         )
-        assert 'target_data' in top_match
-        assert 'target_data' not in second_match
+        assert top_match.target_data is not None
+        assert second_match.target_data is None
 
     def test_top(
         self,
@@ -267,8 +269,8 @@ def test_top(
             max_num_results=2,
             include_target_data=CloudRecoIncludeTargetData.TOP,
         )
-        assert 'target_data' in top_match
-        assert 'target_data' not in second_match
+        assert top_match.target_data is not None
+        assert second_match.target_data is None
 
     def test_none(
         self,
@@ -301,8 +303,8 @@ def test_none(
             max_num_results=2,
             include_target_data=CloudRecoIncludeTargetData.NONE,
         )
-        assert 'target_data' not in top_match
-        assert 'target_data' not in second_match
+        assert top_match.target_data is None
+        assert second_match.target_data is None
 
     def test_all(
         self,
@@ -335,5 +337,5 @@ def test_all(
             max_num_results=2,
             include_target_data=CloudRecoIncludeTargetData.ALL,
         )
-        assert 'target_data' in top_match
-        assert 'target_data' in second_match
+        assert top_match.target_data is not None
+        assert second_match.target_data is not None

tests/test_vws.py

@@ -65,9 +65,9 @@ def test_add_target(
         matching_targets = cloud_reco_client.query(image=high_quality_image)
         if active_flag:
             [matching_target] = matching_targets
-            assert matching_target['target_id'] == target_id
-            query_target_data = matching_target['target_data']
-            query_metadata = query_target_data['application_metadata']
+            assert matching_target.target_id == target_id
+            assert matching_target.target_data is not None
+            query_metadata = matching_target.target_data.application_metadata
             assert query_metadata == encoded_metadata
         else:
             assert matching_targets == []
@@ -500,9 +500,10 @@ def test_update_target(
         )
         vws_client.wait_for_target_processed(target_id=target_id)
         [matching_target] = cloud_reco_client.query(image=high_quality_image)
-        assert matching_target['target_id'] == target_id
-        query_target_data = matching_target['target_data']
-        query_metadata = query_target_data['application_metadata']
+        assert matching_target.target_id == target_id
+        query_target_data = matching_target.target_data
+        assert query_target_data is not None
+        query_metadata = query_target_data.application_metadata
         assert query_metadata is None
 
         new_name = uuid.uuid4().hex
@@ -521,9 +522,10 @@ def test_update_target(
         [
             matching_target,
         ] = cloud_reco_client.query(image=different_high_quality_image)
-        assert matching_target['target_id'] == target_id
-        query_target_data = matching_target['target_data']
-        query_metadata = query_target_data['application_metadata']
+        assert matching_target.target_id == target_id
+        query_target_data = matching_target.target_data
+        assert query_target_data is not None
+        query_metadata = query_target_data.application_metadata
         assert query_metadata == new_application_metadata
 
         vws_client.update_target(