Merge pull request #2187 from dhermes/language-impl-4

Updating language implementation after some review comments

docs/language-usage.rst

@@ -23,8 +23,7 @@ Client
 
 :class:`~gcloud.language.client.Client` objects provide a
 means to configure your application. Each instance holds
-both a ``project`` and an authenticated connection to the
-Natural Language service.
+an authenticated connection to the Natural Language service.
 
 For an overview of authentication in ``gcloud-python``, see
 :doc:`gcloud-auth`.
@@ -37,13 +36,13 @@ create an instance of :class:`~gcloud.language.client.Client`.
      >>> from gcloud import language
      >>> client = language.Client()
 
-By default the ``language`` is ``'en'`` and the ``encoding`` is
+By default the ``language`` is ``'en-US'`` and the ``encoding`` is
 UTF-8. To over-ride these values:
 
   .. code-block:: python
 
      >>> client = language.Client(language='es',
-     ...                          encoding=encoding=language.Encoding.UTF16)
+     ...                          encoding=language.Encoding.UTF16)
 
 The encoding can be one of
 :attr:`Encoding.UTF8 <gcloud.language.document.Encoding.UTF8>`,
@@ -85,7 +84,7 @@ the client
   .. code-block:: python
 
      >>> document.language
-     'en'
+     'en-US'
      >>> document.language == client.language
      True
 
@@ -123,30 +122,24 @@ The document type (``doc_type``) value can be one of
 
 In addition to supplying the text / HTML content, a document can refer
 to content stored in `Google Cloud Storage`_. We can use the
-:meth:`~gcloud.language.client.Client.document_from_blob` method:
+:meth:`~gcloud.language.client.Client.document_from_url` method:
 
   .. code-block:: python
 
-     >>> document = client.document_from_blob('my-text-bucket',
-     ...                                      'sentiment-me.txt')
-     >>> document.gcs_url
-     'gs://my-text-bucket/sentiment-me.txt'
+     >>> gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
+     >>> document = client.document_from_url(
+     ...     gcs_url, doc_type=language.Document.HTML)
+     >>> document.gcs_url == gcs_url
+     True
      >>> document.doc_type == language.Document.PLAIN_TEXT
      True
 
-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:
+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_url(
      ...     gcs_url, doc_type=language.Document.HTML)
-     >>> document.gcs_url == gcs_url
-     True
-     >>> document.doc_type == language.Document.HTML
-     True
 
 .. _analyzeEntities: https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeEntities
 .. _analyzeSentiment: https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/analyzeSentiment

gcloud/language/__init__.py

@@ -16,3 +16,4 @@
 
 from gcloud.language.client import Client
 from gcloud.language.document import Document
+from gcloud.language.document import Encoding

gcloud/language/client.py

@@ -15,19 +15,14 @@
 """Basic client for Google Cloud Natural Language API."""
 
 
-from gcloud.client import JSONClient
+from gcloud import client as client_module
 from gcloud.language.connection import Connection
 from gcloud.language.document import Document
 
 
-class Client(JSONClient):
+class Client(client_module.Client):
     """Client to bundle configuration needed for API requests.
 
-    :type project: str
-    :param project: the project which the client acts on behalf of. If not
-                    passed, falls back to the default inferred from the
-                    environment.
-
     :type credentials: :class:`~oauth2client.client.OAuth2Credentials`
     :param credentials: (Optional) The OAuth2 Credentials to use for the
                         connection owned by this client. If not passed (and
@@ -50,9 +45,9 @@ def document_from_text(self, content, **kwargs):
 
         :type kwargs: dict
         :param kwargs: Remaining keyword arguments to be passed along to the
-                       :class:`Document` constructor.
+                       :class:`.Document` constructor.
 
-        :rtype: :class:`Document`
+        :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.
@@ -70,9 +65,9 @@ def document_from_html(self, content, **kwargs):
 
         :type kwargs: dict
         :param kwargs: Remaining keyword arguments to be passed along to the
-                       :class:`Document` constructor.
+                       :class:`.Document` constructor.
 
-        :rtype: :class:`Document`
+        :rtype: :class:`.Document`
         :returns: An HTML document bound to this client.
         :raises: :class:`~exceptions.TypeError` if ``doc_type`` is passed as a
                  keyword argument.
@@ -98,38 +93,9 @@ def document_from_url(self, gcs_url,
 
         :type kwargs: dict
         :param kwargs: Remaining keyword arguments to be passed along to the
-                       :class:`Document` constructor.
+                       :class:`.Document` constructor.
 
-        :rtype: :class:`Document`
+        :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

@@ -20,7 +20,7 @@
 from gcloud.language.entity import Entity
 
 
-DEFAULT_LANGUAGE = 'en'
+DEFAULT_LANGUAGE = 'en-US'
 """Default document language, English."""
 
 
@@ -48,7 +48,7 @@ class Document(object):
     object.
 
     :type client: :class:`~gcloud.language.client.Client`
-    :param client: A client which holds credentials and project
+    :param client: A client which holds credentials and other
                    configuration.
 
     :type content: str
@@ -129,12 +129,14 @@ def analyze_entities(self):
         in the text, entity types, salience, mentions for each entity, and
         other properties.
 
-        See:
-        https://cloud.google.com/natural-language/reference/\
-        rest/v1beta1/documents/analyzeEntities
+        .. _analyzeEntities: https://cloud.google.com/natural-language/\
+                             reference/rest/v1beta1/documents/analyzeEntities
+
+        See `analyzeEntities`_.
 
         :rtype: list
-        :returns: A list of :class:`Entity` returned from the API.
+        :returns: A list of :class:`~.language.entity.Entity` returned from
+                  the API.
         """
         data = {
             'document': self._to_dict(),

gcloud/language/entity.py

@@ -57,16 +57,18 @@ class Entity(object):
     so this value will be removed from the passed in ``metadata``
     and put in its own property.
 
-    See:
-    https://cloud.google.com/natural-language/reference/rest/v1beta1/Entity
+    .. _Entity message: https://cloud.google.com/natural-language/\
+                        reference/rest/v1beta1/Entity
+    .. _EntityType enum: https://cloud.google.com/natural-language/\
+                         reference/rest/v1beta1/Entity#Type
+
+    See `Entity message`_.
 
     :type name: str
     :param name: The name / phrase identified as the entity.
 
     :type entity_type: str
-    :param entity_type: The type of the entity. See
-                        https://cloud.google.com/natural-language/\
-                        reference/rest/v1beta1/Entity#Type
+    :param entity_type: The type of the entity. See `EntityType enum`_.
 
     :type metadata: dict
     :param metadata: The metadata associated with the entity.

gcloud/language/test_client.py

@@ -27,10 +27,9 @@ 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)
+        client = self._makeOne(credentials=creds, http=http)
         self.assertIsInstance(client.connection, Connection)
         self.assertTrue(client.connection.credentials is creds)
         self.assertTrue(client.connection.http is http)
@@ -39,8 +38,7 @@ def test_document_from_text_factory(self):
         from gcloud.language.document import Document
 
         creds = _Credentials()
-        client = self._makeOne(project='PROJECT',
-                               credentials=creds, http=object())
+        client = self._makeOne(credentials=creds, http=object())
 
         content = 'abc'
         language = 'es'
@@ -55,8 +53,7 @@ def test_document_from_text_factory(self):
 
     def test_document_from_text_factory_failure(self):
         creds = _Credentials()
-        client = self._makeOne(project='PROJECT',
-                               credentials=creds, http=object())
+        client = self._makeOne(credentials=creds, http=object())
 
         with self.assertRaises(TypeError):
             client.document_from_text('abc', doc_type='foo')
@@ -65,8 +62,7 @@ def test_document_from_html_factory(self):
         from gcloud.language.document import Document
 
         creds = _Credentials()
-        client = self._makeOne(project='PROJECT',
-                               credentials=creds, http=object())
+        client = self._makeOne(credentials=creds, http=object())
 
         content = '<html>abc</html>'
         language = 'ja'
@@ -81,8 +77,7 @@ def test_document_from_html_factory(self):
 
     def test_document_from_html_factory_failure(self):
         creds = _Credentials()
-        client = self._makeOne(project='PROJECT',
-                               credentials=creds, http=object())
+        client = self._makeOne(credentials=creds, http=object())
 
         with self.assertRaises(TypeError):
             client.document_from_html('abc', doc_type='foo')
@@ -91,8 +86,7 @@ def test_document_from_url_factory(self):
         from gcloud.language.document import Document
 
         creds = _Credentials()
-        client = self._makeOne(project='PROJECT',
-                               credentials=creds, http=object())
+        client = self._makeOne(credentials=creds, http=object())
 
         gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
         document = client.document_from_url(gcs_url)
@@ -107,8 +101,7 @@ def test_document_from_url_factory_explicit(self):
         from gcloud.language.document import Encoding
 
         creds = _Credentials()
-        client = self._makeOne(project='PROJECT',
-                               credentials=creds, http=object())
+        client = self._makeOne(credentials=creds, http=object())
 
         encoding = Encoding.UTF32
         gcs_url = 'gs://my-text-bucket/sentiment-me.txt'
@@ -121,23 +114,6 @@ def test_document_from_url_factory_explicit(self):
         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):