Send back the complete API responses.

language/google/cloud/language/api_responses.py

@@ -0,0 +1,116 @@
+# 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.
+
+"""Classes representing each of the types of responses returned 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):
+    """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.
+        """
+        return cls(
+            entities=[Entity.from_api_repr(i) for i in payload['entities']],
+            language=payload['language'],
+        )
+
+
+class SentimentResponse(object):
+    """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.
+        """
+        return cls(
+            language=payload.get('language', None),
+            sentences=[Sentence.from_api_repr(i) for i
+                       in payload.get('sentences', ())],
+            sentiment=Sentiment.from_api_repr(payload['documentSentiment']),
+        )
+
+
+class SyntaxResponse(object):
+    """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.
+        """
+        return cls(
+            language=payload.get('language', None),
+            sentences=[Sentence.from_api_repr(i) for i in
+                       payload.get('sentences', ())],
+            tokens=[Token.from_api_repr(i) for i in
+                    payload.get('tokens', ())]
+        )

language/google/cloud/language/client.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.

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,6 +19,7 @@
 
 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
@@ -27,7 +28,7 @@
 
 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', None),
             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,7 @@ 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.wikipedia_url = metadata.get('wikipedia_url', None)
         self.metadata = metadata
         self.salience = salience
         self.mentions = mentions

language/google/cloud/language/sentence.py

@@ -0,0 +1,67 @@
+# 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.
+
+from google.cloud.language.sentiment import Sentiment
+
+
+class Sentence(object):
+    """A Google Cloud Natural Language API sentence object.
+
+    .. _Sentence message: https://cloud.google.com/natural-language/reference\
+                          /rest/v1/documents/annotateText#Sentence
+
+    See `Sentence message`_.
+
+    :type content: str
+    :param content: The text that the sentence is composed of.
+
+    :type begin: int
+    :param begin: The beginning offset of the sentence in the original
+                  document according to the encoding type specified
+                  in the API request.
+
+    :type sentiment: :class:`~google.cloud.language.sentiment.Sentiment`
+    :param sentiment:
+        (Optional) For calls to
+        :meth:`~google.cloud.language.document.Document.annotate_text` where
+        ``include_sentiment`` is set to true, this field will contain the
+        sentiment for the sentence.
+    """
+
+    def __init__(self, content, begin, sentiment=None):
+        self.content = content
+        self.begin = begin
+        self.sentiment = sentiment
+
+    @classmethod
+    def from_api_repr(cls, payload):
+        """Convert a sentence from the JSON API into a :class:`Sentence`.
+
+        :param payload: dict
+        :type payload: The value from the backend.
+
+        :rtype: :class:`Sentence`
+        :returns: The sentence parsed from the API representation.
+        """
+        text_span = payload['text']
+
+        # The sentence may or may not have a sentiment; only attempt the
+        # typecast if one is present.
+        sentiment = None
+        if payload.get('sentiment', None):
+            sentiment = Sentiment.from_api_repr(payload['sentiment'])
+
+        # Return a Sentence object.
+        return cls(text_span['content'], text_span['beginOffset'],
+                   sentiment=sentiment)

language/google/cloud/language/sentiment.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.

language/google/cloud/language/syntax.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,6 +19,7 @@
 """
 
 from google.cloud.language.sentiment import Sentiment
+from google.cloud.language.sentence import Sentence
 
 
 class PartOfSpeech(object):
@@ -168,53 +169,3 @@ def from_api_repr(cls, payload):
         lemma = payload['lemma']
         return cls(text_content, text_begin, part_of_speech,
                    edge_index, edge_label, lemma)
-
-
-class Sentence(object):
-    """A Google Cloud Natural Language API sentence object.
-
-    .. _Sentence message: https://cloud.google.com/natural-language/reference\
-                          /rest/v1/documents/annotateText#Sentence
-
-    See `Sentence message`_.
-
-    :type content: str
-    :param content: The text that the sentence is composed of.
-
-    :type begin: int
-    :param begin: The beginning offset of the sentence in the original
-                  document according to the encoding type specified
-                  in the API request.
-
-    :type sentiment: :class:`~google.cloud.language.sentiment.Sentiment`
-    :param sentiment:
-        (Optional) For calls to
-        :meth:`~google.cloud.language.document.Document.annotate_text` where
-        ``include_sentiment`` is set to true, this field will contain the
-        sentiment for the sentence.
-    """
-
-    def __init__(self, content, begin, sentiment=None):
-        self.content = content
-        self.begin = begin
-        self.sentiment = sentiment
-
-    @classmethod
-    def from_api_repr(cls, payload):
-        """Convert a sentence from the JSON API into a :class:`Sentiment`.
-
-        :param payload: dict
-        :type payload: The value from the backend.
-
-        :rtype: :class:`Sentence`
-        :returns: The sentence parsed from the API representation.
-        """
-        text_span = payload['text']
-
-        try:
-            sentiment = Sentiment.from_api_repr(payload['sentiment'])
-        except KeyError:
-            sentiment = None
-
-        return cls(text_span['content'], text_span['beginOffset'],
-                   sentiment=sentiment)

language/setup.py

@@ -55,7 +55,7 @@
 
 setup(
     name='google-cloud-language',
-    version='0.22.2',
+    version='0.23.0',
     description='Python Client for Google Cloud Natural Language',
     long_description=README,
     namespace_packages=[