Basic implementation of Translate API.

docs/index.rst

@@ -122,6 +122,14 @@
   monitoring-timeseries
   monitoring-label
 
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+  :caption: Translate
+
+  translate-usage
+  Client <translate-client>
+
 .. toctree::
   :maxdepth: 0
   :hidden:

docs/translate-client.rst

@@ -0,0 +1,15 @@
+Translate Client
+================
+
+.. automodule:: gcloud.translate.client
+  :members:
+  :undoc-members:
+  :show-inheritance:
+
+Connection
+~~~~~~~~~~
+
+.. automodule:: gcloud.translate.connection
+  :members:
+  :undoc-members:
+  :show-inheritance:

docs/translate-usage.rst

@@ -0,0 +1,123 @@
+Using the API
+=============
+
+With `Google Translate`_, you can dynamically translate text
+between thousands of language pairs. The Google Translate API
+lets websites and programs integrate with Google Translate
+programmatically. Google Translate API is available as a
+paid service. See the `Pricing`_ and `FAQ`_ pages for details.
+
+Authentication / Configuration
+------------------------------
+
+- Use :class:`~gcloud.translate.client.Client` objects to configure
+  your applications.
+
+- :class:`~gcloud.translate.client.Client` objects hold both a ``key``
+  and a connection to the Translate service.
+
+- **An API key is required for Translate.** See
+  `Identifying your application to Google`_ for details. This is
+  significantly different than the other clients in ``gcloud-python``.
+
+Methods
+-------
+
+To create a client:
+
+  .. code::
+
+     >>> from gcloud import translate
+     >>> client = translate.Client('my-api-key')
+
+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`.
+
+To get a list of languages supported by Google Translate
+
+  .. code::
+
+     >>> from gcloud import translate
+     >>> client = translate.Client('my-api-key')
+     >>> client.get_languages()
+     [
+         {
+             'language': 'af',
+             'name': 'Afrikaans',
+         },
+          ...
+     ]
+
+To detect the language that some given text is written in:
+
+  .. code::
+
+     >>> from gcloud import translate
+     >>> client = translate.Client('my-api-key')
+     >>> client.detect_language(['Me llamo', 'I am'])
+     [
+         {
+             'confidence': 0.25830904,
+             'input': 'Me llamo',
+             'language': 'es',
+         }, {
+             'confidence': 0.17112699,
+             'input': 'I am',
+             'language': 'en',
+         },
+     ]
+
+The `confidence`_ value is an optional floating point value between 0 and 1.
+The closer this value is to 1, the higher the confidence level for the
+language detection. This member is not always available.
+
+To translate text:
+
+  .. code::
+
+     >>> from gcloud import translate
+     >>> client = translate.Client('my-api-key')
+     >>> client.translate('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'],
+     ...                  target_language='de')
+     [
+         {
+             'translatedText': 'Mein Name ist Jeff',
+             'detectedSourceLanguage': 'es',
+             'input': 'Me llamo Jeff',
+         }, {
+             'translatedText': 'Mein Name ist Jeff',
+             'detectedSourceLanguage': 'en',
+             'input': 'My name is Jeff',
+         },
+     ]
+
+.. _Google Translate: https://cloud.google.com/translate
+.. _Pricing: https://cloud.google.com/translate/v2/pricing.html
+.. _FAQ: https://cloud.google.com/translate/v2/faq.html
+.. _Identifying your application to Google: https://cloud.google.com/translate/v2/using_rest#auth
+.. _confidence: https://cloud.google.com/translate/v2/detecting-language-with-rest

gcloud/connection.py

@@ -162,9 +162,10 @@ def build_api_url(cls, path, query_params=None,
         :type path: string
         :param path: The path to the resource (ie, ``'/b/bucket-name'``).
 
-        :type query_params: dict
-        :param query_params: A dictionary of keys and values to insert into
-                             the query string of the URL.
+        :type query_params: dict or list
+        :param query_params: A dictionary of keys and values (or list of
+                             key-value pairs) to insert into the query
+                             string of the URL.
 
         :type api_base_url: string
         :param api_base_url: The base URL for the API endpoint.
@@ -286,10 +287,10 @@ def api_request(self, method, path, query_params=None,
         :param path: The path to the resource (ie, ``'/b/bucket-name'``).
                      Required.
 
-        :type query_params: dict
-        :param query_params: A dictionary of keys and values to insert into
-                             the query string of the URL.  Default is
-                             empty dict.
+        :type query_params: dict or list
+        :param query_params: A dictionary of keys and values (or list of
+                             key-value pairs) to insert into the query
+                             string of the URL.
 
         :type data: string
         :param data: The data to send as the body of the request. Default is

gcloud/pubsub/connection.py

@@ -67,9 +67,10 @@ def build_api_url(self, path, query_params=None,
         :type path: string
         :param path: The path to the resource.
 
-        :type query_params: dict
-        :param query_params: A dictionary of keys and values to insert into
-                             the query string of the URL.
+        :type query_params: dict or list
+        :param query_params: A dictionary of keys and values (or list of
+                             key-value pairs) to insert into the query
+                             string of the URL.
 
         :type api_base_url: string
         :param api_base_url: The base URL for the API endpoint.

gcloud/translate/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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.
+
+"""Google Cloud Translate API wrapper."""
+
+from gcloud.translate.client import Client
+from gcloud.translate.connection import Connection