Merge pull request #218 from hanlhan/feature/tencent

deep_translator/__init__.py

@@ -14,6 +14,7 @@ from deep_translator.mymemory import MyMemoryTranslator
 from deep_translator.papago import PapagoTranslator
 from deep_translator.pons import PonsTranslator
 from deep_translator.qcri import QcriTranslator
+from deep_translator.tencent import TencentTranslator
 from deep_translator.yandex import YandexTranslator
 
 __author__ = """Nidhal Baccouri"""
@@ -32,6 +33,7 @@ __all__ = [
     "LibreTranslator",
     "PapagoTranslator",
     "ChatGptTranslator",
+    "TencentTranslator",
     "BaiduTranslator",
     "single_detection",
     "batch_detection",

deep_translator/constants.py

@@ -7,6 +7,8 @@ LIBRE_ENV_VAR = "LIBRE_API_KEY"
 MSFT_ENV_VAR = "MICROSOFT_API_KEY"
 QCRI_ENV_VAR = "QCRI_API_KEY"
 YANDEX_ENV_VAR = "YANDEX_API_KEY"
+TENCENT_SECRET_ID_ENV_VAR = "TENCENT_SECRET_ID"
+TENCENT_SECRET_KEY_ENV_VAR = "TENCENT_SECRET_KEY"
 BAIDU_APPID_ENV_VAR = "BAIDU_APPID"
 BAIDU_APPKEY_ENV_VAR = "BAIDU_APPKEY"
 
@@ -25,6 +27,7 @@ BASE_URLS = {
     "PAPAGO_API": "https://openapi.naver.com/v1/papago/n2mt",
     "LIBRE": "https://libretranslate.com/",
     "LIBRE_FREE": "https://libretranslate.de/",
+    "TENENT": "https://tmt.tencentcloudapi.com",
     "BAIDU": "https://fanyi-api.baidu.com/api/trans/vip/translate",
 }
 
@@ -609,6 +612,26 @@ LIBRE_LANGUAGES_TO_CODES = {
     "Vietnamese": "vi",
 }
 
+TENCENT_LANGUAGE_TO_CODE = {
+    "arabic": "ar",
+    "chinese (simplified)": "zh",
+    "chinese (traditional)": "zh-TW",
+    "english": "en",
+    "french": "fr",
+    "german": "de",
+    "hindi": "hi",
+    "indonesian": "id",
+    "japanese": "ja",
+    "korean": "ko",
+    "malay": "ms",
+    "portuguese": "pt",
+    "russian": "ru",
+    "spanish": "es",
+    "thai": "th",
+    "turkish": "tr",
+    "vietnamese": "vi",
+}
+
 BAIDU_LANGUAGE_TO_CODE = {
     "arabic": "ara",
     "bulgarian": "bul",

deep_translator/exceptions.py

@@ -182,6 +182,19 @@ class AuthorizationException(Exception):
         super().__init__(msg, *args)
 
 
+class TencentAPIerror(Exception):
+    """
+    exception thrown if Tencent API returns one of its errors
+    """
+
+    def __init__(self, api_message):
+        self.api_message = str(api_message)
+        self.message = "Tencent API returned the following error"
+
+    def __str__(self):
+        return "{}: {}".format(self.message, self.api_message)
+
+
 class BaiduAPIerror(Exception):
     """
     exception thrown if Baidu API returns one of its errors

deep_translator/tencent.py

@@ -0,0 +1,131 @@
+"""
+tencent translator API
+"""
+
+__copyright__ = "Copyright (C) 2020 Nidhal Baccouri"
+
+import base64
+import hashlib
+import hmac
+import os
+import time
+from typing import List, Optional
+
+import requests
+
+from deep_translator.base import BaseTranslator
+from deep_translator.constants import (
+    BASE_URLS,
+    TENCENT_LANGUAGE_TO_CODE,
+    TENCENT_SECRET_ID_ENV_VAR,
+    TENCENT_SECRET_KEY_ENV_VAR,
+)
+from deep_translator.exceptions import (
+    ApiKeyException,
+    ServerException,
+    TencentAPIerror,
+    TranslationNotFound,
+)
+from deep_translator.validate import is_empty, is_input_valid
+
+
+class TencentTranslator(BaseTranslator):
+    """
+    class that wraps functions, which use the TentCentTranslator translator
+    under the hood to translate word(s)
+    """
+
+    def __init__(
+        self,
+        source: str = "en",
+        target: str = "zh",
+        secret_id: Optional[str] = os.getenv(TENCENT_SECRET_ID_ENV_VAR, None),
+        secret_key: Optional[str] = os.getenv(
+            TENCENT_SECRET_KEY_ENV_VAR, None
+        ),
+        **kwargs
+    ):
+        """
+        @param secret_id: your tencent cloud api secret id.
+        Get one here: https://console.cloud.tencent.com/capi
+        @param secret_key: your tencent cloud api secret key.
+        @param source: source language
+        @param target: target language
+        """
+        if not secret_id:
+            raise ApiKeyException(env_var=TENCENT_SECRET_ID_ENV_VAR)
+
+        if not secret_key:
+            raise ApiKeyException(env_var=TENCENT_SECRET_KEY_ENV_VAR)
+
+        self.secret_id = secret_id
+        self.secret_key = secret_key
+        url = BASE_URLS.get("TENENT")
+        super().__init__(
+            base_url=url,
+            source=source,
+            target=target,
+            languages=TENCENT_LANGUAGE_TO_CODE,
+            **kwargs
+        )
+
+    def translate(self, text: str, **kwargs) -> str:
+        """
+        @param text: text to translate
+        @return: translated text
+        """
+        if is_input_valid(text):
+            if self._same_source_target() or is_empty(text):
+                return text
+
+            # Create the request parameters.
+            translate_endpoint = self._base_url.replace("https://", "")
+            params = {
+                "Action": "TextTranslate",
+                "Nonce": 11886,
+                "ProjectId": 0,
+                "Region": "ap-guangzhou",
+                "SecretId": self.secret_id,
+                "Source": self.source,
+                "SourceText": text,
+                "Target": self.target,
+                "Timestamp": int(time.time()),
+                "Version": "2018-03-21",
+            }
+            s = "GET" + translate_endpoint + "/?"
+            query_str = "&".join(
+                "%s=%s" % (k, params[k]) for k in sorted(params)
+            )
+            hmac_str = hmac.new(
+                self.secret_key.encode("utf8"),
+                (s + query_str).encode("utf8"),
+                hashlib.sha1,
+            ).digest()
+            params["Signature"] = base64.b64encode(hmac_str)
+
+            # Do the request and check the connection.
+            try:
+                response = requests.get(self._base_url, params=params)
+            except ConnectionError:
+                raise ServerException(503)
+            # If the answer is not success, raise server exception.
+            if response.status_code != 200:
+                raise ServerException(response.status_code)
+            # Get the response and check is not empty.
+            res = response.json()
+            if not res:
+                raise TranslationNotFound(text)
+            # Process and return the response.
+            if "Error" in res["Response"]:
+                raise TencentAPIerror(res["Response"]["Error"]["Code"])
+            return res["Response"]["TargetText"]
+
+    def translate_file(self, path: str, **kwargs) -> str:
+        return self._translate_file(path, **kwargs)
+
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
+        """
+        @param batch: list of texts to translate
+        @return: list of translations
+        """
+        return self._translate_batch(batch, **kwargs)

docs/README.rst

@@ -664,6 +664,35 @@ Libre Translator
 
     translated = LibreTranslator(source='auto', target='en').translate_file('path/to/file')
 
+TencentTranslator
+-----------------
+
+.. note::
+
+    In order to use the TencentTranslator translator, you need to generate a secret_id and a secret_key.
+    deep-translator supports both Pro and free APIs. Just check the examples below.
+    Visit https://cloud.tencent.com/document/api/551/15619 for more information on how to generate your Tencent secret_id
+    and secret_key.
+
+- Simple translation
+
+.. code-block:: python
+
+    text = 'Hello world'
+    translated = TencentTranslator(secret_id="your-secret_id", secret_key="your-secret_key" source="en", target="zh").translate(text)
+
+- Translate batch of texts
+
+.. code-block:: python
+
+    texts = ["Hello world", "How are you?"]
+    translated = TencentTranslator(secret_id="your-secret_id", secret_key="your-secret_key" source="en", target="zh").translate_batch(texts)
+
+- Translate from a file:
+
+.. code-block:: python
+
+    translated = TencentTranslator(secret_id="your-secret_id", secret_key="your-secret_key" source="en", target="zh").translate_file('path/to/file')
 
 BaiduTranslator
 -----------------

tests/test_tencent.py

@@ -0,0 +1,74 @@
+from unittest.mock import Mock, patch
+
+import pytest
+
+from deep_translator import TencentTranslator
+from deep_translator.exceptions import TencentAPIerror
+
+
+@patch("deep_translator.tencent.requests")
+def test_simple_translation(mock_requests):
+    translator = TencentTranslator(
+        secret_id="imagine-this-is-an-valid-secret-id",
+        secret_key="imagine-this-is-an-valid-secret-key",
+        source="en",
+        target="zh",
+    )
+    # Set the request response mock.
+    mock_response = Mock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {
+        "Response": {
+            "TargetText": "你好",
+            "Source": "en",
+            "Target": "zh",
+            "RequestId": "000ee211-f19e-4a34-a214-e2bb1122d248",
+        }
+    }
+    mock_requests.get.return_value = mock_response
+    translation = translator.translate("hello")
+    assert translation == "你好"
+
+
+@patch("deep_translator.tencent.requests")
+def test_wrong_api_key(mock_requests):
+    translator = TencentTranslator(
+        secret_id="imagine-this-is-a-wrong-secret-id",
+        secret_key="imagine-this-is-a-wrong-secret-id",
+        source="en",
+        target="zh",
+    )
+
+    mock_response = Mock()
+    mock_response.status_code = 200
+    mock_response.json.return_value = {
+        "Response": {
+            "Error": {
+                "Code": "AuthFailure.SignatureFailure",
+                "Message": "The provided credentials could not be validated. \
+                Please check your signature is correct.",
+            },
+            "RequestId": "ed93f3cb-f35e-473f-b9f3-0d451b8b79c6",
+        }
+    }
+    mock_requests.get.return_value = mock_response
+    with pytest.raises(TencentAPIerror):
+        translator.translate("Hello")
+
+
+# the remaining tests are actual requests to Tencent translator API and use secret_id and secret_key
+# if secret_id and secret_key variable is None, they are skipped
+
+secret_id = None
+secret_key = None
+
+
+@pytest.mark.skipif(
+    secret_id is None or secret_key is None,
+    reason="secret_id or secret_key is not provided",
+)
+def test_tencent_successful_post_onetarget():
+    posted = TencentTranslator(
+        secret_id=secret_id, secret_key=secret_key, source="en", target="zh"
+    ).translate("Hello! How are you?")
+    assert isinstance(posted, str)