Reverting back to using str/list values in Translate.

dhermes · dhermes · commit 2a4eaf8d35b1 · 2016-05-17T09:33:19.000-07:00
diff --git a/docs/translate-usage.rst b/docs/translate-usage.rst
@@ -30,7 +30,17 @@ To create a client:
      >>> from gcloud import translate
      >>> client = translate.Client('my-api-key')
 
-The API has three supported methods:
+By default, the client targets English when doing detections
+and translations, but a non-default value can be used as
+well:
+
+  .. code::
+
+     >>> from gcloud import translate
+     >>> client = translate.Client('my-api-key', target_language='es')
+
+The Google Translate API has three supported methods, and they
+map to three methods on a client:
 :meth:`~gcloud.translate.client.Client.get_languages`,
 :meth:`~gcloud.translate.client.Client.detect_language` and
 :meth:`~gcloud.translate.client.Client.translate`.
@@ -41,7 +51,7 @@ To get a list of languages supported by Google Translate
 
      >>> from gcloud import translate
      >>> client = translate.Client('my-api-key')
-     >>> client.get_languages('en')
+     >>> client.get_languages()
      [
          {
              'language': 'af',
@@ -76,21 +86,20 @@ To translate text:
      >>> from gcloud import translate
      >>> client = translate.Client('my-api-key')
      >>> client.translate('koszula')
-     [
-         {
-             'translatedText': 'shirt',
-             'detectedSourceLanguage': 'pl',
-             'input': 'koszula',
-         },
-     ]
+     {
+         'translatedText': 'shirt',
+         'detectedSourceLanguage': 'pl',
+         'input': 'koszula',
+     }
 
 or to use a non-default target language:
 
   .. code::
 
      >>> from gcloud import translate
      >>> client = translate.Client('my-api-key')
-     >>> client.translate(['Me llamo Jeff', 'My name is Jeff'], 'de')
+     >>> client.translate(['Me llamo Jeff', 'My name is Jeff'],
+     ...                  target_language='de')
      [
          {
              'translatedText': 'Mein Name ist Jeff',
diff --git a/gcloud/translate/client.py b/gcloud/translate/client.py
@@ -79,16 +79,17 @@ def get_languages(self, target_language=None):
             method='GET', path='/languages', query_params=query_params)
         return response.get('data', {}).get('languages', ())
 
-    def detect_language(self, *values):
+    def detect_language(self, values):
         """Detect the language of a string or list of strings.
 
         See: https://cloud.google.com/translate/v2/\
         detecting-language-with-rest
 
-        :type values: tuple
-        :param values: Tuple of strings that will have language detected.
+        :type values: str or list
+        :param values: String or list of strings that will have
+                       language detected.
 
-        :rtype: list
+        :rtype: str or list
         :returns: A list of dictionaries for each queried value. Each
                   dictionary typically contains three keys (though not
                   all will be present in all cases)
@@ -99,15 +100,19 @@ def detect_language(self, *values):
                   * ``language``: The detected language (as an ISO 639-1
                     language code).
 
-                  If multiple languages are detected for a given input, then
-                  the there will be a list of dictionaries (instead of a single
-                  dictionary) for that queried value.
+                  If only a single value is passed, then only a single
+                  dictionary will be returned.
         :raises: :class:`ValueError <exceptions.ValueError>` if the number of
                  detections is not equal to the number of values.
                  :class:`ValueError <exceptions.ValueError>` if a value
                  produces a list of detections with 0 or multiple results
                  in it.
         """
+        single_value = False
+        if isinstance(values, six.string_types):
+            single_value = True
+            values = [values]
+
         query_params = [('key', self.key)]
         query_params.extend(('q', _to_bytes(value, 'utf-8'))
                             for value in values)
@@ -134,32 +139,40 @@ def detect_language(self, *values):
             # The ``isReliable`` field is deprecated.
             detections[index].pop('isReliable', None)
 
-        return detections
+        if single_value:
+            return detections[0]
+        else:
+            return detections
 
-    def translate(self, *values, **kwargs):
+    def translate(self, values, target_language=None, format_=None,
+                  source_language=None, customization_ids=()):
         """Translate a string or list of strings.
 
         See: https://cloud.google.com/translate/v2/\
         translating-text-with-rest
 
-        Accepted keyword arguments are:
+        :type values: str or list
+        :param values: String or list of strings to translate.
 
-        * ``target_language`` (str): The language to translate results into.
-          This is required by the API and defaults to :data:`ENGLISH_ISO_639`.
-        * ``format`` (str): (Optional) One of ``text`` or ``html``, to specify
-          if the input text is plain text or HTML.
-        * ``source_language`` (str): (Optional) The language of the text to
-          be translated.
-        * ``customization_ids`` (list): (Optional) List of customization IDs
-          for translation. Sets the ``cid`` parameter in the query.
+        :type target_language: str
+        :param target_language: The language to translate results into. This
+                                is required by the API and defaults to
+                                the target language of the current instance.
 
-        :type values: tuple
-        :param values: Tuple of strings to translate.
+        :type format_: str
+        :param format_: (Optional) One of ``text`` or ``html``, to specify
+                        if the input text is plain text or HTML.
 
-        :type kwargs: dict
-        :param kwargs: Keyword arguments to be passed in.
+        :type source_language: str
+        :param source_language: (Optional) The language of the text to
+                                be translated.
 
-        :rtype: list
+        :type customization_ids: str or list
+        :param customization_ids: (Optional) ID or list of customization IDs
+                                  for translation. Sets the ``cid`` parameter
+                                  in the query.
+
+        :rtype: str or list list
         :returns: A list of dictionaries for each queried value. Each
                   dictionary typically contains three keys (though not
                   all will be present in all cases)
@@ -169,22 +182,30 @@ def translate(self, *values, **kwargs):
                   * ``translatedText``: The translation of the text into the
                     target language.
                   * ``input``: The corresponding input value.
+
+                  If only a single value is passed, then only a single
+                  dictionary will be returned.
         :raises: :class:`ValueError <exceptions.ValueError>` if the number of
                  values and translations differ.
         """
-        target_language = kwargs.get('target_language', self.target_language)
-        customization_ids = kwargs.get('customization_ids', ())
+        single_value = False
+        if isinstance(values, six.string_types):
+            single_value = True
+            values = [values]
+
+        if target_language is None:
+            target_language = self.target_language
         if isinstance(customization_ids, six.string_types):
             customization_ids = [customization_ids]
 
         query_params = [('key', self.key), ('target', target_language)]
         query_params.extend(('q', _to_bytes(value, 'utf-8'))
                             for value in values)
         query_params.extend(('cid', cid) for cid in customization_ids)
-        if 'format' in kwargs:
-            query_params.append(('format', kwargs['format']))
-        if 'source_language' in kwargs:
-            query_params.append(('source', kwargs['source_language']))
+        if format_ is not None:
+            query_params.append(('format', format_))
+        if source_language is not None:
+            query_params.append(('source', source_language))
 
         response = self.connection.api_request(
             method='GET', path='', query_params=query_params)
@@ -195,4 +216,8 @@ def translate(self, *values, **kwargs):
                              values, translations)
         for value, translation in six.moves.zip(values, translations):
             translation['input'] = value
-        return translations
+
+        if single_value:
+            return translations[0]
+        else:
+            return translations
diff --git a/gcloud/translate/test_client.py b/gcloud/translate/test_client.py
@@ -161,7 +161,7 @@ def test_detect_language_single_value(self):
         conn = client.connection = _Connection(data)
 
         result = client.detect_language(value)
-        self.assertEqual(result, [detection])
+        self.assertEqual(result, detection)
 
         # Verify requested.
         self.assertEqual(len(conn._requested), 1)
@@ -200,7 +200,7 @@ def test_detect_language_multiple_values(self):
         }
         conn = client.connection = _Connection(data)
 
-        result = client.detect_language(value1, value2)
+        result = client.detect_language([value1, value2])
         self.assertEqual(result, [detection1, detection2])
 
         # Verify requested.
@@ -276,7 +276,7 @@ def test_translate_defaults(self):
         conn = client.connection = _Connection(data)
 
         result = client.translate(value)
-        self.assertEqual(result, [translation])
+        self.assertEqual(result, translation)
 
         # Verify requested.
         self.assertEqual(len(conn._requested), 1)
@@ -290,6 +290,43 @@ def test_translate_defaults(self):
         ]
         self.assertEqual(req['query_params'], query_params)
 
+    def test_translate_multiple(self):
+        client = self._makeOne(self.KEY)
+        value1 = 'hvala ti'
+        translation1 = {
+            'detectedSourceLanguage': 'hr',
+            'translatedText': 'thank you',
+            'input': value1,
+        }
+        value2 = 'Dankon'
+        translation2 = {
+            'detectedSourceLanguage': 'eo',
+            'translatedText': 'thank you',
+            'input': value2,
+        }
+        data = {
+            'data': {
+                'translations': [translation1, translation2],
+            },
+        }
+        conn = client.connection = _Connection(data)
+
+        result = client.translate([value1, value2])
+        self.assertEqual(result, [translation1, translation2])
+
+        # Verify requested.
+        self.assertEqual(len(conn._requested), 1)
+        req = conn._requested[0]
+        self.assertEqual(req['method'], 'GET')
+        self.assertEqual(req['path'], '')
+        query_params = [
+            ('key', self.KEY),
+            ('target', 'en'),
+            ('q', value1.encode('utf-8')),
+            ('q', value2.encode('utf-8')),
+        ]
+        self.assertEqual(req['query_params'], query_params)
+
     def test_translate_explicit(self):
         client = self._makeOne(self.KEY)
         value = 'thank you'
@@ -310,8 +347,8 @@ def test_translate_explicit(self):
         format_ = 'text'
         result = client.translate(value, target_language=target_language,
                                   source_language=source_language,
-                                  format=format_, customization_ids=cid)
-        self.assertEqual(result, [translation])
+                                  format_=format_, customization_ids=cid)
+        self.assertEqual(result, translation)
 
         # Verify requested.
         self.assertEqual(len(conn._requested), 1)
