Change image init. Update doc class references.

Author: daspecster

docs/vision-usage.rst

@@ -42,7 +42,7 @@ Annotate a single image
     >>> from google.cloud import vision
     >>> client = vision.Client()
     >>> with io.open('./image.png', 'rb') as image_file:
-    ...     image = client.image(image_file.read())
+    ...     image = client.image(content=image_file.read())
     >>> faces = image.detect_faces(limit=10)
     >>> faces[0].landmarks.left_eye.position.x_coordinate
     ... 1004.8003
@@ -52,15 +52,15 @@ Annotate multiple images
 
 .. code-block:: python
 
-     >>> import io
-     >>> from gcloud import vision
-     >>> client = vision.Client()
+    >>> import io
+    >>> from gcloud import vision
+    >>> client = vision.Client()
      >>> with io.open('./image.png', 'rb') as image_file:
-     ...     first_image = client.image(image_file.read())
-     >>> second_image = client.image('gs://my-storage-bucket/image2.jpg')
-     >>> with client.batch():
-     ...     labels = first_image.detect_labels()
-     ...     faces = second_image.detect_faces(limit=10)
+    ...     image_one = client.image(content=image_file.read())
+    >>> image_two = client.image(source_uri='gs://my-storage-bucket/image.jpg')
+    >>> with client.batch():
+    ...     labels = image_one.detect_labels()
+    ...     faces = image_two.detect_faces(limit=10)
 
 No results returned
 ~~~~~~~~~~~~~~~~~~~
@@ -71,7 +71,7 @@ Failing annotations return no results for the feature type requested.
 
     >>> from google.cloud import vision
     >>> client = vision.Client()
-    >>> image = client.image('./image.jpg')
+    >>> image = client.image(source_uri='gs://my-storage-bucket/image.jpg')
     >>> logos = image.detect_logos(limit=10)
     >>> logos
     []
@@ -88,7 +88,7 @@ You can call the detection method manually.
     >>> from google.cloud.vision.image import Feature
     >>> from google.cloud.vision.image import FeatureTypes
     >>> client = vision.Client()
-    >>> image = client.image('gs://my-test-bucket/image.jpg')
+    >>> image = client.image(source_uri='gs://my-test-bucket/image.jpg')
     >>> features = [Feature(FeatureTypes.FACE_DETECTION, 5),
     ...             Feature(FeatureTypes.LOGO_DETECTION, 3)]
     >>> annotations = image.detect(features)
@@ -105,7 +105,7 @@ see: https://cloud.google.com/vision/reference/rest/v1/images/annotate#type_1
 
     >>> from google.cloud import vision
     >>> client = vision.Client()
-    >>> image = client.image('gs://my-test-bucket/image.jpg')
+    >>> image = client.image(source_uri='gs://my-test-bucket/image.jpg')
     >>> faces = image.detect_faces(limit=10)
     >>> faces[0].landmarks.left_eye.landmark_type
     'LEFT_EYE'
@@ -131,7 +131,7 @@ attempt to identify those objects.
 
     >>> from google.cloud import vision
     >>> client = vision.Client()
-    >>> image = client.image('./image.jpg')
+    >>> image = client.image(source_uri='gs://my-storage-bucket/image.jpg')
     >>> labels = image.detect_labels(limit=3)
     >>> labels[0].description
     'automobile'

google/cloud/vision/client.py

@@ -24,7 +24,7 @@
 class VisionRequest(object):
     """Request container with image and features information to annotate.
 
-    :type features: list of :class:`gcoud.vision.feature.Feature`.
+    :type features: list of :class:`~gcoud.vision.feature.Feature`.
     :param features: The features that dictate which annotations to run.
 
     :type image: bytes
@@ -89,7 +89,7 @@ def annotate(self, image, features):
         :param image: A string which can be a URL, a Google Cloud Storage path,
                       or a byte stream of the image.
 
-        :type features:  list of :class:`google.cloud.vision.feature.Feature`
+        :type features:  list of :class:`~google.cloud.vision.feature.Feature`
         :param features: The type of detection that the Vision API should
                          use to determine image attributes. Pricing is
                          based on the number of Feature Types.
@@ -107,13 +107,16 @@ def annotate(self, image, features):
 
         return response['responses'][0]
 
-    def image(self, image_source):
+    def image(self, content=None, source_uri=None):
         """Get instance of Image using current client.
 
-        :type image_source: str or bytes
-        :param image_source: Byte stream of an image or a GCS URI.
+        :type content: bytes
+        :param content: Byte stream of an image.
 
-        :rtype: :class:`google.cloud.vision.image.Image`
+        :type source_uri: str
+        :param source_uri: Google Cloud Storage URI of image.
+
+        :rtype: :class:`~google.cloud.vision.image.Image`
         :returns: Image instance with the current client attached.
         """
-        return Image(client=self, image_source=image_source)
+        return Image(client=self, content=content, source_uri=source_uri)

google/cloud/vision/face.py

@@ -31,7 +31,7 @@ def __init__(self, roll, pan, tilt):
     def from_api_repr(cls, response):
         """Factory: construct the angles from an Vision API response.
 
-        :rtype: :class:`google.cloud.vision.face.Angles`
+        :rtype: :class:`~google.cloud.vision.face.Angles`
         :returns: An `Angles` instance with data parsed from `response`.
         """
         roll = response['rollAngle']
@@ -88,7 +88,7 @@ def from_api_repr(cls, response):
         :type response: dict
         :param response: Response dictionary representing a face.
 
-        :rtype: :class:`google.cloud.vision.face.Emotions`
+        :rtype: :class:`~google.cloud.vision.face.Emotions`
         :returns: Populated instance of `Emotions`.
         """
         joy_likelihood = getattr(Likelihood, response['joyLikelihood'])
@@ -106,7 +106,7 @@ def joy_likelihood(self):
 
         :rtype: str
         :returns: String derived from
-                  :class:`google.cloud.vision.face.Likelihood`.
+                  :class:`~google.cloud.vision.face.Likelihood`.
         """
         return self._joy_likelihood
 
@@ -116,7 +116,7 @@ def sorrow_likelihood(self):
 
         :rtype: str
         :returns: String derived from
-                  :class:`google.cloud.vision.face.Likelihood`.
+                  :class:`~google.cloud.vision.face.Likelihood`.
         """
         return self._sorrow_likelihood
 
@@ -126,7 +126,7 @@ def surprise_likelihood(self):
 
         :rtype: str
         :returns: String derived from
-                  :class:`google.cloud.vision.face.Likelihood`.
+                  :class:`~google.cloud.vision.face.Likelihood`.
         """
         return self._surprise_likelihood
 
@@ -136,7 +136,7 @@ def anger_likelihood(self):
 
         :rtype: str
         :returns: String derived from
-                  :class:`google.cloud.vision.face.Likelihood`.
+                  :class:`~google.cloud.vision.face.Likelihood`.
         """
         return self._anger_likelihood
 
@@ -164,7 +164,7 @@ def from_api_repr(cls, response):
         :type response: dict
         :param response: Face annotation dict returned from the Vision API.
 
-        :rtype: :class:`google.cloud.vision.face.Face`
+        :rtype: :class:`~google.cloud.vision.face.Face`
         :returns: A instance of `Face` with data parsed from `response`.
         """
         angles = Angles.from_api_repr(response)
@@ -186,7 +186,7 @@ def from_api_repr(cls, response):
     def angles(self):
         """Accessor to the pan, tilt and roll angles of a Face.
 
-        :rtype: :class:`google.cloud.vision.face.Angles`
+        :rtype: :class:`~google.cloud.vision.face.Angles`
         :returns: Pan, tilt and roll angles of the detected face.
         """
 
@@ -196,7 +196,7 @@ def angles(self):
     def bounds(self):
         """Accessor to the bounding poly information of the detected face.
 
-        :rtype: :class:`google.cloud.vision.face.Bounds`
+        :rtype: :class:`~google.cloud.vision.face.Bounds`
         :returns: An instance of ``Bounds`` which has a list of vertices.
         """
         return self._bounds
@@ -214,7 +214,7 @@ def detection_confidence(self):
     def emotions(self):
         """Accessor to the possible emotions expressed in the detected face.
 
-        :rtype: :class:`google.cloud.vision.face.Emotions`
+        :rtype: :class:`~google.cloud.vision.face.Emotions`
         :returns: An instance of ``Emotions`` with joy, sorrow, anger, surprise
                   likelihood.
         """
@@ -224,7 +224,7 @@ def emotions(self):
     def fd_bounds(self):
         """Accessor to the skin area bounding poly of the detected face.
 
-        :rtype: :class:`google.cloud.vision.image.FDBounds`
+        :rtype: :class:`~google.cloud.vision.image.FDBounds`
         :returns: An instance of ``FDBounds`` which has a list of vertices.
         """
         return self._fd_bounds
@@ -233,17 +233,17 @@ def fd_bounds(self):
     def headwear_likelihood(self):
         """Headwear likelihood.
 
-        :rtype: :class:`google.cloud.vision.face.Likelihood`
+        :rtype: :class:`~google.cloud.vision.face.Likelihood`
         :returns: String representing the likelihood based on
-                  :class:`google.cloud.vision.face.Likelihood`
+                  :class:`~google.cloud.vision.face.Likelihood`
         """
         return self._headwear_likelihood
 
     @property
     def image_properties(self):
         """Image properties from imaged used in face detection.
 
-        :rtype: :class:`google.cloud.vision.face.FaceImageProperties`
+        :rtype: :class:`~google.cloud.vision.face.FaceImageProperties`
         :returns: ``FaceImageProperties`` object with image properties.
         """
         return self._image_properties
@@ -252,7 +252,7 @@ def image_properties(self):
     def landmarks(self):
         """Accessor to the facial landmarks detected in a face.
 
-        :rtype: :class:`google.cloud.vision.face.Landmarks`
+        :rtype: :class:`~google.cloud.vision.face.Landmarks`
         :returns: ``Landmarks`` object with facial landmarks as properies.
         """
         return self._landmarks
@@ -278,7 +278,7 @@ def __init__(self, blurred_likelihood, underexposed_likelihood):
     def from_api_repr(cls, response):
         """Factory: construct image properties from image.
 
-        :rtype: :class:`google.cloud.vision.face.FaceImageProperties`
+        :rtype: :class:`~google.cloud.vision.face.FaceImageProperties`
         :returns: Instance populated with image property data.
         """
         blurred_likelihood = getattr(Likelihood,
@@ -294,7 +294,7 @@ def blurred_likelihood(self):
 
         :rtype: str
         :returns: String representation derived from
-                  :class:`google.cloud.vision.face.Position`.
+                  :class:`~google.cloud.vision.face.Position`.
         """
         return self._blurred_likelihood
 
@@ -304,7 +304,7 @@ def underexposed_likelihood(self):
 
         :rtype: str
         :returns: String representation derived from
-                  :class:`google.cloud.vision.face.Position`.
+                  :class:`~google.cloud.vision.face.Position`.
         """
         return self._underexposed_likelihood
 
@@ -369,7 +369,7 @@ def from_api_repr(cls, response_landmark):
         :type response_landmark: dict
         :param response_landmark: Landmark representation from Vision API.
 
-        :rtype: :class:`google.cloud.vision.face.Landmark`
+        :rtype: :class:`~google.cloud.vision.face.Landmark`
         :returns: Populated instance of `Landmark`.
         """
         position = Position.from_api_repr(response_landmark['position'])
@@ -380,7 +380,7 @@ def from_api_repr(cls, response_landmark):
     def position(self):
         """Landmark position on face.
 
-        :rtype: :class:`google.cloud.vision.face.Position`
+        :rtype: :class:`~google.cloud.vision.face.Position`
         :returns: Instance of `Position` with landmark coordinates.
         """
         return self._position

google/cloud/vision/feature.py

@@ -34,7 +34,7 @@ class Feature(object):
 
     :type feature_type: str
     :param feature_type: String representation of
-                         :class:`google.cloud.vision.feature.FeatureType`.
+                         :class:`~google.cloud.vision.feature.FeatureType`.
 
     :type max_results: int
     :param max_results: Number of results to return for the specified

google/cloud/vision/geometry.py

@@ -27,7 +27,7 @@ def from_api_repr(cls, response_vertices):
         :type response_vertices: dict
         :param response_vertices: List of vertices.
 
-        :rtype: :class:`google.cloud.vision.geometry.BoundsBase`
+        :rtype: :class:`~google.cloud.vision.geometry.BoundsBase`
         :returns: Instance of BoundsBase with populated verticies.
         """
         vertices = []
@@ -61,7 +61,7 @@ def __init__(self, x_coordinate, y_coordinate, z_coordinate):
     def from_api_repr(cls, response_position):
         """Factory: construct 3D position from API response.
 
-        :rtype: :class:`google.cloud.vision.geometry.Position`
+        :rtype: :class:`~google.cloud.vision.geometry.Position`
         :returns: `Position` constructed with 3D points from API response.
         """
         x_coordinate = response_position['x']

google/cloud/vision/image.py

@@ -18,7 +18,6 @@
 from base64 import b64encode
 
 from google.cloud._helpers import _to_bytes
-from google.cloud._helpers import _bytes_to_unicode
 from google.cloud.vision.face import Face
 from google.cloud.vision.feature import Feature
 from google.cloud.vision.feature import FeatureTypes
@@ -27,23 +26,25 @@
 class Image(object):
     """Image representation containing information to be annotate.
 
-    :type image_source: str
-    :param image_source: A string which can a Google Cloud Storage URI, or
-                         a byte stream of the image.
+    :type content: bytes
+    :param content: Byte stream of an image.
 
-    :type client: :class:`Client`
+    :type source_uri: str
+    :param source_uri: Google Cloud Storage URI of image.
+
+    :type client: :class:`~google.cloud.vision.client.Client`
     :param client: Instance of Vision client.
     """
 
-    def __init__(self, image_source, client):
+    def __init__(self, client, content=None, source_uri=None):
         self.client = client
         self._content = None
         self._source = None
 
-        if _bytes_to_unicode(image_source).startswith('gs://'):
-            self._source = image_source
+        if source_uri:
+            self._source = source_uri
         else:
-            self._content = b64encode(_to_bytes(image_source))
+            self._content = b64encode(_to_bytes(content))
 
     def as_dict(self):
         """Generate dictionary structure for request.
@@ -87,7 +88,7 @@ def detect_faces(self, limit=10):
         :param limit: The number of faces to try and detect.
 
         :rtype: list
-        :returns: List of :class:`google.cloud.vision.face.Face`.
+        :returns: List of :class:`~google.cloud.vision.face.Face`.
         """
         faces = []
         face_detection_feature = Feature(FeatureTypes.FACE_DETECTION, limit)

unit_tests/vision/test_client.py

@@ -64,7 +64,7 @@ def test_face_annotation(self):
 
         features = [Feature(feature_type=FeatureTypes.FACE_DETECTION,
                             max_results=3)]
-        image = client.image(_IMAGE_CONTENT)
+        image = client.image(content=_IMAGE_CONTENT)
         response = client.annotate(image, features)
 
         self.assertEqual(REQUEST,
@@ -77,7 +77,7 @@ def test_image_with_client(self):
         credentials = _Credentials()
         client = self._makeOne(project=self.PROJECT,
                                credentials=credentials)
-        image = client.image(_IMAGE_SOURCE)
+        image = client.image(source_uri=_IMAGE_SOURCE)
         self.assertTrue(isinstance(image, Image))
 
     def test_face_detection_from_source(self):
@@ -88,7 +88,7 @@ def test_face_detection_from_source(self):
         client = self._makeOne(project=self.PROJECT, credentials=credentials)
         client.connection = _Connection(RETURNED)
 
-        image = client.image(_IMAGE_SOURCE)
+        image = client.image(source_uri=_IMAGE_SOURCE)
         faces = image.detect_faces(limit=3)
         self.assertEqual(5, len(faces))
         self.assertTrue(isinstance(faces[0], Face))
@@ -105,7 +105,7 @@ def test_face_detection_from_content(self):
         client = self._makeOne(project=self.PROJECT, credentials=credentials)
         client.connection = _Connection(RETURNED)
 
-        image = client.image(_IMAGE_CONTENT)
+        image = client.image(content=_IMAGE_CONTENT)
         faces = image.detect_faces(limit=5)
         self.assertEqual(5, len(faces))
         self.assertTrue(isinstance(faces[0], Face))