fixed the requests issue and added a check on text length

deep_translator/cli.py

@@ -1,4 +1,5 @@
 """Console script for deep_translator."""
+
 import argparse
 import sys
 from .google_trans import GoogleTranslator
@@ -8,6 +9,11 @@ from .linguee import LingueeTranslator
 
 
 def translate(args):
+    """
+    function used to provide translations from the parsed terminal arguments
+    @param args: parsed terminal arguments
+    @return: None
+    """
     translator = None
     if args.translator == 'google':
         translator = GoogleTranslator(source=args.source, target=args.target)
@@ -26,7 +32,10 @@ def translate(args):
 
 
 def main():
-    """Console script for deep_translator."""
+    """
+    function responsible for parsing terminal arguments and provide them for further use in the translation process
+
+    """
     parser = argparse.ArgumentParser()
     parser.add_argument('--translator', '-trans',
                         default='google', type=str, help="name of the translator you want to use")
@@ -36,12 +45,8 @@ def main():
 
     args = parser.parse_args()
     translate(args)
-    # print("Arguments: " + str(args))
-    # print("Replace this message by putting your code into "
-    #       "deep_translator.cli.main")
-    # return 0
+    # sys.exit()
 
 
 if __name__ == "__main__":
-    # sys.exit(main())  # pragma: no cover
     main()

deep_translator/configs.py

@@ -1,3 +1,7 @@
+"""
+configuration object that holds data about the language detection api
+"""
+
 config = {
     "url": 'https://ws.detectlanguage.com/0.2/detect',
     "headers": {

deep_translator/detection.py

@@ -1,10 +1,21 @@
+"""
+language detection API
+"""
 import requests
 from deep_translator.configs import config
 from requests.exceptions import HTTPError
 
 
 def get_request_body(text, api_key, *args):
+    """
+    send a request and return the response body parsed as dictionary
+
+    @param text: target text that you want to detect its language
+    @type text: str
+    @type api_key: str
+    @param api_key: your private API key
 
+    """
     if not api_key:
         raise Exception("you need to get an API_KEY for this to work. "
                         "Get one for free here: https://detectlanguage.com/documentation")
@@ -30,6 +41,12 @@ def get_request_body(text, api_key, *args):
 def single_detection(text, api_key=None, detailed=False, *args, **kwargs):
     """
     function responsible for detecting the language from a text
+
+    @param text: target text that you want to detect its language
+    @type text: str
+    @type api_key: str
+    @param api_key: your private API key
+    @param detailed: set to True if you want to get detailed information about the detection process
     """
     body = get_request_body(text, api_key)
     detections = body.get('detections')
@@ -42,6 +59,13 @@ def single_detection(text, api_key=None, detailed=False, *args, **kwargs):
 
 
 def batch_detection(text_list, api_key, detailed=False, *args):
+    """
+    function responsible for detecting the language from a text
+
+    @param text_list: target batch that you want to detect its language
+    @param api_key: your private API key
+    @param detailed: set to True if you want to get detailed information about the detection process
+    """
     body = get_request_body(text_list, api_key)
     detections = body.get('detections')
     res = [obj[0] for obj in detections]

deep_translator/exceptions.py

@@ -1,6 +1,14 @@
 
+
 class BaseError(Exception):
+    """
+    base error structure class
+    """
     def __init__(self, val, message):
+        """
+        @param val: actual value
+        @param message: message shown to the user
+        """
         self.val = val
         self.message = message
         super().__init__()
@@ -10,11 +18,17 @@ class BaseError(Exception):
 
 
 class LanguageNotSupportedException(BaseError):
+    """
+    exception thrown if the user uses a language that is not supported by the deep_translator
+    """
     def __init__(self, val, message="There is no support for the chosen language"):
         super().__init__(val, message)
 
 
 class NotValidPayload(BaseError):
+    """
+    exception thrown if the user enters an invalid payload
+    """
     def __init__(self,
                  val,
                  message='text must be a valid text with maximum 5000 character, otherwise it cannot be translated'):
@@ -22,6 +36,9 @@ class NotValidPayload(BaseError):
 
 
 class TranslationNotFound(BaseError):
+    """
+    exception thrown if no translation was found for the text provided by the user
+    """
     def __init__(self,
                  val,
                  message='No translation was found using the current translator. Try another translator?'):
@@ -29,6 +46,9 @@ class TranslationNotFound(BaseError):
 
 
 class ElementNotFoundInGetRequest(BaseError):
+    """
+    exception thrown if the html element was not found in the body parsed by beautifulsoup
+    """
     def __init__(self,
                  val,
                  message='Required element was not found in the API response'):
@@ -36,5 +56,21 @@ class ElementNotFoundInGetRequest(BaseError):
 
 
 class NotValidLength(BaseError):
-    def __init__(self, val, message="Length of text need to be between 0 and 5000"):
+    """
+    exception thrown if the provided text exceed the length limit of the translator
+    """
+    def __init__(self, val, min_chars, max_chars):
+        message = "Text length need to be between {} and {} characters".format(min_chars, max_chars)
         super(NotValidLength, self).__init__(val, message)
+
+
+class RequestError(Exception):
+    """
+    exception thrown if an error occured during the request call, e.g a connection problem.
+    """
+    def __init__(self, message="Request exception can happen due to an api connection error. "
+                               "Please check your connection and try again"):
+        self.message = message
+
+    def __str__(self):
+        return self.message

deep_translator/google_trans.py

@@ -1,6 +1,9 @@
+"""
+google translator API
+"""
 
 from deep_translator.constants import BASE_URLS, GOOGLE_LANGUAGES_TO_CODES
-from deep_translator.exceptions import LanguageNotSupportedException, TranslationNotFound, NotValidPayload
+from deep_translator.exceptions import LanguageNotSupportedException, TranslationNotFound, NotValidPayload, RequestError
 from deep_translator.parent import BaseTranslator
 from bs4 import BeautifulSoup
 import requests
@@ -8,7 +11,7 @@ import requests
 
 class GoogleTranslator(BaseTranslator):
     """
-    class that uses google translate to translate texts
+    class that wraps functions, which use google translate under the hood to translate text(s)
     """
     _languages = GOOGLE_LANGUAGES_TO_CODES
     supported_languages = list(_languages.keys())
@@ -34,12 +37,17 @@ class GoogleTranslator(BaseTranslator):
 
     @staticmethod
     def get_supported_languages(as_dict=False):
+        """
+        return the supported languages by the google translator
+        @param as_dict: if True, the languages will be returned as a dictionary mapping languages to their abbreviations
+        @return: list or dict
+        """
         return GoogleTranslator.supported_languages if not as_dict else GoogleTranslator._languages
 
     def _map_language_to_code(self, *languages):
         """
-
-        @param language: type of language
+        map language to its corresponding code (abbreviation) if the language was passed by its full name by the user
+        @param languages: list of languages
         @return: mapped value of the language or raise an exception if the language is not supported
         """
         for language in languages:
@@ -51,6 +59,11 @@ class GoogleTranslator(BaseTranslator):
                 raise LanguageNotSupportedException(language)
 
     def is_language_supported(self, *languages):
+        """
+        check if the language is supported by the translator
+        @param languages: list of languages
+        @return: bool or raise an Exception
+        """
         for lang in languages:
             if lang != 'auto' and lang not in self._languages.keys():
                 if lang != 'auto' and lang not in self._languages.values():
@@ -59,7 +72,7 @@ class GoogleTranslator(BaseTranslator):
 
     def translate(self, text, **kwargs):
         """
-        main function that uses google translate to translate a text
+        function that uses google translate to translate a text
         @param text: desired text to translate
         @return: str: translated text
         """
@@ -73,15 +86,25 @@ class GoogleTranslator(BaseTranslator):
             response = requests.get(self.__base_url,
                                     params=self._url_params)
 
+            if response.status_code != 200:
+                raise RequestError()
+
             soup = BeautifulSoup(response.text, 'html.parser')
             element = soup.find(self._element_tag, self._element_query)
+
             if not element:
-                # raise ElementNotFoundInGetRequest(element)
                 raise TranslationNotFound(text)
 
             return element.get_text(strip=True)
 
     def translate_file(self, path, **kwargs):
+        """
+        translate directly from file
+        @param path: path to the target file
+        @type path: str
+        @param kwargs: additional args
+        @return: str
+        """
         try:
             with open(path) as f:
                 text = f.read()

deep_translator/linguee.py

@@ -1,5 +1,13 @@
+"""
+linguee translator API
+"""
+
 from deep_translator.constants import BASE_URLS, LINGUEE_LANGUAGES_TO_CODES, LINGUEE_CODE_TO_LANGUAGE
-from deep_translator.exceptions import LanguageNotSupportedException, TranslationNotFound, NotValidPayload, ElementNotFoundInGetRequest
+from deep_translator.exceptions import (LanguageNotSupportedException,
+                                        TranslationNotFound,
+                                        NotValidPayload,
+                                        ElementNotFoundInGetRequest,
+                                        RequestError)
 from deep_translator.parent import BaseTranslator
 from bs4 import BeautifulSoup
 import requests
@@ -7,6 +15,9 @@ from requests.utils import requote_uri
 
 
 class LingueeTranslator(BaseTranslator):
+    """
+    class that wraps functions, which use the linguee translator under the hood to translate word(s)
+    """
     _languages = LINGUEE_LANGUAGES_TO_CODES
     supported_languages = list(_languages.keys())
 
@@ -30,13 +41,19 @@ class LingueeTranslator(BaseTranslator):
 
     @staticmethod
     def get_supported_languages(as_dict=False):
+        """
+        return the supported languages by the linguee translator
+        @param as_dict: if True, the languages will be returned as a dictionary mapping languages to their abbreviations
+        @return: list or dict
+        """
         return LingueeTranslator.supported_languages if not as_dict else LingueeTranslator._languages
 
     def _map_language_to_code(self, *languages, **kwargs):
         """
-        @param language: type of language
-        @return: mapped value of the language or raise an exception if the language is not supported
-        """
+         map language to its corresponding code (abbreviation) if the language was passed by its full name by the user
+         @param languages: list of languages
+         @return: mapped value of the language or raise an exception if the language is not supported
+         """
         for language in languages:
             if language in self._languages.values():
                 yield LINGUEE_CODE_TO_LANGUAGE[language]
@@ -46,6 +63,11 @@ class LingueeTranslator(BaseTranslator):
                 raise LanguageNotSupportedException(language)
 
     def is_language_supported(self, *languages, **kwargs):
+        """
+        check if the language is supported by the translator
+        @param languages: list of languages
+        @return: bool or raise an Exception
+        """
         for lang in languages:
             if lang not in self._languages.keys():
                 if lang not in self._languages.values():
@@ -53,12 +75,21 @@ class LingueeTranslator(BaseTranslator):
         return True
 
     def translate(self, word, return_all=False, **kwargs):
-
-        if self._validate_payload(word):
+        """
+        function that uses linguee to translate a word
+        @param word: word to translate
+        @type word: str
+        @param return_all: set to True to return all synonym of the translated word
+        @type return_all: bool
+        @return: str: translated word
+        """
+        if self._validate_payload(word, max_chars=50):
             # %s-%s/translation/%s.html
             url = "{}{}-{}/translation/{}.html".format(self.__base_url, self._source, self._target, word)
             url = requote_uri(url)
             response = requests.get(url)
+            if response.status_code != 200:
+                raise RequestError()
             soup = BeautifulSoup(response.text, 'html.parser')
             elements = soup.find_all(self._element_tag, self._element_query)
             if not elements:
@@ -78,6 +109,12 @@ class LingueeTranslator(BaseTranslator):
             return filtered_elements if return_all else filtered_elements[0]
 
     def translate_words(self, words, **kwargs):
+        """
+        translate a batch of words together by providing them in a list
+        @param words: list of words you want to translate
+        @param kwargs: additional args
+        @return: list of translated words
+        """
         if not words:
             raise NotValidPayload(words)
 

deep_translator/mymemory.py

@@ -1,13 +1,15 @@
-
+"""
+mymemory translator API
+"""
 from deep_translator.constants import BASE_URLS, GOOGLE_LANGUAGES_TO_CODES
-from deep_translator.exceptions import NotValidPayload, TranslationNotFound, LanguageNotSupportedException
+from deep_translator.exceptions import NotValidPayload, TranslationNotFound, LanguageNotSupportedException, RequestError
 from deep_translator.parent import BaseTranslator
 import requests
 
 
 class MyMemoryTranslator(BaseTranslator):
     """
-    class that uses google translate to translate texts
+    class that uses the mymemory translator to translate texts
     """
     _languages = GOOGLE_LANGUAGES_TO_CODES
     supported_languages = list(_languages.keys())
@@ -32,13 +34,18 @@ class MyMemoryTranslator(BaseTranslator):
 
     @staticmethod
     def get_supported_languages(as_dict=False):
+        """
+         return the supported languages by the mymemory translator
+         @param as_dict: if True, the languages will be returned as a dictionary mapping languages to their abbreviations
+         @return: list or dict
+         """
         return MyMemoryTranslator.supported_languages if not as_dict else MyMemoryTranslator._languages
 
     def _map_language_to_code(self, *languages):
         """
-
-        @param language: type of language
-        @return: mapped value of the language or raise an exception if the language is not supported
+          map language to its corresponding code (abbreviation) if the language was passed by its full name by the user
+          @param languages: list of languages
+          @return: mapped value of the language or raise an exception if the language is not supported
         """
         for language in languages:
             if language in self._languages.values() or language == 'auto':
@@ -49,6 +56,11 @@ class MyMemoryTranslator(BaseTranslator):
                 raise LanguageNotSupportedException(language)
 
     def is_language_supported(self, *languages):
+        """
+        check if the language is supported by the translator
+        @param languages: list of languages
+        @return: bool or raise an Exception
+        """
         for lang in languages:
             if lang != 'auto' and lang not in self._languages.keys():
                 if lang != 'auto' and lang not in self._languages.values():
@@ -57,13 +69,14 @@ class MyMemoryTranslator(BaseTranslator):
 
     def translate(self, text, return_all=False, **kwargs):
         """
-        main function that uses google translate to translate a text
+        function that uses the mymemory translator to translate a text
         @param text: desired text to translate
-        @param return_all: set True to return all synonyms
-        @return: str: translated text
+        @type text: str
+        @param return_all: set to True to return all synonym/similars of the translated text
+        @return: str or list
         """
 
-        if self._validate_payload(text):
+        if self._validate_payload(text, max_chars=500):
             text = text.strip()
 
             if self.payload_key:
@@ -74,6 +87,10 @@ class MyMemoryTranslator(BaseTranslator):
             response = requests.get(self.__base_url,
                                     params=self._url_params,
                                     headers=self.headers)
+
+            if response.status_code != 200:
+                raise RequestError()
+
             data = response.json()
             if not data:
                 TranslationNotFound(text)
@@ -111,3 +128,18 @@ class MyMemoryTranslator(BaseTranslator):
         except Exception as e:
             raise e
 
+    def translate_file(self, path, **kwargs):
+        """
+         translate directly from file
+         @param path: path to the target file
+         @type path: str
+         @param kwargs: additional args
+         @return: str
+         """
+        try:
+            with open(path) as f:
+                text = f.read()
+
+            return self.translate(text=text)
+        except Exception as e:
+            raise e

deep_translator/parent.py

@@ -1,4 +1,4 @@
-"""Main module."""
+"""parent translator class"""
 
 from deep_translator.exceptions import NotValidPayload, NotValidLength
 from abc import ABC, abstractmethod
@@ -6,7 +6,7 @@ from abc import ABC, abstractmethod
 
 class BaseTranslator(ABC):
     """
-    class that serve as a parent translator class for other different translators
+    Abstract class that serve as a parent translator for other different translators
     """
     def __init__(self,
                  base_url=None,
@@ -34,7 +34,7 @@ class BaseTranslator(ABC):
     @staticmethod
     def _validate_payload(payload, min_chars=1, max_chars=5000):
         """
-        validate the text text to translate
+        validate the target text to translate
         @param payload: text to translate
         @return: bool
         """
@@ -42,14 +42,27 @@ class BaseTranslator(ABC):
         if not payload or not isinstance(payload, str):
             raise NotValidPayload(payload)
         if not BaseTranslator.__check_length(payload, min_chars, max_chars):
-            raise NotValidLength
+            raise NotValidLength(payload, min_chars, max_chars)
         return True
 
     @staticmethod
     def __check_length(payload, min_chars, max_chars):
+        """
+        check length of the provided target text to translate
+        @param payload: text to translate
+        @param min_chars: minimum characters allowed
+        @param max_chars: maximum characters allowed
+        @return: bool
+        """
         return True if min_chars < len(payload) < max_chars else False
 
     @abstractmethod
     def translate(self, text, **kwargs):
+        """
+        translate a text using a translator under the hood and return the translated text
+        @param text: text to translate
+        @param kwargs: additional arguments
+        @return: str
+        """
         return NotImplemented('You need to implement the translate method!')
 

deep_translator/pons.py

@@ -1,8 +1,14 @@
-
+"""
+pons translator API
+"""
 from bs4 import BeautifulSoup
 import requests
 from deep_translator.constants import BASE_URLS, PONS_LANGUAGES_TO_CODES, PONS_CODES_TO_LANGUAGES
-from deep_translator.exceptions import LanguageNotSupportedException, TranslationNotFound, NotValidPayload, ElementNotFoundInGetRequest
+from deep_translator.exceptions import (LanguageNotSupportedException,
+                                        TranslationNotFound,
+                                        NotValidPayload,
+                                        ElementNotFoundInGetRequest,
+                                        RequestError)
 from deep_translator.parent import BaseTranslator
 from requests.utils import requote_uri
 
@@ -34,12 +40,18 @@ class PonsTranslator(BaseTranslator):
 
     @staticmethod
     def get_supported_languages(as_dict=False):
+        """
+          return the supported languages by the linguee translator
+          @param as_dict: if True, the languages will be returned as a dictionary mapping languages to their abbreviations
+          @return: list or dict
+          """
         return PonsTranslator.supported_languages if not as_dict else PonsTranslator._languages
 
     def _map_language_to_code(self, *languages, **kwargs):
         """
-        @param language: type of language
-        @return: mapped value of the language or raise an exception if the language is not supported
+           map language to its corresponding code (abbreviation) if the language was passed by its full name by the user
+           @param languages: list of languages
+           @return: mapped value of the language or raise an exception if the language is not supported
         """
         for language in languages:
             if language in self._languages.values():
@@ -50,6 +62,11 @@ class PonsTranslator(BaseTranslator):
                 raise LanguageNotSupportedException(language)
 
     def is_language_supported(self, *languages, **kwargs):
+        """
+         check if the language is supported by the translator
+         @param languages: list of languages
+         @return: bool or raise an Exception
+         """
         for lang in languages:
             if lang not in self._languages.keys():
                 if lang not in self._languages.values():
@@ -57,13 +74,25 @@ class PonsTranslator(BaseTranslator):
         return True
 
     def translate(self, word, return_all=False, **kwargs):
-
-        if self._validate_payload(word):
+        """
+        function that uses PONS to translate a word
+        @param word: word to translate
+        @type word: str
+        @param return_all: set to True to return all synonym of the translated word
+        @type return_all: bool
+        @return: str: translated word
+        """
+        if self._validate_payload(word, max_chars=50):
             url = "{}{}-{}/{}".format(self.__base_url, self._source, self._target, word)
             url = requote_uri(url)
             response = requests.get(url)
+
+            if response.status_code != 200:
+                raise RequestError()
+
             soup = BeautifulSoup(response.text, 'html.parser')
             elements = soup.findAll(self._element_tag, self._element_query)
+
             if not elements:
                 raise ElementNotFoundInGetRequest(word)
 
@@ -87,6 +116,12 @@ class PonsTranslator(BaseTranslator):
             return word_list if return_all else word_list[0]
 
     def translate_words(self, words, **kwargs):
+        """
+        translate a batch of words together by providing them in a list
+        @param words: list of words you want to translate
+        @param kwargs: additional args
+        @return: list of translated words
+        """
         if not words:
             raise NotValidPayload(words)
 

deep_translator/tests/test_google_trans.py

@@ -29,6 +29,7 @@ def test_inputs():
     with pytest.raises(exceptions.LanguageNotSupportedException):
         GoogleTranslator(source="auto", target="nothing")
 
+    # test abbreviations and languages
     g1 = GoogleTranslator("en", "fr")
     g2 = GoogleTranslator("english", "french")
     assert g1._source == g2._source
@@ -48,3 +49,6 @@ def test_payload(google_translator):
 
     with pytest.raises(exceptions.NotValidPayload):
         google_translator.translate(text=[])
+
+    with pytest.raises(exceptions.NotValidLength):
+        google_translator.translate("a"*5001)

deep_translator/tests/test_linguee.py

@@ -44,3 +44,6 @@ def test_payload(linguee):
 
     with pytest.raises(exceptions.NotValidPayload):
         linguee.translate([])
+
+    with pytest.raises(exceptions.NotValidLength):
+        linguee.translate("a"*51)

deep_translator/tests/test_mymemory.py

@@ -29,6 +29,7 @@ def test_inputs():
     assert m1._source == m2._source
     assert m1._target == m2._target
 
+
 def test_payload(mymemory):
 
     with pytest.raises(exceptions.NotValidPayload):
@@ -42,3 +43,6 @@ def test_payload(mymemory):
 
     with pytest.raises(exceptions.NotValidPayload):
         mymemory.translate(text=[])
+
+    with pytest.raises(exceptions.NotValidLength):
+        mymemory.translate(text="a"*501)

deep_translator/tests/test_pons.py

@@ -29,6 +29,7 @@ def test_inputs():
     assert l1._source == l2._source
     assert l1._target == l2._target
 
+
 def test_payload(pons):
 
     with pytest.raises(exceptions.NotValidPayload):
@@ -42,3 +43,6 @@ def test_payload(pons):
 
     with pytest.raises(exceptions.NotValidPayload):
         pons.translate([])
+
+    with pytest.raises(exceptions.NotValidLength):
+        pons.translate("a" * 51)