Send back the complete API responses.

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',
- 'sentencestokenssentimententities')
+['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