Merge pull request #1041 from adamtheturtle/include-target-data

Include target data

Author: adamtheturtle

docs/source/conf.py

@@ -76,6 +76,7 @@
 html_show_copyright = False
 html_show_sphinx = False
 html_show_sourcelink = False
+autoclass_content = 'both'
 
 html_theme_options = {
     'show_powered_by': 'false',

docs/source/index.rst

@@ -15,6 +15,11 @@ Reference
 ---------
 
 .. automodule:: vws
+   :undoc-members:
+   :members:
+
+.. automodule:: vws.include_target_data
+   :undoc-members:
    :members:
 
 .. toctree::

spelling_private_dict.txt

@@ -1,6 +1,7 @@
 AuthenticationFailure
 BadImage
 ImageTooLarge
+MaxNumResultsOutOfRange
 MetadataTooLarge
 ProjectInactive
 TargetNameExist

src/vws/include_target_data.py

@@ -0,0 +1,15 @@
+"""
+Tools for managing ``CloudRecoService.query``'s ``include_target_data``.
+"""
+
+from enum import Enum
+
+
+class CloudRecoIncludeTargetData(Enum):
+    """
+    Options for the ``include_target_data`` parameter of foo.
+    """
+
+    TOP = 'top'
+    NONE = 'none'
+    ALL = 'all'

src/vws/query.py

@@ -12,6 +12,7 @@
 from ._authorization import authorization_header, rfc_1123_date
 from ._result_codes import raise_for_result_code
 from .exceptions import MaxNumResultsOutOfRange
+from .include_target_data import CloudRecoIncludeTargetData
 
 
 class CloudRecoService:
@@ -39,6 +40,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 +52,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:
+            ~vws.exceptions.MaxNumResultsOutOfRange: `max_num_results`` is not
+                within the range (1, 50).
 
         Returns:
             An ordered list of target details of matching targets.
@@ -57,6 +70,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

@@ -11,6 +11,7 @@
 
 from vws import VWS, CloudRecoService
 from vws.exceptions import MaxNumResultsOutOfRange
+from vws.include_target_data import CloudRecoIncludeTargetData
 
 
 class TestQuery:
@@ -167,3 +168,127 @@ def test_too_many(
             'Accepted range is from 1 to 50 (inclusive).'
         )
         assert str(exc.value) == exc.value.response.text == expected_value
+
+
+class TestIncludeTargetData:
+    """
+    Tests for the ``include_target_data`` parameter of ``query``.
+    """
+
+    def test_default(
+        self,
+        vws_client: VWS,
+        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,
+            image=high_quality_image,
+        )
+        target_id_2 = vws_client.add_target(
+            name=uuid.uuid4().hex,
+            width=1,
+            image=high_quality_image,
+        )
+        vws_client.wait_for_target_processed(target_id=target_id)
+        vws_client.wait_for_target_processed(target_id=target_id_2)
+        top_match, second_match = cloud_reco_client.query(
+            image=high_quality_image,
+            max_num_results=2,
+        )
+        assert 'target_data' in top_match
+        assert 'target_data' not in second_match
+
+    def test_top(
+        self,
+        vws_client: VWS,
+        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,
+            image=high_quality_image,
+        )
+        target_id_2 = vws_client.add_target(
+            name=uuid.uuid4().hex,
+            width=1,
+            image=high_quality_image,
+        )
+        vws_client.wait_for_target_processed(target_id=target_id)
+        vws_client.wait_for_target_processed(target_id=target_id_2)
+        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
+
+    def test_none(
+        self,
+        vws_client: VWS,
+        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,
+            image=high_quality_image,
+        )
+        target_id_2 = vws_client.add_target(
+            name=uuid.uuid4().hex,
+            width=1,
+            image=high_quality_image,
+        )
+        vws_client.wait_for_target_processed(target_id=target_id)
+        vws_client.wait_for_target_processed(target_id=target_id_2)
+        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
+
+    def test_all(
+        self,
+        vws_client: VWS,
+        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,
+            image=high_quality_image,
+        )
+        target_id_2 = vws_client.add_target(
+            name=uuid.uuid4().hex,
+            width=1,
+            image=high_quality_image,
+        )
+        vws_client.wait_for_target_processed(target_id=target_id)
+        vws_client.wait_for_target_processed(target_id=target_id_2)
+        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