Merge pull request #785 from adamtheturtle/success-add

Initial passing test for adding a target

Author: adamtheturtle

dev-requirements.txt

@@ -14,4 +14,7 @@ pyroma==2.4  # Packaging best practices checker
 pytest==3.8.0  # Test runners
 PyYAML==3.13
 vulture==0.29
+VWS-Python-Mock==2018.9.10.6
 yapf==0.24.0  # Automatic formatting for Python
+pytest-cov==2.6.0  # Measure code coverage
+codecov==2.0.15 # Upload coverage data

requirements.txt

@@ -0,0 +1 @@
+requests==2.19.1

src/vws/__init__.py

@@ -1,3 +1,9 @@
 """
 A library for Vuforia Web Services.
 """
+
+from .vws import VWS
+
+__all__ = [
+    'VWS',
+]

src/vws/_authorization.py

@@ -0,0 +1,84 @@
+"""
+Authorization helpers.
+"""
+
+import base64
+import email.utils
+import hashlib
+import hmac
+
+
+def compute_hmac_base64(key: bytes, data: bytes) -> bytes:
+    """
+    Return the Base64 encoded HMAC-SHA1 hash of the given `data` using the
+    provided `key`.
+    """
+    hashed = hmac.new(key=key, msg=None, digestmod=hashlib.sha1)
+    hashed.update(msg=data)
+    return base64.b64encode(s=hashed.digest())
+
+
+def rfc_1123_date() -> str:
+    """
+    Return the date formatted as per RFC 2616, section 3.3.1, rfc1123-date, as
+    described in
+    https://library.vuforia.com/articles/Training/Using-the-VWS-API.
+    """
+    return email.utils.formatdate(None, localtime=False, usegmt=True)
+
+
+def authorization_header(  # pylint: disable=too-many-arguments
+    access_key: bytes,
+    secret_key: bytes,
+    method: str,
+    content: bytes,
+    content_type: str,
+    date: str,
+    request_path: str,
+) -> bytes:
+    """
+    Return an `Authorization` header which can be used for a request made to
+    the VWS API with the given attributes.
+
+    See https://library.vuforia.com/articles/Training/Using-the-VWS-API.
+
+    Args:
+        access_key: A VWS server or client access key.
+        secret_key: A VWS server or client secret key.
+        method: The HTTP method which will be used in the request.
+        content: The request body which will be used in the request.
+        content_type: The `Content-Type` header which is expected by
+            endpoint. This does not necessarily have to match the
+            `Content-Type` sent in the headers. In particular, for the query
+            API, this must be set to `multipart/form-data` but the header must
+            include the boundary.
+        date: The current date which must exactly match the date sent in the
+            `Date` header.
+        request_path: The path to the endpoint which will be used in the
+            request.
+
+    Returns:
+        Return an `Authorization` header which can be used for a request made
+        to the VWS API with the given attributes.
+    """
+    hashed = hashlib.md5()
+    hashed.update(content)
+    content_md5_hex = hashed.hexdigest()
+
+    components_to_sign = [
+        method,
+        content_md5_hex,
+        content_type,
+        date,
+        request_path,
+    ]
+    string_to_sign = '\n'.join(components_to_sign)
+    signature = compute_hmac_base64(
+        key=secret_key,
+        data=bytes(
+            string_to_sign,
+            encoding='utf-8',
+        ),
+    )
+    auth_header = b'VWS %s:%s' % (access_key, signature)
+    return auth_header

src/vws/vws.py

@@ -0,0 +1,135 @@
+"""
+Tools for interacting with Vuforia APIs.
+"""
+
+import base64
+import io
+import json
+from typing import Union
+from urllib.parse import urljoin
+
+import requests
+from requests import Response
+
+from vws._authorization import authorization_header, rfc_1123_date
+
+
+def _target_api_request(
+    server_access_key: bytes,
+    server_secret_key: bytes,
+    method: str,
+    content: bytes,
+    request_path: str,
+    base_vws_url: str,
+) -> Response:
+    """
+    Make a request to the Vuforia Target API.
+
+    This uses `requests` to make a request against https://vws.vuforia.com.
+    The content type of the request will be `application/json`.
+
+    Args:
+        server_access_key: A VWS server access key.
+        server_secret_key: A VWS server secret key.
+        method: The HTTP method which will be used in the request.
+        content: The request body which will be used in the request.
+        request_path: The path to the endpoint which will be used in the
+            request.
+
+        base_vws_url: The base URL for the VWS API.
+
+    Returns:
+        The response to the request made by `requests`.
+    """
+    date = rfc_1123_date()
+    content_type = 'application/json'
+
+    signature_string = authorization_header(
+        access_key=server_access_key,
+        secret_key=server_secret_key,
+        method=method,
+        content=content,
+        content_type=content_type,
+        date=date,
+        request_path=request_path,
+    )
+
+    headers = {
+        'Authorization': signature_string,
+        'Date': date,
+        'Content-Type': content_type,
+    }
+
+    url = urljoin(base=base_vws_url, url=request_path)
+
+    response = requests.request(
+        method=method,
+        url=url,
+        headers=headers,
+        data=content,
+    )
+
+    return response
+
+
+class VWS:
+    """
+    An interface to Vuforia Web Services APIs.
+    """
+
+    def __init__(
+        self,
+        server_access_key: str,
+        server_secret_key: str,
+        base_vws_url: str = 'https://vws.vuforia.com',
+    ) -> None:
+        """
+        Args:
+            server_access_key: A VWS server access key.
+            server_secret_key: A VWS server secret key.
+            base_vws_url: The base URL for the VWS API.
+        """
+        self._server_access_key = server_access_key.encode()
+        self._server_secret_key = server_secret_key.encode()
+        self._base_vws_url = base_vws_url
+
+    def add_target(
+        self,
+        name: str,
+        width: Union[int, float],
+        image: io.BytesIO,
+    ) -> str:
+        """
+        Add a target to a Vuforia Web Services database.
+
+        Args:
+            name: The name of the target.
+            width: The width of the target.
+            image: The image of the target.
+
+        Returns:
+            The target ID of the new target.
+        """
+        image_data = image.getvalue()
+        image_data_encoded = base64.b64encode(image_data).decode('ascii')
+        metadata_encoded = None
+
+        data = {
+            'name': name,
+            'width': width,
+            'image': image_data_encoded,
+            'application_metadata': metadata_encoded,
+        }
+
+        content = bytes(json.dumps(data), encoding='utf-8')
+
+        response = _target_api_request(
+            server_access_key=self._server_access_key,
+            server_secret_key=self._server_secret_key,
+            method='POST',
+            content=content,
+            request_path='/targets',
+            base_vws_url=self._base_vws_url,
+        )
+
+        return str(response.json()['target_id'])

tests/conftest.py

@@ -0,0 +1,28 @@
+"""
+Configuration, plugins and fixtures for `pytest`.
+"""
+
+from typing import Iterator
+
+import pytest
+from mock_vws import MockVWS
+
+from vws import VWS
+
+pytest_plugins = [  # pylint: disable=invalid-name
+    'tests.fixtures.images',
+]
+
+
+@pytest.fixture()
+def client() -> Iterator[VWS]:
+    """
+    Yield a VWS client which connects to a mock.
+    """
+    with MockVWS() as mock:
+        vws_client = VWS(
+            server_access_key=mock.server_access_key,
+            server_secret_key=mock.server_secret_key,
+        )
+
+        yield vws_client

tests/data/high_quality_image.jpg

@@ -0,0 +1,3 @@
+"""
+Common fixtures.
+"""

tests/fixtures/__init__.py

@@ -0,0 +1,20 @@
+"""
+Fixtures for images.
+"""
+
+import io
+
+import pytest
+
+
+@pytest.fixture()
+def high_quality_image() -> io.BytesIO:
+    """
+    Return an image file which is expected to have a 'success' status when
+    added to a target and a high tracking rating.
+
+    At the time of writing, this image gains a tracking rating of 5.
+    """
+    path = 'tests/data/high_quality_image.jpg'
+    with open(path, 'rb') as high_quality_image_file:
+        return io.BytesIO(high_quality_image_file.read())

tests/fixtures/images.py

@@ -0,0 +1,34 @@
+"""
+Tests for helper function for adding a target to a Vuforia database.
+"""
+
+import io
+
+from vws import VWS
+
+
+class TestSuccess:
+    """
+    Tests for successfully adding a target.
+    """
+
+    def test_add_target(
+        self,
+        client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """
+        No exception is raised when adding one target.
+        """
+        client.add_target(name='x', width=1, image=high_quality_image)
+
+    def test_add_two_targets(
+        self,
+        client: VWS,
+        high_quality_image: io.BytesIO,
+    ) -> None:
+        """
+        No exception is raised when adding two targets with different names.
+        """
+        client.add_target(name='x', width=1, image=high_quality_image)
+        client.add_target(name='a', width=1, image=high_quality_image)