feat(VisualRecognitionV4): add support for downloading a model file

mamoonraja · mamoonraja · commit fa2cd1b8e8c0 · 2020-05-28T09:30:14.000-04:00
diff --git a/ibm_watson/visual_recognition_v4.py b/ibm_watson/visual_recognition_v4.py
@@ -365,6 +365,58 @@ def delete_collection(self, collection_id: str,
         response = self.send(request)
         return response
 
+    def get_model_file(self, collection_id: str, feature: str,
+                       model_format: str, **kwargs) -> 'DetailedResponse':
+        """
+        Get a model.
+
+        Download a model that you can deploy to detect objects in images. The collection
+        must include a generated model, which is indicated in the response for the
+        collection details as `"rscnn_ready": true`. If the value is `false`, train or
+        retrain the collection to generate the model.
+        Currently, the model format is specific to Android apps. For more information
+        about how to deploy the model to your app, see the [Watson Visual Recognition on
+        Android](https://github.com/matt-ny/rscnn) project in GitHub.
+
+        :param str collection_id: The identifier of the collection.
+        :param str feature: The feature for the model.
+        :param str model_format: The format of the returned model.
+        :param dict headers: A `dict` containing the request headers
+        :return: A `DetailedResponse` containing the result, headers and HTTP status code.
+        :rtype: DetailedResponse
+        """
+
+        if collection_id is None:
+            raise ValueError('collection_id must be provided')
+        if feature is None:
+            raise ValueError('feature must be provided')
+        if model_format is None:
+            raise ValueError('model_format must be provided')
+
+        headers = {}
+        if 'headers' in kwargs:
+            headers.update(kwargs.get('headers'))
+        sdk_headers = get_sdk_headers(service_name=self.DEFAULT_SERVICE_NAME,
+                                      service_version='V4',
+                                      operation_id='get_model_file')
+        headers.update(sdk_headers)
+
+        params = {
+            'version': self.version,
+            'feature': feature,
+            'model_format': model_format
+        }
+
+        url = '/v4/collections/{0}/model'.format(
+            *self._encode_path_vars(collection_id))
+        request = self.prepare_request(method='GET',
+                                       url=url,
+                                       headers=headers,
+                                       params=params)
+
+        response = self.send(request)
+        return response
+
     #########################
     # Images
     #########################
@@ -973,6 +1025,21 @@ class Features(Enum):
         OBJECTS = 'objects'
 
 
+class GetModelFileEnums(object):
+
+    class Feature(Enum):
+        """
+        The feature for the model.
+        """
+        OBJECTS = 'objects'
+
+    class ModelFormat(Enum):
+        """
+        The format of the returned model.
+        """
+        RSCNN = 'rscnn'
+
+
 class GetJpegImageEnums(object):
 
     class Size(Enum):
@@ -1732,7 +1799,7 @@ class ImageDetails():
           (UTC) that the image was created.
     :attr ImageSource source: The source type of the image.
     :attr ImageDimensions dimensions: (optional) Height and width of an image.
-    :attr List[Error] errors: (optional)
+    :attr List[Error] errors: (optional) Details about the errors.
     :attr TrainingDataObjects training_data: (optional) Training data for all
           objects.
     """
@@ -1756,7 +1823,7 @@ def __init__(self,
         :param datetime created: (optional) Date and time in Coordinated Universal
                Time (UTC) that the image was created.
         :param ImageDimensions dimensions: (optional) Height and width of an image.
-        :param List[Error] errors: (optional)
+        :param List[Error] errors: (optional) Details about the errors.
         :param TrainingDataObjects training_data: (optional) Training data for all
                objects.
         """
@@ -2592,13 +2659,16 @@ class ObjectTrainingStatus():
     :attr bool data_changed: Whether there are changes to the training data since
           the most recent training.
     :attr bool latest_failed: Whether the most recent training failed.
+    :attr bool rscnn_ready: Whether the model can be downloaded after the training
+          status is `ready`.
     :attr str description: Details about the training. If training is in progress,
           includes information about the status. If training is not in progress, includes
           a success message or information about why training failed.
     """
 
     def __init__(self, ready: bool, in_progress: bool, data_changed: bool,
-                 latest_failed: bool, description: str) -> None:
+                 latest_failed: bool, rscnn_ready: bool,
+                 description: str) -> None:
         """
         Initialize a ObjectTrainingStatus object.
 
@@ -2608,6 +2678,8 @@ def __init__(self, ready: bool, in_progress: bool, data_changed: bool,
         :param bool data_changed: Whether there are changes to the training data
                since the most recent training.
         :param bool latest_failed: Whether the most recent training failed.
+        :param bool rscnn_ready: Whether the model can be downloaded after the
+               training status is `ready`.
         :param str description: Details about the training. If training is in
                progress, includes information about the status. If training is not in
                progress, includes a success message or information about why training
@@ -2617,6 +2689,7 @@ def __init__(self, ready: bool, in_progress: bool, data_changed: bool,
         self.in_progress = in_progress
         self.data_changed = data_changed
         self.latest_failed = latest_failed
+        self.rscnn_ready = rscnn_ready
         self.description = description
 
     @classmethod
@@ -2625,7 +2698,7 @@ def from_dict(cls, _dict: Dict) -> 'ObjectTrainingStatus':
         args = {}
         valid_keys = [
             'ready', 'in_progress', 'data_changed', 'latest_failed',
-            'description'
+            'rscnn_ready', 'description'
         ]
         bad_keys = set(_dict.keys()) - set(valid_keys)
         if bad_keys:
@@ -2656,6 +2729,12 @@ def from_dict(cls, _dict: Dict) -> 'ObjectTrainingStatus':
             raise ValueError(
                 'Required property \'latest_failed\' not present in ObjectTrainingStatus JSON'
             )
+        if 'rscnn_ready' in _dict:
+            args['rscnn_ready'] = _dict.get('rscnn_ready')
+        else:
+            raise ValueError(
+                'Required property \'rscnn_ready\' not present in ObjectTrainingStatus JSON'
+            )
         if 'description' in _dict:
             args['description'] = _dict.get('description')
         else:
@@ -2680,6 +2759,8 @@ def to_dict(self) -> Dict:
             _dict['data_changed'] = self.data_changed
         if hasattr(self, 'latest_failed') and self.latest_failed is not None:
             _dict['latest_failed'] = self.latest_failed
+        if hasattr(self, 'rscnn_ready') and self.rscnn_ready is not None:
+            _dict['rscnn_ready'] = self.rscnn_ready
         if hasattr(self, 'description') and self.description is not None:
             _dict['description'] = self.description
         return _dict
diff --git a/test/unit/test_visual_recognition_v4.py b/test/unit/test_visual_recognition_v4.py
@@ -462,6 +462,80 @@ def construct_required_body(self):
         return body
 
 
+#-----------------------------------------------------------------------------
+# Test Class for get_model_file
+#-----------------------------------------------------------------------------
+class TestGetModelFile():
+
+    #--------------------------------------------------------
+    # Test 1: Send fake data and check response
+    #--------------------------------------------------------
+    @responses.activate
+    def test_get_model_file_response(self):
+        body = self.construct_full_body()
+        response = fake_response_BinaryIO_json
+        send_request(self, body, response)
+        assert len(responses.calls) == 1
+
+    #--------------------------------------------------------
+    # Test 2: Send only required fake data and check response
+    #--------------------------------------------------------
+    @responses.activate
+    def test_get_model_file_required_response(self):
+        # Check response with required params
+        body = self.construct_required_body()
+        response = fake_response_BinaryIO_json
+        send_request(self, body, response)
+        assert len(responses.calls) == 1
+
+    #--------------------------------------------------------
+    # Test 3: Send empty data and check response
+    #--------------------------------------------------------
+    @responses.activate
+    def test_get_model_file_empty(self):
+        check_empty_required_params(self, fake_response_BinaryIO_json)
+        check_missing_required_params(self)
+        assert len(responses.calls) == 0
+
+    #-----------
+    #- Helpers -
+    #-----------
+    def make_url(self, body):
+        endpoint = '/v4/collections/{0}/model'.format(body['collection_id'])
+        url = '{0}{1}'.format(base_url, endpoint)
+        return url
+
+    def add_mock_response(self, url, response):
+        responses.add(responses.GET,
+                    url,
+                    body=json.dumps(response),
+                    status=200,
+                    content_type='')
+    
+    def call_service(self, body):
+        service = VisualRecognitionV4(
+            authenticator=NoAuthAuthenticator(),
+            version='2019-02-11',
+            )
+        service.set_service_url(base_url)
+        output = service.get_model_file(**body)
+        return output
+
+    def construct_full_body(self):
+        body = dict()
+        body['collection_id'] = "string1"
+        body['feature'] = "string1"
+        body['model_format'] = "string1"
+        return body
+
+    def construct_required_body(self):
+        body = dict()
+        body['collection_id'] = "string1"
+        body['feature'] = "string1"
+        body['model_format'] = "string1"
+        return body
+
+
 # endregion
 ##############################################################################
 # End of Service: Collections
@@ -1504,17 +1578,18 @@ def send_request(obj, body, response, url=None):
 
 fake_response__json = None
 fake_response_AnalyzeResponse_json = """{"images": [], "warnings": [], "trace": "fake_trace"}"""
-fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "description": "fake_description"}}}"""
+fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "rscnn_ready": false, "description": "fake_description"}}}"""
 fake_response_CollectionsList_json = """{"collections": []}"""
-fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "description": "fake_description"}}}"""
-fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "description": "fake_description"}}}"""
+fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "rscnn_ready": false, "description": "fake_description"}}}"""
+fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "rscnn_ready": false, "description": "fake_description"}}}"""
+fake_response_BinaryIO_json = """Contents of response byte-stream..."""
 fake_response_ImageDetailsList_json = """{"images": [], "warnings": [], "trace": "fake_trace"}"""
 fake_response_ImageSummaryList_json = """{"images": []}"""
 fake_response_ImageDetails_json = """{"image_id": "fake_image_id", "updated": "2017-05-16T13:56:54.957Z", "created": "2017-05-16T13:56:54.957Z", "source": {"type": "fake_type", "filename": "fake_filename", "archive_filename": "fake_archive_filename", "source_url": "fake_source_url", "resolved_url": "fake_resolved_url"}, "dimensions": {"height": 6, "width": 5}, "errors": [], "training_data": {"objects": []}}"""
 fake_response_BinaryIO_json = """Contents of response byte-stream..."""
 fake_response_ObjectMetadataList_json = """{"object_count": 12, "objects": []}"""
 fake_response_UpdateObjectMetadata_json = """{"object": "fake_object", "count": 5}"""
 fake_response_ObjectMetadata_json = """{"object": "fake_object", "count": 5}"""
-fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "description": "fake_description"}}}"""
+fake_response_Collection_json = """{"collection_id": "fake_collection_id", "name": "fake_name", "description": "fake_description", "created": "2017-05-16T13:56:54.957Z", "updated": "2017-05-16T13:56:54.957Z", "image_count": 11, "training_status": {"objects": {"ready": false, "in_progress": false, "data_changed": true, "latest_failed": false, "rscnn_ready": false, "description": "fake_description"}}}"""
 fake_response_TrainingDataObjects_json = """{"objects": []}"""
 fake_response_TrainingEvents_json = """{"start_time": "2017-05-16T13:56:54.957Z", "end_time": "2017-05-16T13:56:54.957Z", "completed_events": 16, "trained_images": 14, "events": []}"""
