Merge remote-tracking branch 'origin/master' into query-2

Author: adamtheturtle

requirements.txt

@@ -1,2 +1,3 @@
 requests==2.22.0
 timeout-decorator==0.4.1
+urllib3==1.25.3

src/vws/query.py

@@ -1,5 +1,9 @@
+"""
+Tools for interacting with the Vuforia Cloud Recognition Web APIs.
+"""
+
 import io
-import json
+from typing import Any, Dict, List
 from urllib.parse import urljoin
 
 import requests
@@ -13,7 +17,7 @@
 
 class CloudRecoService:
     """
-    TODO
+    An interface to the Vuforia Cloud Recognition Web APIs.
     """
 
     def __init__(
@@ -37,9 +41,19 @@ def query(
         self,
         image: io.BytesIO,
         max_num_results: int = 1,
-    ) -> str:
+    ) -> List[Dict[str, Any]]:
         """
-        TODO docstring
+        Use the Vuforia Web Query API to make an Image Recognition Query.
+
+        See
+        https://library.vuforia.com/articles/Solution/How-To-Perform-an-Image-Recognition-Query
+        for parameter details.
+
+        Args:
+            image: The image to make a query against.
+
+        Returns:
+            An ordered list of target details of matching targets.
         """
         image_content = image.getvalue()
         body = {
@@ -79,4 +93,4 @@ def query(
             raise MaxNumResultsOutOfRange(response=response)
 
         raise_for_result_code(response=response, expected_result_code='Success')
-        return response.json()['results']
+        return list(response.json()['results'])

tests/conftest.py

@@ -29,7 +29,7 @@ def _mock_database() -> Iterator[VuforiaDatabase]:
 @pytest.fixture()
 def vws_client(_mock_database: VuforiaDatabase) -> Iterator[VWS]:
     """
-    Yield a VWS client which connects to a mock.
+    Yield a VWS client which connects to a mock database.
     """
     yield VWS(
         server_access_key=_mock_database.server_access_key,
@@ -38,9 +38,10 @@ def vws_client(_mock_database: VuforiaDatabase) -> Iterator[VWS]:
 
 
 @pytest.fixture()
-def cloud_reco_client(_mock_database: VuforiaDatabase) -> Iterator[VWS]:
+def cloud_reco_client(_mock_database: VuforiaDatabase,
+                      ) -> Iterator[CloudRecoService]:
     """
-    TODO Docstring
+    Yield a ``CloudRecoService`` client which connects to a mock database.
     """
     yield CloudRecoService(
         client_access_key=_mock_database.client_access_key,

tests/test_query.py

@@ -1,5 +1,5 @@
 """
-TODO
+Tests for the ``CloudRecoService`` querying functionality.
 """
 
 import io
@@ -14,7 +14,7 @@
 
 class TestQuery:
     """
-    TODO
+    Tests for making image queries.
     """
 
     def test_no_matches(