Progress

Author: adamtheturtle

src/vws/__init__.py

@@ -3,11 +3,12 @@
 """
 
 from ._version import get_versions
-from .query import CloudRecoService
+from .query import CloudRecoIncludeTargetData, CloudRecoService
 from .vws import VWS
 
 __all__ = [
     'CloudRecoService',
+    'CloudRecoIncludeTargetData',
     'VWS',
 ]
 

src/vws/query.py

@@ -3,6 +3,7 @@
 """
 
 import io
+from enum import Enum
 from typing import Any, Dict, List
 from urllib.parse import urljoin
 
@@ -14,6 +15,17 @@
 from .exceptions import MaxNumResultsOutOfRange
 
 
+class CloudRecoIncludeTargetData(Enum):
+    """
+    Options for the ``include_target_data`` parameter of
+    ``CloudRecoService.query``.
+    """
+
+    TOP = 'top'
+    NONE = 'none'
+    ALL = 'all'
+
+
 class CloudRecoService:
     """
     An interface to the Vuforia Cloud Recognition Web APIs.
@@ -39,6 +51,8 @@ def query(
         self,
         image: io.BytesIO,
         max_num_results: int = 1,
+        include_target_data:
+        CloudRecoIncludeTargetData = CloudRecoIncludeTargetData.TOP,
     ) -> List[Dict[str, Any]]:
         """
         Use the Vuforia Web Query API to make an Image Recognition Query.
@@ -49,6 +63,16 @@ def query(
 
         Args:
             image: The image to make a query against.
+            max_num_results: The maximum number of matching targets to be
+                returned.
+            include_target_data: "Indicates if target_data records shall be
+                returned for the matched targets. Accepted values are top
+                (default value, only return target_data for top ranked match),
+                none (return no target_data), all (for all matched targets)".
+
+        Raises:
+            MaxNumResultsOutOfRange: ``max_num_results`` is not within the
+            range (1, 50).
 
         Returns:
             An ordered list of target details of matching targets.
@@ -57,6 +81,8 @@ def query(
         body = {
             'image': ('image.jpeg', image_content, 'image/jpeg'),
             'max_num_results': (None, int(max_num_results), 'text/plain'),
+            'include_target_data':
+            (None, include_target_data.value, 'text/plain'),
         }
         date = rfc_1123_date()
         request_path = '/v1/query'

tests/test_query.py

@@ -9,7 +9,7 @@
 from mock_vws import MockVWS
 from mock_vws.database import VuforiaDatabase
 
-from vws import VWS, CloudRecoService
+from vws import VWS, CloudRecoIncludeTargetData, CloudRecoService
 from vws.exceptions import MaxNumResultsOutOfRange
 
 
@@ -180,6 +180,9 @@ def test_default(
         cloud_reco_client: CloudRecoService,
         high_quality_image: io.BytesIO,
     ) -> None:
+        """
+        By default, target data is only returned in the top match.
+        """
         target_id = vws_client.add_target(
             name=uuid.uuid4().hex,
             width=1,
@@ -205,6 +208,10 @@ def test_top(
         cloud_reco_client: CloudRecoService,
         high_quality_image: io.BytesIO,
     ) -> None:
+        """
+        When ``CloudRecoIncludeTargetData.TOP`` is given, target data is only
+        returned in the top match.
+        """
         target_id = vws_client.add_target(
             name=uuid.uuid4().hex,
             width=1,
@@ -220,6 +227,7 @@ def test_top(
         top_match, second_match = cloud_reco_client.query(
             image=high_quality_image,
             max_num_results=2,
+            include_target_data=CloudRecoIncludeTargetData.TOP,
         )
         assert 'target_data' in top_match
         assert 'target_data' not in second_match
@@ -230,6 +238,10 @@ def test_none(
         cloud_reco_client: CloudRecoService,
         high_quality_image: io.BytesIO,
     ) -> None:
+        """
+        When ``CloudRecoIncludeTargetData.NONE`` is given, target data is not
+        returned in any match.
+        """
         target_id = vws_client.add_target(
             name=uuid.uuid4().hex,
             width=1,
@@ -245,6 +257,7 @@ def test_none(
         top_match, second_match = cloud_reco_client.query(
             image=high_quality_image,
             max_num_results=2,
+            include_target_data=CloudRecoIncludeTargetData.NONE,
         )
         assert 'target_data' not in top_match
         assert 'target_data' not in second_match
@@ -255,6 +268,10 @@ def test_all(
         cloud_reco_client: CloudRecoService,
         high_quality_image: io.BytesIO,
     ) -> None:
+        """
+        When ``CloudRecoIncludeTargetData.ALL`` is given, target data is
+        returned in all matches.
+        """
         target_id = vws_client.add_target(
             name=uuid.uuid4().hex,
             width=1,
@@ -270,6 +287,7 @@ def test_all(
         top_match, second_match = cloud_reco_client.query(
             image=high_quality_image,
             max_num_results=2,
+            include_target_data=CloudRecoIncludeTargetData.ALL,
         )
         assert 'target_data' in top_match
         assert 'target_data' in second_match