Add Vision safe search detection.

docs/index.rst

@@ -149,10 +149,11 @@
 
   vision-usage
   vision-client
-  vision-image
   vision-entity
   vision-feature
   vision-face
+  vision-image
+  vision-safe-search
 
 .. toctree::
   :maxdepth: 0

docs/vision-safe-search.rst

@@ -0,0 +1,10 @@
+Vision Safe Search
+==================
+
+Safe Search Annotation
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: google.cloud.vision.safe
+  :members:
+  :undoc-members:
+  :show-inheritance:

google/cloud/vision/image.py

@@ -22,6 +22,7 @@
 from google.cloud.vision.face import Face
 from google.cloud.vision.feature import Feature
 from google.cloud.vision.feature import FeatureTypes
+from google.cloud.vision.safe import SafeSearchAnnotation
 
 
 class Image(object):
@@ -162,6 +163,22 @@ def detect_logos(self, limit=10):
         feature = Feature(FeatureTypes.LOGO_DETECTION, limit)
         return self._detect_annotation(feature)
 
+    def detect_safe_search(self, limit=10):
+        """Retreive safe search properties from an image.
+
+        :type limit: int
+        :param limit: The number of faces to try and detect.
+
+        :rtype: list
+        :returns: List of
+                  :class:`~google.cloud.vision.sage.SafeSearchAnnotation`.
+        """
+        safe_detection_feature = Feature(FeatureTypes.SAFE_SEARCH_DETECTION,
+                                         limit)
+        result = self.client.annotate(self, [safe_detection_feature])
+        safe_search_response = result['safeSearchAnnotation']
+        return SafeSearchAnnotation.from_api_repr(safe_search_response)
+
     def detect_text(self, limit=10):
         """Detect text in an image.
 

google/cloud/vision/safe.py

@@ -0,0 +1,101 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Safe search class for information returned from annotating an image."""
+
+
+from google.cloud.vision.likelihood import Likelihood
+
+
+class SafeSearchAnnotation(object):
+    """Representation of a SafeSearchAnnotation.
+
+    :type adult_likelihood: :class:`~google.cloud.vision.likelihood.Likelihood`
+    :param adult_likelihood: Likelihood that image contains adult material.
+
+    :type spoof_likelihood: :class:`~google.cloud.vision.likelihood.Likelihood`
+    :param spoof_likelihood: Likelihood that image is a spoof.
+
+    :type medical_likelihood:
+        :class:`~google.cloud.vision.likelihood.Likelihood`
+    :param medical_likelihood: Likelihood that image contains medical material.
+
+    :type violence_likelihood:
+        :class:`~google.cloud.vision.likelihood.Likelihood`
+    :param violence_likelihood: Likelihood that image contains violence.
+    """
+
+    def __init__(self, adult_likelihood, spoof_likelihood, medical_likelihood,
+                 violence_likelihood):
+        self._adult_likelihood = adult_likelihood
+        self._spoof_likelihood = spoof_likelihood
+        self._medical_likeliehood = medical_likelihood
+        self._violence_likelihood = violence_likelihood
+
+    @classmethod
+    def from_api_repr(cls, response):
+        """Factory: construct SafeSearchAnnotation from Vision API response.
+
+        :type response: dict
+        :param response: Dictionary response from Vision API with safe search
+                         data.
+
+        :rtype: :class:`~google.cloud.vision.safe.SafeSearchAnnotation`
+        :returns: Instance of ``SafeSearchAnnotation``.
+        """
+        adult_likelihood = getattr(Likelihood, response['adult'])
+        spoof_likelihood = getattr(Likelihood, response['spoof'])
+        medical_likelihood = getattr(Likelihood, response['medical'])
+        violence_likelihood = getattr(Likelihood, response['violence'])
+
+        return cls(adult_likelihood, spoof_likelihood, medical_likelihood,
+                   violence_likelihood)
+
+    @property
+    def adult(self):
+        """Represents the adult contents likelihood for the image.
+
+        :rtype: :class:`~google.cloud.vision.likelihood.Likelihood`
+        :returns: ``Likelihood`` of the image containing adult content.
+        """
+        return self._adult_likelihood
+
+    @property
+    def spoof(self):
+        """The likelihood that an obvious modification was made to the image.
+
+        :rtype: :class:`~google.cloud.vision.likelihood.Likelihood`
+        :returns: The ``Likelihood`` that an obvious modification was made to
+                  the image's canonical version to make it appear funny or
+                  offensive.
+        """
+        return self._spoof_likelihood
+
+    @property
+    def medical(self):
+        """Likelihood this is a medical image.
+
+        :rtype: :class:`~google.cloud.vision.likelihood.Likelihood`
+        :returns: The ``Likelihood`` that the image is medical in origin.
+        """
+        return self._medical_likeliehood
+
+    @property
+    def violence(self):
+        """Likeliehood that this image contains violence.
+
+        :rtype: :class:`~google.cloud.vision.likelihood.Likelihood`
+        :returns: The ``Likelihood`` that the image contains violence.
+        """
+        return self._violence_likelihood

unit_tests/vision/_fixtures.py

@@ -1570,6 +1570,20 @@
 }
 
 
+SAFE_SEARCH_DETECTION_RESPONSE = {
+    'responses': [
+        {
+            'safeSearchAnnotation': {
+                'adult': 'VERY_UNLIKELY',
+                'spoof': 'UNLIKELY',
+                'medical': 'POSSIBLE',
+                'violence': 'VERY_UNLIKELY'
+            }
+        }
+    ]
+}
+
+
 TEXT_DETECTION_RESPONSE = {
     'responses': [
         {

unit_tests/vision/test_client.py

@@ -228,6 +228,26 @@ def test_text_detection_from_source(self):
         self.assertEqual('Google', text[1].description)
         self.assertEqual(694, text[0].bounds.vertices[0].y_coordinate)
 
+    def test_safe_search_detection_from_source(self):
+        from google.cloud.vision.safe import SafeSearchAnnotation
+        from unit_tests.vision._fixtures import SAFE_SEARCH_DETECTION_RESPONSE
+
+        RETURNED = SAFE_SEARCH_DETECTION_RESPONSE
+        credentials = _Credentials()
+        client = self._makeOne(project=self.PROJECT, credentials=credentials)
+        client.connection = _Connection(RETURNED)
+
+        image = client.image(source_uri=_IMAGE_SOURCE)
+        safe_search = image.detect_safe_search()
+        self.assertTrue(isinstance(safe_search, SafeSearchAnnotation))
+        image_request = client.connection._requested[0]['data']['requests'][0]
+        self.assertEqual(_IMAGE_SOURCE,
+                         image_request['image']['source']['gcs_image_uri'])
+        self.assertEqual('VERY_UNLIKELY', safe_search.adult)
+        self.assertEqual('UNLIKELY', safe_search.spoof)
+        self.assertEqual('POSSIBLE', safe_search.medical)
+        self.assertEqual('VERY_UNLIKELY', safe_search.violence)
+
 
 class TestVisionRequest(unittest.TestCase):
     def _getTargetClass(self):