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

adamtheturtle · adamtheturtle · commit 7ba6f87973b6 · 2019-07-31T09:38:48.000+01:00
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -6,5 +6,8 @@ Changelog
 Next
 ----
 
+2018.12.10.0
+------------
+
 2018.10.05.0
 ------------
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,2 +1,3 @@
 include versioneer.py
 include src/vws/_version.py
+include src/vws/py.typed
diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -1,29 +1,29 @@
-autoflake==1.2
-check-manifest==0.37
+autoflake==1.3
+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.6
+dulwich==0.19.11
 flake8-commas==2.0.0  # Require silicon valley commas
-flake8-quotes==1.0.0  # Require single quotes
-flake8==3.5.0  # Lint
-isort==4.3.4  # Lint imports
-mypy==0.630  # Type checking
+flake8-quotes==2.0.1  # Require single quotes
+flake8==3.7.8  # Lint
+isort==4.3.21  # Lint imports
+mypy==0.720  # Type checking
 pip_check_reqs==2.0.3
-pydocstyle==2.1.1  # Lint docstrings
+pydocstyle==4.0.0  # Lint docstrings
 pyenchant==2.0.0  # Bindings for a spellchecking sytem
-pygithub==1.43.2
-Pygments==2.2.0
-pylint==2.1.1  # Lint
-pyroma==2.4  # Packaging best practices checker
-pytest-cov==2.6.0  # Measure code coverage
-pytest==3.8.2  # Test runners
-PyYAML==3.13
-Sphinx==1.8.1
-sphinx-autodoc-typehints==1.3.0
-sphinxcontrib-spelling==4.2.0
-twine==1.12.1
+pygithub==1.43.8
+Pygments==2.4.2
+pylint==2.3.1  # 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
+sphinxcontrib-spelling==4.3.0
+twine==1.13.0
 versioneer==0.18
-vulture==0.29
-VWS-Python-Mock==2018.10.02.0
-yapf==0.24.0  # Automatic formatting for Python
+vulture==1.0
+VWS-Python-Mock==2018.12.1.0
+yapf==0.28.0  # Automatic formatting for Python
diff --git a/docs/source/conf.py b/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',
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -14,7 +14,7 @@ Install Python dependencies in a virtual environment.
 
 .. code:: sh
 
-    pip install --editable .[dev]
+    pip install --editable '.[dev]'
 
 Spell checking requires ``enchant``.
 This can be installed on macOS, for example, with `Homebrew <https://brew.sh>`__:
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -15,6 +15,11 @@ Reference
 ---------
 
 .. automodule:: vws
+   :undoc-members:
+   :members:
+
+.. automodule:: vws.include_target_data
+   :undoc-members:
    :members:
 
 .. toctree::
diff --git a/requirements.txt b/requirements.txt
@@ -1,2 +1,3 @@
-requests==2.19.1
-timeout-decorator==0.4.0
+requests==2.22.0
+timeout-decorator==0.4.1
+urllib3==1.25.3
diff --git a/setup.cfg b/setup.cfg
@@ -73,6 +73,7 @@ disallow_untyped_defs = True
 follow_imports = silent
 ignore_missing_imports = True
 no_implicit_optional = True
+strict_equality = True
 strict_optional = True
 warn_no_return = True
 warn_redundant_casts = True
@@ -88,6 +89,7 @@ ignore_errors = True
 #   - D200
 #   - D205
 #   - D400
+#   - D415
 # We don't want blank lines before class docstrings
 #   - D203
 # We don't need docstrings to start at the first line
@@ -101,7 +103,7 @@ ignore_errors = True
 # No blank line is needed after the last section
 # Do not care about imperative mood
 #   - D401
-ignore = D200,D202,D203,D205,D212,D400,D406,D407,D413,D401
+ignore = D200,D202,D203,D205,D212,D400,D406,D407,D413,D401,D415
 match=(?!.*(versioneer|test_|_version)).*\.py
 
 [isort]
@@ -116,3 +118,4 @@ omit =
 
 [yapf]
 DEDENT_CLOSING_BRACKETS = true
+BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF = true
diff --git a/setup.py b/setup.py
@@ -1,8 +1,9 @@
 """Setup script for VWS Python, a wrapper for Vuforia's Web Services APIs."""
 
-import versioneer
 from setuptools import find_packages, setup
 
+import versioneer
+
 # We use requirements.txt instead of just declaring the requirements here
 # because this helps with Docker package caching.
 with open('requirements.txt') as requirements:
@@ -39,5 +40,6 @@
         'Environment :: Web Environment',
         'License :: OSI Approved :: MIT License',
         'Programming Language :: Python :: 3.7',
+        'Development Status :: 3 - Alpha',
     ],
 )
diff --git a/spelling_private_dict.txt b/spelling_private_dict.txt
@@ -1,6 +1,7 @@
 AuthenticationFailure
 BadImage
 ImageTooLarge
+MaxNumResultsOutOfRange
 MetadataTooLarge
 ProjectInactive
 TargetNameExist
diff --git a/src/vws/__init__.py b/src/vws/__init__.py
@@ -2,12 +2,14 @@
 A library for Vuforia Web Services.
 """
 
+from ._version import get_versions
+from .query import CloudRecoService
 from .vws import VWS
 
 __all__ = [
+    'CloudRecoService',
     'VWS',
 ]
 
-from ._version import get_versions
 __version__ = get_versions()['version']  # type: ignore
 del get_versions
diff --git a/src/vws/_result_codes.py b/src/vws/_result_codes.py
@@ -0,0 +1,52 @@
+"""
+Tools for managing result codes.
+"""
+
+from requests import Response
+
+from vws.exceptions import (
+    AuthenticationFailure,
+    BadImage,
+    Fail,
+    ImageTooLarge,
+    MetadataTooLarge,
+    ProjectInactive,
+    TargetNameExist,
+    TargetStatusNotSuccess,
+    TargetStatusProcessing,
+    UnknownTarget,
+)
+
+
+def raise_for_result_code(
+    response: Response,
+    expected_result_code: str,
+) -> None:
+    """
+    Raise an appropriate exception if the expected result code for a successful
+    request is not returned.
+
+    Args:
+        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
+    """
+    result_code = response.json()['result_code']
+    if result_code == expected_result_code:
+        return
+
+    exception = {
+        'AuthenticationFailure': AuthenticationFailure,
+        'BadImage': BadImage,
+        'Fail': Fail,
+        'ImageTooLarge': ImageTooLarge,
+        'MetadataTooLarge': MetadataTooLarge,
+        'ProjectInactive': ProjectInactive,
+        'InactiveProject': ProjectInactive,
+        'TargetNameExist': TargetNameExist,
+        'TargetStatusProcessing': TargetStatusProcessing,
+        'TargetStatusNotSuccess': TargetStatusNotSuccess,
+        'UnknownTarget': UnknownTarget,
+    }[result_code]
+
+    raise exception(response=response)
diff --git a/src/vws/exceptions.py b/src/vws/exceptions.py
@@ -5,6 +5,50 @@
 from requests import Response
 
 
+class MatchProcessing(Exception):
+    """
+    Exception raised when a query is made with an image which matches a target
+    which is processing or has recently been deleted.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to Vuforia.
+        """
+        super().__init__()
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """
+        The response returned by Vuforia which included this error.
+        """
+        return self._response
+
+
+class MaxNumResultsOutOfRange(Exception):
+    """
+    Exception raised when the ``max_num_results`` given to the Cloud
+    Recognition Web API query endpoint is out of range.
+    """
+
+    def __init__(self, response: Response) -> None:
+        """
+        Args:
+            response: The response to a request to Vuforia.
+        """
+        super().__init__(response.text)
+        self._response = response
+
+    @property
+    def response(self) -> Response:
+        """
+        The response returned by Vuforia which included this error.
+        """
+        return self._response
+
+
 class UnknownTarget(Exception):
     """
     Exception raised when Vuforia returns a response with a result code
diff --git a/src/vws/include_target_data.py b/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'
diff --git a/src/vws/py.typed b/src/vws/py.typed
diff --git a/src/vws/query.py b/src/vws/query.py
diff --git a/src/vws/vws.py b/src/vws/vws.py
diff --git a/tests/conftest.py b/tests/conftest.py
diff --git a/tests/test_exceptions.py b/tests/test_exceptions.py
diff --git a/tests/test_query.py b/tests/test_query.py
diff --git a/tests/test_vws.py b/tests/test_vws.py

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`include versioneer.py`
`2`	`2`	`include src/vws/_version.py`
	`3`	`+include src/vws/py.typed`