Merge pull request #1143 from adamtheturtle/target-report-dataclass

Return a data class for the target report

Author: adamtheturtle

src/vws/reports.py

@@ -2,7 +2,9 @@
 Classes for representing Vuforia reports.
 """
 
+import datetime
 from dataclasses import dataclass
+from enum import Enum
 
 
 @dataclass
@@ -26,3 +28,35 @@ class DatabaseSummaryReport:
     request_usage: int
     target_quota: int
     total_recos: int
+
+
+class TargetStatuses(Enum):
+    """
+    Constants representing VWS target statuses.
+    See the 'status' field in
+    https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API.html#How-To-Retrieve-a-Target-Record
+    """
+
+    PROCESSING = 'processing'
+    SUCCESS = 'success'
+    FAILED = 'failed'
+
+
+@dataclass
+class TargetSummaryReport:
+    """
+    A target summary report.
+
+    See
+    https://library.vuforia.com/articles/Solution/How-To-Use-the-Vuforia-Web-Services-API#How-To-Retrieve-a-Target-Summary-Report.
+    """
+
+    status: TargetStatuses
+    database_name: str
+    target_name: str
+    upload_date: datetime.date
+    active_flag: bool
+    tracking_rating: int
+    total_recos: int
+    current_month_recos: int
+    previous_month_recos: int

src/vws/vws.py

@@ -5,6 +5,7 @@
 import base64
 import io
 import json
+from datetime import date
 from time import sleep
 from typing import Dict, List, Optional, Union
 from urllib.parse import urljoin
@@ -16,7 +17,11 @@
 
 from vws._result_codes import raise_for_result_code
 from vws.exceptions import TargetProcessingTimeout
-from vws.reports import DatabaseSummaryReport
+from vws.reports import (
+    DatabaseSummaryReport,
+    TargetStatuses,
+    TargetSummaryReport,
+)
 
 
 def _target_api_request(
@@ -45,7 +50,7 @@ def _target_api_request(
     Returns:
         The response to the request made by `requests`.
     """
-    date = rfc_1123_date()
+    date_string = rfc_1123_date()
     content_type = 'application/json'
 
     signature_string = authorization_header(
@@ -54,13 +59,13 @@ def _target_api_request(
         method=method,
         content=content,
         content_type=content_type,
-        date=date,
+        date=date_string,
         request_path=request_path,
     )
 
     headers = {
         'Authorization': signature_string,
-        'Date': date,
+        'Date': date_string,
         'Content-Type': content_type,
     }
 
@@ -267,7 +272,7 @@ def _wait_for_target_processed(
         """
         while True:
             report = self.get_target_summary_report(target_id=target_id)
-            if report['status'] != 'processing':
+            if report.status != TargetStatuses.PROCESSING:
                 return
 
             sleep(seconds_between_requests)
@@ -345,10 +350,7 @@ def list_targets(self) -> List[str]:
 
         return list(response.json()['results'])
 
-    def get_target_summary_report(
-        self,
-        target_id: str,
-    ) -> Dict[str, Union[str, int]]:
+    def get_target_summary_report(self, target_id: str) -> TargetSummaryReport:
         """
         Get a summary report for a target.
 
@@ -378,7 +380,18 @@ def get_target_summary_report(
             expected_result_code='Success',
         )
 
-        return dict(response.json())
+        result_data = dict(response.json())
+        return TargetSummaryReport(
+            status=TargetStatuses(result_data['status']),
+            database_name=result_data['database_name'],
+            target_name=result_data['target_name'],
+            upload_date=date.fromisoformat(result_data['upload_date']),
+            active_flag=result_data['active_flag'],
+            tracking_rating=result_data['tracking_rating'],
+            total_recos=result_data['total_recos'],
+            current_month_recos=result_data['current_month_recos'],
+            previous_month_recos=result_data['previous_month_recos'],
+        )
 
     def get_database_summary_report(self) -> DatabaseSummaryReport:
         """

tests/test_vws.py

@@ -3,18 +3,24 @@
 """
 
 import base64
+import datetime
 import io
 import random
 import uuid
 from typing import Optional
 
 import pytest
+from freezegun import freeze_time
 from mock_vws import MockVWS
 from mock_vws.database import VuforiaDatabase
 
 from vws import VWS, CloudRecoService
 from vws.exceptions import TargetProcessingTimeout
-from vws.reports import DatabaseSummaryReport
+from vws.reports import (
+    DatabaseSummaryReport,
+    TargetStatuses,
+    TargetSummaryReport,
+)
 
 
 class TestAddTarget:
@@ -184,29 +190,31 @@ def test_get_target_summary_report(
         """
         Details of a target are returned by ``get_target_summary_report``.
         """
-        target_id = vws_client.add_target(
-            name='x',
-            width=1,
-            image=high_quality_image,
-            active_flag=True,
-            application_metadata=None,
-        )
+        date = '2018-04-25'
+        target_name = uuid.uuid4().hex
+        with freeze_time(date):
+            target_id = vws_client.add_target(
+                name=target_name,
+                width=1,
+                image=high_quality_image,
+                active_flag=True,
+                application_metadata=None,
+            )
 
         result = vws_client.get_target_summary_report(target_id=target_id)
-        expected_keys = {
-            'status',
-            'result_code',
-            'transaction_id',
-            'database_name',
-            'target_name',
-            'upload_date',
-            'active_flag',
-            'tracking_rating',
-            'total_recos',
-            'current_month_recos',
-            'previous_month_recos',
-        }
-        assert set(result.keys()) == expected_keys
+
+        expected_report = TargetSummaryReport(
+            status=TargetStatuses.SUCCESS,
+            database_name=result.database_name,
+            target_name=target_name,
+            upload_date=datetime.date(2018, 4, 25),
+            active_flag=True,
+            tracking_rating=result.tracking_rating,
+            total_recos=0,
+            current_month_recos=0,
+            previous_month_recos=0,
+        )
+        assert result == expected_report
 
 
 class TestGetDatabaseSummaryReport:
@@ -292,10 +300,10 @@ def test_wait_for_target_processed(
             application_metadata=None,
         )
         report = vws_client.get_target_summary_report(target_id=target_id)
-        assert report['status'] == 'processing'
+        assert report.status == TargetStatuses.PROCESSING
         vws_client.wait_for_target_processed(target_id=target_id)
         report = vws_client.get_target_summary_report(target_id=target_id)
-        assert report['status'] != 'processing'
+        assert report.status != TargetStatuses.PROCESSING
 
     def test_default_seconds_between_requests(
         self,
@@ -416,7 +424,7 @@ def test_custom_timeout(
             )
 
             report = vws_client.get_target_summary_report(target_id=target_id)
-            assert report['status'] == 'processing'
+            assert report.status == TargetStatuses.PROCESSING
             with pytest.raises(TargetProcessingTimeout):
                 vws_client.wait_for_target_processed(
                     target_id=target_id,
@@ -428,7 +436,7 @@ def test_custom_timeout(
                 timeout_seconds=0.5,
             )
             report = vws_client.get_target_summary_report(target_id=target_id)
-            assert report['status'] != 'processing'
+            assert report.status != TargetStatuses.PROCESSING
 
 
 class TestGetDuplicateTargets: