Implement Document factory constructors on language client

docs/index.rst

@@ -155,6 +155,7 @@
 
   language-usage
   Client <language-client>
+  language-document
 
 .. toctree::
   :maxdepth: 0

docs/language-document.rst

@@ -0,0 +1,6 @@
+Document
+~~~~~~~~
+
+.. automodule:: gcloud.language.document
+  :members:
+  :show-inheritance:

docs/language-usage.rst

@@ -127,21 +127,21 @@ to content stored in `Google Cloud Storage`_. We can use the
 
   .. code-block:: python
 
-     >>> document = client.document_from_blob(bucket='my-text-bucket',
-     ...                                      blob='sentiment-me.txt')
+     >>> document = client.document_from_blob('my-text-bucket',
+     ...                                      'sentiment-me.txt')
      >>> document.gcs_url
      'gs://my-text-bucket/sentiment-me.txt'
      >>> document.doc_type == language.Document.PLAIN_TEXT
      True
 
-and the :meth:`~gcloud.language.client.Client.document_from_uri`
+and the :meth:`~gcloud.language.client.Client.document_from_url`
 method. In either case, the document type can be specified with
 the ``doc_type`` argument:
 
   .. code-block:: python
 
      >>> gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
-     >>> document = client.document_from_uri(
+     >>> document = client.document_from_url(
      ...     gcs_url, doc_type=language.Document.HTML)
      >>> document.gcs_url == gcs_url
      True

gcloud/language/__init__.py

@@ -15,3 +15,4 @@
 """Client library for Google Cloud Natural Language API."""
 
 from gcloud.language.client import Client
+from gcloud.language.document import Document

gcloud/language/client.py

@@ -17,6 +17,7 @@
 
 from gcloud.client import JSONClient
 from gcloud.language.connection import Connection
+from gcloud.language.document import Document
 
 
 class Client(JSONClient):
@@ -40,3 +41,95 @@ class Client(JSONClient):
     """
 
     _connection_class = Connection
+
+    def document_from_text(self, content, **kwargs):
+        """Create a plain text document bound to this client.
+
+        :type content: str
+        :param content: The document plain text content.
+
+        :type kwargs: dict
+        :param kwargs: Remaining keyword arguments to be passed along to the
+                       :class:`Document` constructor.
+
+        :rtype: :class:`Document`
+        :returns: A plain-text document bound to this client.
+        :raises: :class:`~exceptions.TypeError` if ``doc_type`` is passed as a
+                 keyword argument.
+        """
+        if 'doc_type' in kwargs:
+            raise TypeError('Cannot pass doc_type')
+        return Document(self, content=content,
+                        doc_type=Document.PLAIN_TEXT, **kwargs)
+
+    def document_from_html(self, content, **kwargs):
+        """Create an HTML document bound to this client.
+
+        :type content: str
+        :param content: The document HTML text content.
+
+        :type kwargs: dict
+        :param kwargs: Remaining keyword arguments to be passed along to the
+                       :class:`Document` constructor.
+
+        :rtype: :class:`Document`
+        :returns: An HTML document bound to this client.
+        :raises: :class:`~exceptions.TypeError` if ``doc_type`` is passed as a
+                 keyword argument.
+        """
+        if 'doc_type' in kwargs:
+            raise TypeError('Cannot pass doc_type')
+        return Document(self, content=content,
+                        doc_type=Document.HTML, **kwargs)
+
+    def document_from_url(self, gcs_url,
+                          doc_type=Document.PLAIN_TEXT, **kwargs):
+        """Create a Cloud Storage document bound to this client.
+
+        :type gcs_url: str
+        :param gcs_url: The URL of the Google Cloud Storage object
+                        holding the content. Of the form
+                        ``gs://{bucket}/{blob-name}``.
+
+        :type doc_type: str
+        :param doc_type: (Optional) The type of text in the document.
+                         Defaults to plain text. Can also be specified
+                         as HTML via :attr:`~.Document.HTML`.
+
+        :type kwargs: dict
+        :param kwargs: Remaining keyword arguments to be passed along to the
+                       :class:`Document` constructor.
+
+        :rtype: :class:`Document`
+        :returns: A document bound to this client.
+        """
+        return Document(self, gcs_url=gcs_url, doc_type=doc_type, **kwargs)
+
+    def document_from_blob(self, bucket_name, blob_name,
+                           doc_type=Document.PLAIN_TEXT, **kwargs):
+        """Create a Cloud Storage document bound to this client.
+
+        :type bucket_name: str
+        :param bucket_name: The name of the bucket that contains the
+                            document text.
+
+        :type blob_name: str
+        :param blob_name: The name of the blob (within the bucket) that
+                          contains document text.
+
+        :type doc_type: str
+        :param doc_type: (Optional) The type of text in the document.
+                         Defaults to plain text. Can also be specified
+                         as HTML via :attr:`~.Document.HTML`.
+
+        :type kwargs: dict
+        :param kwargs: Remaining keyword arguments to be passed along to the
+                       :class:`Document` constructor.
+
+        :rtype: :class:`Document`
+        :returns: A document bound to this client.
+        """
+        # NOTE: We assume that the bucket and blob name don't
+        #       need to be URL-encoded.
+        gcs_url = 'gs://%s/%s' % (bucket_name, blob_name)
+        return self.document_from_url(gcs_url, doc_type=doc_type, **kwargs)

gcloud/language/document.py

@@ -0,0 +1,103 @@
+# 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.
+
+"""Definition for Google Cloud Natural Language API documents.
+
+A document is used to hold text to be analyzed and annotated.
+"""
+
+
+DEFAULT_LANGUAGE = 'en'
+"""Default document language, English."""
+
+
+class Encoding(object):
+    """Document text encoding types."""
+
+    NONE = 'NONE'
+    """Unspecified encoding type."""
+
+    UTF8 = 'UTF8'
+    """UTF-8 encoding type."""
+
+    UTF16 = 'UTF16'
+    """UTF-16 encoding type."""
+
+    UTF32 = 'UTF32'
+    """UTF-32 encoding type."""
+
+
+class Document(object):
+    """Document to send to Google Cloud Natural Language API.
+
+    Represents either plain text or HTML, and the content is either
+    stored on the document or referred to in a Google Cloud Storage
+    object.
+
+    :type client: :class:`~gcloud.language.client.Client`
+    :param client: A client which holds credentials and project
+                   configuration.
+
+    :type content: str
+    :param content: (Optional) The document text content (either plain
+                    text or HTML).
+
+    :type gcs_url: str
+    :param gcs_url: (Optional) The URL of the Google Cloud Storage object
+                    holding the content. Of the form
+                    ``gs://{bucket}/{blob-name}``.
+
+    :type doc_type: str
+    :param doc_type: (Optional) The type of text in the document.
+                     Defaults to plain text. Can be one of
+                     :attr:`~.Document.PLAIN_TEXT` or
+                     or :attr:`~.Document.HTML`.
+
+    :type language: str
+    :param language: (Optional) The language of the document text.
+                     Defaults to :data:`DEFAULT_LANGUAGE`.
+
+    :type encoding: str
+    :param encoding: (Optional) The encoding of the document text.
+                     Defaults to UTF-8. Can be one of
+                     :attr:`~.Encoding.UTF8`, :attr:`~.Encoding.UTF16`
+                     or :attr:`~.Encoding.UTF32`.
+
+    :raises: :class:`~exceptions.ValueError` both ``content`` and ``gcs_url``
+             are specified or if neither are specified.
+    """
+
+    TYPE_UNSPECIFIED = 'TYPE_UNSPECIFIED'
+    """Unspecified document type."""
+
+    PLAIN_TEXT = 'PLAIN_TEXT'
+    """Plain text document type."""
+
+    HTML = 'HTML'
+    """HTML document type."""
+
+    def __init__(self, client, content=None, gcs_url=None, doc_type=PLAIN_TEXT,
+                 language=DEFAULT_LANGUAGE, encoding=Encoding.UTF8):
+        if content is not None and gcs_url is not None:
+            raise ValueError('A Document cannot contain both local text and '
+                             'a link to text in a Google Cloud Storage object')
+        if content is None and gcs_url is None:
+            raise ValueError('A Document must contain either local text or a '
+                             'link to text in a Google Cloud Storage object')
+        self.client = client
+        self.content = content
+        self.gcs_url = gcs_url
+        self.doc_type = doc_type
+        self.language = language
+        self.encoding = encoding

gcloud/language/test_client.py

@@ -26,14 +26,118 @@ def _makeOne(self, *args, **kw):
 
     def test_ctor(self):
         from gcloud.language.connection import Connection
+
         project = 'PROJECT'
         creds = _Credentials()
         http = object()
         client = self._makeOne(project=project, credentials=creds, http=http)
-        self.assertTrue(isinstance(client.connection, Connection))
+        self.assertIsInstance(client.connection, Connection)
         self.assertTrue(client.connection.credentials is creds)
         self.assertTrue(client.connection.http is http)
 
+    def test_document_from_text_factory(self):
+        from gcloud.language.document import Document
+
+        creds = _Credentials()
+        client = self._makeOne(project='PROJECT',
+                               credentials=creds, http=object())
+
+        content = 'abc'
+        language = 'es'
+        document = client.document_from_text(content, language=language)
+        self.assertIsInstance(document, Document)
+        self.assertIs(document.client, client)
+        self.assertEqual(document.content, content)
+        # Test the default arg.
+        self.assertEqual(document.doc_type, Document.PLAIN_TEXT)
+        # Test the kwargs as well.
+        self.assertEqual(document.language, language)
+
+    def test_document_from_text_factory_failure(self):
+        creds = _Credentials()
+        client = self._makeOne(project='PROJECT',
+                               credentials=creds, http=object())
+
+        with self.assertRaises(TypeError):
+            client.document_from_text('abc', doc_type='foo')
+
+    def test_document_from_html_factory(self):
+        from gcloud.language.document import Document
+
+        creds = _Credentials()
+        client = self._makeOne(project='PROJECT',
+                               credentials=creds, http=object())
+
+        content = '<html>abc</html>'
+        language = 'ja'
+        document = client.document_from_html(content, language=language)
+        self.assertIsInstance(document, Document)
+        self.assertIs(document.client, client)
+        self.assertEqual(document.content, content)
+        # Test the default arg.
+        self.assertEqual(document.doc_type, Document.HTML)
+        # Test the kwargs as well.
+        self.assertEqual(document.language, language)
+
+    def test_document_from_html_factory_failure(self):
+        creds = _Credentials()
+        client = self._makeOne(project='PROJECT',
+                               credentials=creds, http=object())
+
+        with self.assertRaises(TypeError):
+            client.document_from_html('abc', doc_type='foo')
+
+    def test_document_from_url_factory(self):
+        from gcloud.language.document import Document
+
+        creds = _Credentials()
+        client = self._makeOne(project='PROJECT',
+                               credentials=creds, http=object())
+
+        gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
+        document = client.document_from_url(gcs_url)
+        self.assertIsInstance(document, Document)
+        self.assertIs(document.client, client)
+        self.assertIsNone(document.content)
+        self.assertEqual(document.gcs_url, gcs_url)
+        self.assertEqual(document.doc_type, Document.PLAIN_TEXT)
+
+    def test_document_from_url_factory_explicit(self):
+        from gcloud.language.document import Document
+        from gcloud.language.document import Encoding
+
+        creds = _Credentials()
+        client = self._makeOne(project='PROJECT',
+                               credentials=creds, http=object())
+
+        encoding = Encoding.UTF32
+        gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
+        document = client.document_from_url(gcs_url, doc_type=Document.HTML,
+                                            encoding=encoding)
+        self.assertIsInstance(document, Document)
+        self.assertIs(document.client, client)
+        self.assertIsNone(document.content)
+        self.assertEqual(document.gcs_url, gcs_url)
+        self.assertEqual(document.doc_type, Document.HTML)
+        self.assertEqual(document.encoding, encoding)
+
+    def test_document_from_blob_factory(self):
+        from gcloud.language.document import Document
+
+        creds = _Credentials()
+        client = self._makeOne(project='PROJECT',
+                               credentials=creds, http=object())
+
+        bucket_name = 'my-text-bucket'
+        blob_name = 'sentiment-me.txt'
+        gcs_url = 'gs://%s/%s' % (bucket_name, blob_name)
+        document = client.document_from_blob(bucket_name, blob_name)
+        self.assertIsInstance(document, Document)
+        self.assertIs(document.client, client)
+        self.assertIsNone(document.content)
+        self.assertEqual(document.gcs_url, gcs_url)
+        self.assertEqual(document.doc_type, Document.PLAIN_TEXT)
+
 
 class _Credentials(object):