Merge remote-tracking branch 'origin/master' into client

Author: adamtheturtle

README.rst

@@ -15,6 +15,33 @@ Installation
 This is tested on Python 3.7+.
 Get in touch with ``adamdangoor@gmail.com`` if you would like to use this with another language.
 
+Getting Started
+---------------
+
+.. code:: python
+
+   import io
+
+   from vws import VWS, CloudRecoService
+
+   vws_client = VWS(server_access_key='...', server_secret_key='...')
+   cloud_reco_client = CloudRecoService(client_access_key='...', client_secret_key='...')
+   name = 'my_image_name'
+
+   with open('/path/to/image.png', 'rb') as my_image_file:
+      my_image = io.BytesIO(my_image_file.read())
+
+   target_id = vws_client.add_target(
+       name=name,
+       width=1,
+       image=my_image,
+   )
+   vws_client.wait_for_target_processed(target_id=target_id)
+   matching_targets = cloud_reco_client.query(image=my_image)
+
+   assert matching_targets[0]['target_id'] == target_id
+
+
 Full Documentation
 ------------------
 

dev-requirements.txt

@@ -1,30 +1,30 @@
-autoflake==1.3
+autoflake==1.3.1
 check-manifest==0.39
 codecov==2.0.15 # Upload coverage data
 doc8==0.8.0
 dodgy==0.1.9  # Look for uploaded secrets
-dulwich==0.19.11
+dulwich==0.19.13
 flake8-commas==2.0.0  # Require silicon valley commas
-flake8-quotes==2.0.1  # Require single quotes
+flake8-quotes==2.1.0  # Require single quotes
 flake8==3.7.8  # Lint
 freezegun==0.3.12
 isort==4.3.21  # Lint imports
-mypy==0.720  # Type checking
+mypy==0.730  # Type checking
 pip_check_reqs==2.0.3
-pydocstyle==4.0.0  # Lint docstrings
+pydocstyle==4.0.1  # Lint docstrings
 pyenchant==2.0.0  # Bindings for a spellchecking sytem
 pygithub==1.43.8
 Pygments==2.4.2
-pylint==2.3.1  # Lint
+pylint==2.4.2  # Lint
 pyroma==2.5  # Packaging best practices checker
 pytest-cov==2.7.1  # Measure code coverage
-pytest==5.0.1  # Test runners
-PyYAML==5.1.1
-Sphinx==2.1.2
-sphinx-autodoc-typehints==1.7.0
+pytest==5.2.0  # Test runners
+PyYAML==5.1.2
+Sphinx==2.2.0
+sphinx-autodoc-typehints==1.8.0
 sphinxcontrib-spelling==4.3.0
-twine==1.13.0
+twine==2.0.0
 versioneer==0.18
-vulture==1.0
-VWS-Python-Mock==2018.12.1.0
+vulture==1.1
+VWS-Python-Mock==2019.9.28.0
 yapf==0.28.0  # Automatic formatting for Python

requirements.txt

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

spelling_private_dict.txt

@@ -1,5 +1,6 @@
 AuthenticationFailure
 BadImage
+ConnectionErrorPossiblyImageTooLarge
 ImageTooLarge
 MatchProcessing
 MaxNumResultsOutOfRange
@@ -11,6 +12,7 @@ TargetProcessingTimeout
 TargetStatusProcessing
 Ubuntu
 UnknownTarget
+UnknownVWSErrorPossiblyBadName
 api
 args
 ascii

src/vws/_result_codes.py

@@ -2,6 +2,8 @@
 Tools for managing result codes.
 """
 
+import json
+
 from requests import Response
 
 from vws.exceptions import (
@@ -18,6 +20,7 @@
     TargetStatusNotSuccess,
     TargetStatusProcessing,
     UnknownTarget,
+    UnknownVWSErrorPossiblyBadName,
 )
 
 
@@ -33,8 +36,18 @@ def raise_for_result_code(
         response: A response from Vuforia.
         expected_result_code: See
             https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API.html#How-To-Interperete-VWS-API-Result-Codes
+
+    Raises:
+        ~vws.exceptions.UnknownVWSErrorPossiblyBadName: Vuforia returns an HTML
+            page with the text "Oops, an error occurred". This has been seen to
+            happen when the given name includes a bad character.
     """
-    result_code = response.json()['result_code']
+    try:
+        result_code = response.json()['result_code']
+    except json.decoder.JSONDecodeError as exc:
+        assert 'Oops' in response.text
+        raise UnknownVWSErrorPossiblyBadName() from exc
+
     if result_code == expected_result_code:
         return
 

src/vws/exceptions.py

@@ -2,9 +2,28 @@
 Custom exceptions for Vuforia errors.
 """
 
+import requests
 from requests import Response
 
 
+class UnknownVWSErrorPossiblyBadName(Exception):
+    """
+    Exception raised when VWS returns an HTML page which says "Oops, an error
+    occurred".
+
+    This has been seen to happen when the given name includes a bad character.
+    """
+
+
+class ConnectionErrorPossiblyImageTooLarge(
+    requests.exceptions.ConnectionError,
+):
+    """
+    Exception raised when a ConnectionError is raised from a query. This has
+    been seen to happen when the given image is too large.
+    """
+
+
 class MatchProcessing(Exception):
     """
     Exception raised when a query is made with an image which matches a target

src/vws/query.py

@@ -11,7 +11,11 @@
 
 from ._authorization import authorization_header, rfc_1123_date
 from ._result_codes import raise_for_result_code
-from .exceptions import MatchProcessing, MaxNumResultsOutOfRange
+from .exceptions import (
+    ConnectionErrorPossiblyImageTooLarge,
+    MatchProcessing,
+    MaxNumResultsOutOfRange,
+)
 from .include_target_data import CloudRecoIncludeTargetData
 
 
@@ -68,6 +72,8 @@ def query(
                 which was recently added, updated or deleted and Vuforia
                 returns an error in this case.
             ~vws.exceptions.ProjectInactive: The project is inactive.
+            ~vws.exceptions.ConnectionErrorPossiblyImageTooLarge: The given
+                image is too large.
 
         Returns:
             An ordered list of target details of matching targets.
@@ -101,12 +107,15 @@ def query(
             'Content-Type': content_type_header,
         }
 
-        response = requests.request(
-            method=method,
-            url=urljoin(base=self._base_vwq_url, url=request_path),
-            headers=headers,
-            data=content,
-        )
+        try:
+            response = requests.request(
+                method=method,
+                url=urljoin(base=self._base_vwq_url, url=request_path),
+                headers=headers,
+                data=content,
+            )
+        except requests.exceptions.ConnectionError as exc:
+            raise ConnectionErrorPossiblyImageTooLarge from exc
 
         if 'Integer out of range' in response.text:
             raise MaxNumResultsOutOfRange(response=response)

src/vws/vws.py

@@ -178,6 +178,10 @@ def add_target(
             ~vws.exceptions.ProjectInactive: The project is inactive.
             ~vws.exceptions.RequestTimeTooSkewed: There is an error with the
                 time sent to Vuforia.
+            ~vws.exceptions.UnknownVWSErrorPossiblyBadName: Vuforia returns an
+                HTML page with the text "Oops, an error occurred". This has
+                been seen to happen when the given name includes a bad
+                character.
         """
         image_data = image.getvalue()
         image_data_encoded = base64.b64encode(image_data).decode('ascii')

tests/test_exceptions.py

@@ -25,6 +25,7 @@
     TargetStatusNotSuccess,
     TargetStatusProcessing,
     UnknownTarget,
+    UnknownVWSErrorPossiblyBadName,
 )
 
 
@@ -52,6 +53,17 @@ def test_invalid_given_id(vws_client: VWS) -> None:
     assert exc.value.response.status_code == codes.NOT_FOUND
 
 
+def test_add_bad_name(vws_client: VWS, high_quality_image: io.BytesIO) -> None:
+    """
+    When a name with a bad character is given, an
+    ``UnknownVWSErrorPossiblyBadName`` exception is raised.
+    """
+    max_char_value = 65535
+    bad_name = chr(max_char_value + 1)
+    with pytest.raises(UnknownVWSErrorPossiblyBadName):
+        vws_client.add_target(name=bad_name, width=1, image=high_quality_image)
+
+
 def test_request_quota_reached() -> None:
     """
     See https://github.com/adamtheturtle/vws-python/issues/822 for writing
@@ -262,20 +274,14 @@ def test_match_processing(
     high_quality_image: io.BytesIO,
 ) -> None:
     """
-    A ``MatchProcessing`` exception is raised when a deleted target is matched.
+    A ``MatchProcessing`` exception is raised when a target in processing is
+    matched.
     """
-    target_id = vws_client.add_target(
+    vws_client.add_target(
         name='x',
         width=1,
         image=high_quality_image,
     )
     with pytest.raises(MatchProcessing) as exc:
         cloud_reco_client.query(image=high_quality_image)
     assert exc.value.response.status_code == codes.INTERNAL_SERVER_ERROR
-    vws_client.wait_for_target_processed(target_id=target_id)
-    cloud_reco_client.query(image=high_quality_image)
-    vws_client.delete_target(target_id=target_id)
-    with pytest.raises(MatchProcessing) as exc:
-        cloud_reco_client.query(image=high_quality_image)
-
-    assert exc.value.response.status_code == codes.INTERNAL_SERVER_ERROR

tests/test_query.py

@@ -10,7 +10,10 @@
 from mock_vws.database import VuforiaDatabase
 
 from vws import VWS, CloudRecoService
-from vws.exceptions import MaxNumResultsOutOfRange
+from vws.exceptions import (
+    ConnectionErrorPossiblyImageTooLarge,
+    MaxNumResultsOutOfRange,
+)
 from vws.include_target_data import CloudRecoIncludeTargetData
 
 
@@ -48,6 +51,18 @@ def test_match(
         [matching_target] = cloud_reco_client.query(image=high_quality_image)
         assert matching_target['target_id'] == target_id
 
+    def test_too_large(
+        self,
+        cloud_reco_client: CloudRecoService,
+        png_too_large: io.BytesIO,
+    ) -> None:
+        """
+        A ``ConnectionErrorPossiblyImageTooLarge`` exception is raised if an
+        image which is too large is given.
+        """
+        with pytest.raises(ConnectionErrorPossiblyImageTooLarge):
+            cloud_reco_client.query(image=png_too_large)
+
 
 class TestCustomBaseVWQURL:
     """