Send back the complete API responses. (#3059)

* Return full API responses for Natural Language.

* Return full API responses from NL.

* Do the hyphenated copyright thing for edited files.

* Update usage doc.

* Updates based on @dhermes feedback.

* Update system tests.

* Added system tests and Entity Response tests.

Still need explicit SyntaxResponse and SentimentResponse tests.

* Remove explcit dict.get('foo', None)

* Fix some of the pylint errors.

* Finish fixing pylint errors.

* It is 2017.

* Add SentimentResponse tests.

* Unit tests for SyntaxResponse.

* Missed a dict.get('foo', None) case.

* Use assertIsNone

* Remove wikipedia_url as an attribute.

* PEP 257 compliance.

* Add Sentiment isInstance check.

* Add API responses documentation.

* Adding sentences to docs.

* Fix typo.

Author: lukesneeringer

docs/language-responses.rst

@@ -1,6 +1,20 @@
 Natural Language Response Classes
 =================================
 
+Responses
+~~~~~~~~~
+
+.. automodule:: google.cloud.language.api_responses
+  :members:
+  :show-inheritance:
+
+Sentences
+~~~~~~~~~
+
+.. automodule:: google.cloud.language.sentence
+  :members:
+  :show-inheritance:
+
 Entity
 ~~~~~~
 

docs/language-usage.rst

@@ -78,15 +78,8 @@ the document's type is plain text:
      >>> document.doc_type == language.Document.PLAIN_TEXT
      True
 
-In addition, the document's language defaults to the language on
-the client
-
-  .. code-block:: python
-
-     >>> document.language
-     'en-US'
-     >>> document.language == client.language
-     True
+The document's language defaults to ``None``, which will cause the API to
+auto-detect the language.
 
 In addition, the
 :meth:`~google.cloud.language.client.Client.document_from_html`,
@@ -161,31 +154,27 @@ metadata and other properties.
      >>> text_content = ("Michelangelo Caravaggio, Italian painter, is "
      ...                 "known for 'The Calling of Saint Matthew'.")
      >>> document = client.document(text_content)
-     >>> entities = document.analyze_entities()
-     >>> for entity in entities:
+     >>> entity_response = document.analyze_entities()
+     >>> for entity in entity_response.entities:
      ...     print('=' * 20)
      ...     print('         name: %s' % (entity.name,))
      ...     print('         type: %s' % (entity.entity_type,))
-     ...     print('wikipedia_url: %s' % (entity.wikipedia_url,))
      ...     print('     metadata: %s' % (entity.metadata,))
      ...     print('     salience: %s' % (entity.salience,))
      ====================
               name: Michelangelo Caravaggio
               type: PERSON
-     wikipedia_url: http://en.wikipedia.org/wiki/Caravaggio
-          metadata: {}
+          metadata: {'wikipedia_url': 'http://en.wikipedia.org/wiki/Caravaggio'}
           salience: 0.7615959
      ====================
               name: Italian
               type: LOCATION
-     wikipedia_url: http://en.wikipedia.org/wiki/Italy
-          metadata: {}
+          metadata: {'wikipedia_url': 'http://en.wikipedia.org/wiki/Caravaggio'}
           salience: 0.19960518
      ====================
               name: The Calling of Saint Matthew
               type: EVENT
-     wikipedia_url: http://en.wikipedia.org/wiki/The_Calling_of_St_Matthew_(Caravaggio)
-          metadata: {}
+          metadata: {'wikipedia_url': 'http://en.wikipedia.org/wiki/Caravaggio'}
           salience: 0.038798928
 
 Analyze Sentiment
@@ -200,7 +189,8 @@ only supports English text.
 
      >>> text_content = "Jogging isn't very fun."
      >>> document = client.document(text_content)
-     >>> sentiment = document.analyze_sentiment()
+     >>> sentiment_response = document.analyze_sentiment()
+     >>> sentiment = sentiment_response.sentiment
      >>> print(sentiment.score)
      -1
      >>> print(sentiment.magnitude)
@@ -265,14 +255,12 @@ the response is :data:`None`.
      ...     print('=' * 20)
      ...     print('         name: %s' % (entity.name,))
      ...     print('         type: %s' % (entity.entity_type,))
-     ...     print('wikipedia_url: %s' % (entity.wikipedia_url,))
      ...     print('     metadata: %s' % (entity.metadata,))
      ...     print('     salience: %s' % (entity.salience,))
      ====================
               name: Moon
               type: LOCATION
-     wikipedia_url: http://en.wikipedia.org/wiki/Natural_satellite
-          metadata: {}
+          metadata: {'wikipedia_url': 'http://en.wikipedia.org/wiki/Natural_satellite'}
           salience: 0.11793101
 
 .. _Features: https://cloud.google.com/natural-language/reference/rest/v1beta1/documents/annotateText#Features

language/google/cloud/language/api_responses.py

@@ -0,0 +1,129 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+"""Response types from the Natural Language API."""
+
+from google.cloud.language.entity import Entity
+from google.cloud.language.sentence import Sentence
+from google.cloud.language.sentiment import Sentiment
+from google.cloud.language.syntax import Token
+
+
+class EntityResponse(object):
+    """Object representation of entity responses.
+
+    A representation of a response sent back from the
+    ``analyzeEntites`` request to the Google Natural language API.
+
+    :type entities: list
+    :param entities: A list of :class:`~.language.entity.Entity` objects.
+
+    :type language: str
+    :param language: The language used for analysis.
+    """
+    def __init__(self, entities, language):
+        self.entities = entities
+        self.language = language
+
+    @classmethod
+    def from_api_repr(cls, payload):
+        """Return an entity response from a JSON representation.
+
+        :type payload: dict
+        :param payload: A dictionary representing the response.
+
+        :rtype: :class:`~.language.entity.Entity`
+        :returns: An ``Entity`` object.
+        """
+        return cls(
+            entities=[Entity.from_api_repr(i) for i in payload['entities']],
+            language=payload['language'],
+        )
+
+
+class SentimentResponse(object):
+    """Object representation of sentiment responses.
+
+    A representation of a response to an ``analyzeSentiment`` request
+    to the Google Natural Language API.
+
+    :type sentiment: :class:`~.language.sentiment.Sentiment`
+    :param sentiment: A Sentiment object.
+
+    :type language: str
+    :param language: The language used for analyzing sentiment.
+
+    :type sentences: list
+    :param sentences: A list of :class:`~.language.syntax.Sentence` objects.
+    """
+    def __init__(self, sentiment, language, sentences):
+        self.sentiment = sentiment
+        self.language = language
+        self.sentences = sentences
+
+    @classmethod
+    def from_api_repr(cls, payload):
+        """Return an sentiment response from a JSON representation.
+
+        :type payload: dict
+        :param payload: A dictionary representing the response.
+
+        :rtype: `~.language.sentiment.Sentiment`
+        :returns: A ``Sentiment`` object.
+        """
+        return cls(
+            language=payload.get('language'),
+            sentences=[Sentence.from_api_repr(sentence) for sentence
+                       in payload.get('sentences', ())],
+            sentiment=Sentiment.from_api_repr(payload['documentSentiment']),
+        )
+
+
+class SyntaxResponse(object):
+    """Object representation of syntax responses.
+
+    A representation of a response to an ``analyzeSyntax`` request
+    to the Google Natural Language API.
+
+    :type tokens: list
+    :param tokens: A list of :class:`~.language.syntax.Token` objects.
+
+    :type language: str
+    :param language: The language used for analyzing sentiment.
+
+    :type sentences: list
+    :param sentences: A list of :class:`~.language.syntax.Sentence` objects.
+    """
+    def __init__(self, tokens, language, sentences):
+        self.tokens = tokens
+        self.language = language
+        self.sentences = sentences
+
+    @classmethod
+    def from_api_repr(cls, payload):
+        """Return an syntax response from a JSON representation.
+
+        :type payload: dict
+        :param payload: A dictionary representing the response.
+
+        :rtype: `~.language.syntax.Syntax`
+        :returns: A ``Syntax`` object.
+        """
+        return cls(
+            language=payload.get('language'),
+            sentences=[Sentence.from_api_repr(sentence) for sentence in
+                       payload.get('sentences', ())],
+            tokens=[Token.from_api_repr(token) for token in
+                    payload.get('tokens', ())]
+        )

language/google/cloud/language/document.py

@@ -1,4 +1,4 @@
-# Copyright 2016 Google Inc.
+# Copyright 2016-2017 Google Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -19,15 +19,16 @@
 
 import collections
 
+from google.cloud.language import api_responses
 from google.cloud.language.entity import Entity
 from google.cloud.language.sentiment import Sentiment
-from google.cloud.language.syntax import Sentence
+from google.cloud.language.sentence import Sentence
 from google.cloud.language.syntax import Token
 
 
 Annotations = collections.namedtuple(
     'Annotations',
-    'sentences tokens sentiment entities')
+    ['sentences', 'tokens', 'sentiment', 'entities', 'language'])
 """Annotations for a document.
 
 :type sentences: list
@@ -42,6 +43,9 @@
 :type entities: list
 :param entities: List of :class:`~.language.entity.Entity`
                  found in a document.
+
+:type language: str
+:param language: The language used for the annotation.
 """
 
 
@@ -156,18 +160,16 @@ def analyze_entities(self):
 
         See `analyzeEntities`_.
 
-        :rtype: list
-        :returns: A list of :class:`~.language.entity.Entity` returned from
-                  the API.
+        :rtype: :class:`~.language.entity.EntityResponse`
+        :returns: A representation of the entity response.
         """
         data = {
             'document': self._to_dict(),
             'encodingType': self.encoding,
         }
         api_response = self.client._connection.api_request(
             method='POST', path='analyzeEntities', data=data)
-        return [Entity.from_api_repr(entity)
-                for entity in api_response['entities']]
+        return api_responses.EntityResponse.from_api_repr(api_response)
 
     def analyze_sentiment(self):
         """Analyze the sentiment in the current document.
@@ -177,13 +179,13 @@ def analyze_sentiment(self):
 
         See `analyzeSentiment`_.
 
-        :rtype: :class:`.Sentiment`
-        :returns: The sentiment of the current document.
+        :rtype: :class:`.SentimentResponse`
+        :returns: A representation of the sentiment response.
         """
         data = {'document': self._to_dict()}
         api_response = self.client._connection.api_request(
             method='POST', path='analyzeSentiment', data=data)
-        return Sentiment.from_api_repr(api_response['documentSentiment'])
+        return api_responses.SentimentResponse.from_api_repr(api_response)
 
     def analyze_syntax(self):
         """Analyze the syntax in the current document.
@@ -203,8 +205,7 @@ def analyze_syntax(self):
         }
         api_response = self.client._connection.api_request(
             method='POST', path='analyzeSyntax', data=data)
-        return [Token.from_api_repr(token)
-                for token in api_response.get('tokens', ())]
+        return api_responses.SyntaxResponse.from_api_repr(api_response)
 
     def annotate_text(self, include_syntax=True, include_entities=True,
                       include_sentiment=True):
@@ -271,9 +272,10 @@ def annotate_text(self, include_syntax=True, include_entities=True,
         entities = [Entity.from_api_repr(entity)
                     for entity in api_response['entities']]
         annotations = Annotations(
+            entities=entities,
+            language=api_response.get('language'),
             sentences=sentences,
-            tokens=tokens,
             sentiment=sentiment,
-            entities=entities,
+            tokens=tokens,
         )
         return annotations

language/google/cloud/language/entity.py

@@ -1,4 +1,4 @@
-# Copyright 2016 Google Inc.
+# Copyright 2016-2017 Google Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -53,10 +53,6 @@ class Entity(object):
     an organization, or location. The API associates information, such as
     salience and mentions, with entities.
 
-    The only supported metadata (as of August 2016) is ``wikipedia_url``,
-    so this value will be removed from the passed in ``metadata``
-    and put in its own property.
-
     .. _Entity message: https://cloud.google.com/natural-language/\
                         reference/rest/v1/Entity
     .. _EntityType enum: https://cloud.google.com/natural-language/\
@@ -84,7 +80,6 @@ class Entity(object):
     def __init__(self, name, entity_type, metadata, salience, mentions):
         self.name = name
         self.entity_type = entity_type
-        self.wikipedia_url = metadata.pop('wikipedia_url', None)
         self.metadata = metadata
         self.salience = salience
         self.mentions = mentions