updated readme

README.rst

@@ -148,7 +148,7 @@ Imports
                                  PonsTranslator,
                                  LingueeTranslator,
                                  MyMemoryTranslator,
-                                 YandexTranslator
+                                 YandexTranslator,
                                  single_detection,
                                  batch_detection)
 
@@ -207,31 +207,29 @@ Google Translate
 
     translated = GoogleTranslator(source='auto', target='de').translate(text=text)
 
-- You can pass languages by name:
+- You can pass languages by name or by abbreviation:
 
 .. code-block:: python
 
     translated = GoogleTranslator(source='auto', target='german').translate(text=text)
 
-- Alternatively, you can pass languages by their abbreviation:
-
-.. code-block:: python
-
+    # Alternatively, you can pass languages by their abbreviation:
     translated = GoogleTranslator(source='en', target='de').translate(text=text)
 
-- Translate from a file:
+- Translate batch of texts
 
 .. code-block:: python
 
-    translated = GoogleTranslator(source='auto', target='german').translate_file('path/to/file')
+    texts = ["hallo welt", "guten morgen"]
 
-- Automate translation by detecting the source language and translate it automatically to the desired language
+    # the translate_sentences function is deprecated, use the translate_batch function instead
+    translated = MyMemoryTranslator('de', 'en').translate_batch(texts)
 
-.. code-block:: python
+- Translate from a file:
 
-    # this is useful if you have many sentences in different languages and want to automate the translation process
-    translated = GoogleTranslator(source='auto', target='de').translate_sentences([your_list_of_sentences])
+.. code-block:: python
 
+    translated = GoogleTranslator(source='auto', target='german').translate_file('path/to/file')
 
 Mymemory Translator
 --------------------
@@ -250,12 +248,14 @@ Mymemory Translator
 
     translated = MyMemoryTranslator(source='auto', target='french').translate(text)
 
-- Translate a list of sentences or paragraphs
+- Translate batch of texts
 
 .. code-block:: python
 
     texts = ["hallo welt", "guten morgen"]
-    translated = MyMemoryTranslator('de', 'english').translate_sentences(texts)
+
+    # the translate_sentences function is deprecated, use the translate_batch function instead
+    translated = MyMemoryTranslator('de', 'en').translate_batch(texts)
 
 - Translate from file
 
@@ -266,11 +266,9 @@ Mymemory Translator
     translated = MyMemoryTranslator(source='en', target='fr').translate_file(path)
 
 
-
 Linguee Translator
 -------------------
 
-
 .. code-block:: python
 
     word = 'good'
@@ -351,13 +349,26 @@ Yandex Translator
 .. code-block:: python
 
     # with auto detection | meaning provide only the target language and let yandex detect the source
-    translated = YandexTranslator('your_api_key').translate('Hallo, Welt', 'en')
+    translated = YandexTranslator('your_api_key').translate(source="auto", target="en", text='Hallo, Welt')
     print(f"translated text: {translated}")  # output -> translated text: Hello world
 
     # provide source and target language explicitly
-    translated = YandexTranslator('your_api_key').translate('Hallo, Welt', 'de-en')
+    translated = YandexTranslator('your_api_key').translate(source="de", target="en", text='Hallo, Welt')
     print(f"translated text: {translated}")  # output -> translated text: Hello world
 
+- File translation
+
+.. code-block:: python
+
+    translated = YandexTranslator('your_api_key').translate_file(source="auto", target="en", path="path_to_your_file")
+
+- Batch translation
+
+.. code-block:: python
+
+    translated = YandexTranslator('your_api_key').translate_batch(source="auto", target="de", batch=["hello world", "happy coding"])
+
+
 Usage from Terminal
 --------------------
 

deep_translator/google_trans.py

@@ -8,6 +8,8 @@ from deep_translator.parent import BaseTranslator
 from bs4 import BeautifulSoup
 import requests
 from time import sleep
+import warnings
+import logging
 
 
 class GoogleTranslator(BaseTranslator):
@@ -127,6 +129,8 @@ class GoogleTranslator(BaseTranslator):
         @param sentences: list of sentences to translate
         @return: list of all translated sentences
         """
+        warnings.warn("deprecated. Use the translate_batch function instead", DeprecationWarning, stacklevel=2)
+        logging.warning("deprecated. Use the translate_batch function instead")
         if not sentences:
             raise NotValidPayload(sentences)
 
@@ -158,7 +162,3 @@ class GoogleTranslator(BaseTranslator):
 
         return arr
 
-
-if __name__ == '__main__':
-    res = GoogleTranslator(target="fr").translate("good")
-    print(res)

deep_translator/mymemory.py

@@ -1,6 +1,9 @@
 """
 mymemory translator API
 """
+import logging
+import warnings
+
 from deep_translator.constants import BASE_URLS, GOOGLE_LANGUAGES_TO_CODES
 from deep_translator.exceptions import (NotValidPayload,
                                         TranslationNotFound,
@@ -120,6 +123,9 @@ class MyMemoryTranslator(BaseTranslator):
         @param sentences: list of sentences to translate
         @return: list of all translated sentences
         """
+        warn_msg = "deprecated. Use the translate_batch function instead"
+        warnings.warn(warn_msg, DeprecationWarning, stacklevel=2)
+        logging.warning(warn_msg)
         if not sentences:
             raise NotValidPayload(sentences)
 

deep_translator/yandex.py

@@ -52,57 +52,81 @@ class YandexTranslator(object):
             raise YandexDefaultException(response.status_code)
         return data.get("dirs")
 
+    def detect(self, text, proxies=None):
+        response = None
+        params = {
+            "text": text,
+            "format": "plain",
+            "key": self.api_key,
+        }
+        try:
+            url = self.__base_url.format(version=self.api_version, endpoint="detect")
+            response = requests.post(url, data=params, proxies=proxies)
+
+        except RequestError:
+            raise
+        except ConnectionError:
+            raise YandexDefaultException(503)
+        except ValueError:
+            raise YandexDefaultException(response.status_code)
+        else:
+            response = response.json()
+        language = response['lang']
+        status_code = response['code']
+        if status_code != 200:
+            raise RequestError()
+        elif not language:
+            raise YandexDefaultException(501)
+        return language
+
+    def translate(self, source, target, text, proxies=None):
+        params = {
+            "text": text,
+            "format": "plain",
+            "lang": target if source == "auto" else "{}-{}".format(source, target),
+            "key": self.api_key
+        }
+        try:
+            url = self.__base_url.format(version=self.api_version, endpoint="translate")
+            response = requests.post(url, data=params, proxies=proxies)
+        except ConnectionError:
+            raise YandexDefaultException(503)
+        else:
+            response = response.json()
+
+        if response['code'] == 429:
+            raise TooManyRequests()
 
-def detect(self, text, proxies=None):
-    response = None
-    params = {
-        "text": text,
-        "format": "plain",
-        "key": self.api_key,
-    }
-    try:
-        url = self.__base_url.format(version=self.api_version, endpoint="detect")
-        response = requests.post(url, data=params, proxies=proxies)
-
-    except RequestError:
-        raise
-    except ConnectionError:
-        raise YandexDefaultException(503)
-    except ValueError:
-        raise YandexDefaultException(response.status_code)
-    else:
-        response = response.json()
-    language = response['lang']
-    status_code = response['code']
-    if status_code != 200:
-        raise RequestError()
-    elif not language:
-        raise YandexDefaultException(501)
-    return language
-
-
-def translate(self, text, lang, proxies=None):
-    params = {
-        "text": text,
-        "format": "plain",
-        "lang": lang,
-        "key": self.api_key
-    }
-    try:
-        url = self.__base_url.format(version=self.api_version, endpoint="translate")
-        response = requests.post(url, data=params, proxies=proxies)
-    except ConnectionError:
-        raise YandexDefaultException(503)
-    else:
-        response = response.json()
-
-    if response['code'] == 429:
-        raise TooManyRequests()
-
-    if response['code'] != 200:
-        raise YandexDefaultException(response['code'])
-
-    if not response['text']:
-        raise TranslationNotFound()
-
-    return response['text']
+        if response['code'] != 200:
+            raise YandexDefaultException(response['code'])
+
+        if not response['text']:
+            raise TranslationNotFound()
+
+        return response['text']
+
+    def translate_file(self, source, target, path):
+        """
+        translate from a file
+        @param source: source language
+        @param target: target language
+        @param path: path to file
+        @return: translated text
+        """
+        try:
+            with open(path) as f:
+                text = f.read()
+
+            return self.translate(source, target, text)
+        except Exception as e:
+            raise e
+
+    def translate_batch(self, source, target, batch):
+        """
+        translate a batch of texts
+        @param source: source language
+        @param target: target language
+        @param batch: list of texts to translate
+        @return: list of translations
+        """
+        return [self.translate(source, target, text) for text in batch]

docs/usage.rst

@@ -20,6 +20,7 @@ Imports
                                  PonsTranslator,
                                  LingueeTranslator,
                                  MyMemoryTranslator,
+                                 YandexTranslator,
                                  single_detection,
                                  batch_detection)
 
@@ -78,31 +79,29 @@ Google Translate
 
     translated = GoogleTranslator(source='auto', target='de').translate(text=text)
 
-- You can pass languages by name:
+- You can pass languages by name or by abbreviation:
 
 .. code-block:: python
 
     translated = GoogleTranslator(source='auto', target='german').translate(text=text)
 
-- Alternatively, you can pass languages by their abbreviation:
-
-.. code-block:: python
-
+    # Alternatively, you can pass languages by their abbreviation:
     translated = GoogleTranslator(source='en', target='de').translate(text=text)
 
-- Translate from a file:
+- Translate batch of texts
 
 .. code-block:: python
 
-    translated = GoogleTranslator(source='auto', target='german').translate_file('path/to/file')
+    texts = ["hallo welt", "guten morgen"]
 
-- Automate translation by detecting the source language and translate it automatically to the desired language
+    # the translate_sentences function is deprecated, use the translate_batch function instead
+    translated = MyMemoryTranslator('de', 'en').translate_batch(texts)
 
-.. code-block:: python
+- Translate from a file:
 
-    # this is useful if you have many sentences in different languages and want to automate the translation process
-    translated = GoogleTranslator(source='auto', target='de').translate_sentences([your_list_of_sentences])
+.. code-block:: python
 
+    translated = GoogleTranslator(source='auto', target='german').translate_file('path/to/file')
 
 Mymemory Translator
 --------------------
@@ -121,12 +120,14 @@ Mymemory Translator
 
     translated = MyMemoryTranslator(source='auto', target='french').translate(text)
 
-- Translate a list of sentences or paragraphs
+- Translate batch of texts
 
 .. code-block:: python
 
     texts = ["hallo welt", "guten morgen"]
-    translated = MyMemoryTranslator('de', 'english').translate_sentences(texts)
+
+    # the translate_sentences function is deprecated, use the translate_batch function instead
+    translated = MyMemoryTranslator('de', 'en').translate_batch(texts)
 
 - Translate from file
 
@@ -137,11 +138,9 @@ Mymemory Translator
     translated = MyMemoryTranslator(source='en', target='fr').translate_file(path)
 
 
-
 Linguee Translator
 -------------------
 
-
 .. code-block:: python
 
     word = 'good'
@@ -222,13 +221,26 @@ Yandex Translator
 .. code-block:: python
 
     # with auto detection | meaning provide only the target language and let yandex detect the source
-    translated = YandexTranslator('your_api_key').translate('Hallo, Welt', 'en')
+    translated = YandexTranslator('your_api_key').translate(source="auto", target="en", text='Hallo, Welt')
     print(f"translated text: {translated}")  # output -> translated text: Hello world
 
     # provide source and target language explicitly
-    translated = YandexTranslator('your_api_key').translate('Hallo, Welt', 'de-en')
+    translated = YandexTranslator('your_api_key').translate(source="de", target="en", text='Hallo, Welt')
     print(f"translated text: {translated}")  # output -> translated text: Hello world
 
+- File translation
+
+.. code-block:: python
+
+    translated = YandexTranslator('your_api_key').translate_file(source="auto", target="en", path="path_to_your_file")
+
+- Batch translation
+
+.. code-block:: python
+
+    translated = YandexTranslator('your_api_key').translate_batch(source="auto", target="de", batch=["hello world", "happy coding"])
+
+
 Usage from Terminal
 --------------------