Add loading image from filename.

docs/vision-usage.rst

@@ -1,8 +1,11 @@
+####################
 Using the Vision API
-====================
+####################
 
+
+********************************
 Authentication and Configuration
---------------------------------
+********************************
 
 - For an overview of authentication in ``google-cloud-python``,
   see :doc:`google-cloud-auth`.
@@ -31,8 +34,43 @@ or pass in ``credentials`` and ``project`` explicitly.
      >>> client = vision.Client(project='my-project', credentials=creds)
 
 
+*****************************************************
+Creating an :class:`~google.cloud.vision.image.Image`
+*****************************************************
+
+The :class:`~google.cloud.vision.image.Image` class is used to load image
+data from sources such as a Google Cloud Storage URI, raw bytes, or a file.
+
+
+From a Google Cloud Storage URI
+===============================
+
+.. code-block:: python
+
+    >>> from google.cloud import vision
+    >>> client = vision.Client()
+    >>> image = client.image(source_uri='gs://my-test-bucket/image.jpg')
+
+
+From a filename
+===============
+
+.. code-block:: python
+
+    >>> image = client.image(filename='image.jpg')
+
+From raw bytes
+==============
+
+.. code-block:: python
+
+    >>> with open('./image.jpg', 'rb') as image_file:
+    ...     bytes_image = client.image(content=image_file.read())
+
+
+****************
 Manual Detection
-~~~~~~~~~~~~~~~~
+****************
 
 You can call the detection method manually.
 
@@ -60,8 +98,9 @@ You can call the detection method manually.
     'github'
 
 
+**************
 Face Detection
-~~~~~~~~~~~~~~
+**************
 
 :meth:`~google.cloud.vision.image.Image.detect_faces` will search for faces in
 an image and return the coordinates in the image of each `landmark type`_ that
@@ -87,8 +126,9 @@ was detected.
     0.02545464
 
 
+***************
 Label Detection
-~~~~~~~~~~~~~~~
+***************
 
 :meth:`~google.cloud.vision.image.Image.detect_labels` will attempt to label
 objects in an image. If there is a car, person and a dog in the image, label
@@ -107,8 +147,9 @@ certainty from ``0.0 to 1.0``.
     0.9863683
 
 
+******************
 Landmark Detection
-~~~~~~~~~~~~~~~~~~
+******************
 
 :meth:`~google.cloud.vision.image.Image.detect_landmarks` will attempt to
 detect landmarks such as "Mount Rushmore" and the "Sydney Opera House". The API
@@ -133,8 +174,9 @@ will also provide their known geographical locations if available.
     162
 
 
+**************
 Logo Detection
-~~~~~~~~~~~~~~
+**************
 
 With :meth:`~google.cloud.vision.image.Image.detect_logos`, you can identify
 brand logos in an image. Their shape and location in the image can be found by
@@ -162,8 +204,9 @@ iterating through the detected logo's ``vertices``.
     62
 
 
+*********************
 Safe Search Detection
-~~~~~~~~~~~~~~~~~~~~~
+*********************
 
 :meth:`~google.cloud.vision.image.Image.detect_safe_search` will try to
 categorize the entire contents of the image under four categories.
@@ -192,8 +235,9 @@ categorize the entire contents of the image under four categories.
     'LIKELY'
 
 
+**************
 Text Detection
-~~~~~~~~~~~~~~
+**************
 
 :meth:`~google.cloud.vision.image.Image.detect_text` performs OCR to find text
 in an image.
@@ -213,8 +257,9 @@ in an image.
     'some other text in the image'
 
 
+****************
 Image Properties
-~~~~~~~~~~~~~~~~
+****************
 
 :meth:`~google.cloud.vision.image.Image.detect_properties` will process the
 image and determine the dominant colors in the image.
@@ -238,8 +283,9 @@ image and determine the dominant colors in the image.
     0.758658
 
 
+****************
 No results found
-~~~~~~~~~~~~~~~~
+****************
 
 If no results for the detection performed can be extracted from the image, then
 an empty list is returned. This behavior is similiar with all detection types.

vision/google/cloud/vision/image.py

@@ -30,22 +30,35 @@ class Image(object):
     :type content: bytes
     :param content: Byte stream of an image.
 
+    :type filename: str
+    :param filename: Filename to image.
+
     :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, client, content=None, source_uri=None):
+    def __init__(self, client, content=None, filename=None, source_uri=None):
+        sources = [source for source in (content, filename, source_uri)
+                   if source is not None]
+        if len(sources) != 1:
+            raise ValueError(
+                'Specify exactly one of "content", "filename", or '
+                '"source_uri".')
+
         self.client = client
-        self._content = None
-        self._source = None
 
-        if source_uri:
-            self._source = source_uri
-        else:
-            self._content = _bytes_to_unicode(b64encode(_to_bytes(content)))
+        if filename is not None:
+            with open(filename, 'rb') as file_obj:
+                content = file_obj.read()
+
+        if content is not None:
+            content = _bytes_to_unicode(b64encode(_to_bytes(content)))
+
+        self._content = content
+        self._source = source_uri
 
     def as_dict(self):
         """Generate dictionary structure for request.

vision/tox.ini

@@ -7,6 +7,7 @@ localdeps =
     pip install --quiet --upgrade {toxinidir}/../core
 deps =
     {toxinidir}/../core
+    mock
     pytest
 covercmd =
     py.test --quiet \

vision/unit_tests/test_image.py

@@ -33,29 +33,44 @@ def _get_target_class():
     def _make_one(self, *args, **kw):
         return self._get_target_class()(*args, **kw)
 
+    def test_must_set_one_source(self):
+        with self.assertRaises(ValueError):
+            self._make_one(CLIENT_MOCK)
+
+        with self.assertRaises(ValueError):
+            self._make_one(CLIENT_MOCK, content=IMAGE_CONTENT,
+                           source_uri=IMAGE_SOURCE)
+
+        with self.assertRaises(ValueError):
+            self._make_one(CLIENT_MOCK, content=IMAGE_CONTENT,
+                           source_uri=IMAGE_SOURCE, filename='myimage.jpg')
+
+        image = self._make_one(CLIENT_MOCK, content=IMAGE_CONTENT)
+        self.assertEqual(image.content, B64_IMAGE_CONTENT)
+
     def test_image_source_type_content(self):
         image = self._make_one(CLIENT_MOCK, content=IMAGE_CONTENT)
 
-        _AS_DICT = {
-            'content': B64_IMAGE_CONTENT
+        as_dict = {
+            'content': B64_IMAGE_CONTENT,
         }
 
         self.assertEqual(B64_IMAGE_CONTENT, image.content)
         self.assertEqual(None, image.source)
-        self.assertEqual(_AS_DICT, image.as_dict())
+        self.assertEqual(image.as_dict(), as_dict)
 
     def test_image_source_type_google_cloud_storage(self):
         image = self._make_one(CLIENT_MOCK, source_uri=IMAGE_SOURCE)
 
-        _AS_DICT = {
+        as_dict = {
             'source': {
-                'gcs_image_uri': IMAGE_SOURCE
+                'gcs_image_uri': IMAGE_SOURCE,
             }
         }
 
         self.assertEqual(IMAGE_SOURCE, image.source)
         self.assertEqual(None, image.content)
-        self.assertEqual(_AS_DICT, image.as_dict())
+        self.assertEqual(image.as_dict(), as_dict)
 
     def test_cannot_set_both_source_and_content(self):
         image = self._make_one(CLIENT_MOCK, content=IMAGE_CONTENT)
@@ -68,3 +83,18 @@ def test_cannot_set_both_source_and_content(self):
         self.assertEqual(IMAGE_SOURCE, image.source)
         with self.assertRaises(AttributeError):
             image.content = IMAGE_CONTENT
+
+    def test_image_from_filename(self):
+        from mock import mock_open
+        from mock import patch
+
+        as_dict = {
+            'content': B64_IMAGE_CONTENT,
+        }
+
+        with patch('google.cloud.vision.image.open',
+                   mock_open(read_data=IMAGE_CONTENT)) as m:
+            image = self._make_one(CLIENT_MOCK, filename='my-image-file.jpg')
+        m.assert_called_once_with('my-image-file.jpg', 'rb')
+        self.assertEqual(image.content, B64_IMAGE_CONTENT)
+        self.assertEqual(image.as_dict(), as_dict)