added typing

deep_translator/base.py

@@ -3,6 +3,7 @@
 from deep_translator.constants import GOOGLE_LANGUAGES_TO_CODES
 from deep_translator.exceptions import InvalidSourceOrTargetLanguage
 from abc import ABC, abstractmethod
+from typing import Optional, List, Union
 
 
 class BaseTranslator(ABC):
@@ -12,13 +13,13 @@ class BaseTranslator(ABC):
 
     def __init__(
         self,
-        base_url=None,
-        source="auto",
-        target="en",
-        payload_key=None,
-        element_tag=None,
-        element_query=None,
-        languages=None,
+        base_url: str,
+        languages: dict = GOOGLE_LANGUAGES_TO_CODES,
+        source: str = "auto",
+        target: str = "en",
+        payload_key: Optional[str] = None,
+        element_tag: Optional[str] = None,
+        element_query: Optional[dict] = None,
         **url_params
     ):
         """
@@ -26,8 +27,8 @@ class BaseTranslator(ABC):
         @param target: target language to translate to
         """
         self._base_url = base_url
-        self.languages: dict = GOOGLE_LANGUAGES_TO_CODES if not languages else languages
-        self.supported_languages: list = list(self.languages.keys())
+        self.languages = languages
+        self.supported_languages = list(self.languages.keys())
         if not source:
             raise InvalidSourceOrTargetLanguage(source)
         if not target:
@@ -55,18 +56,20 @@ class BaseTranslator(ABC):
             elif language in self.languages.keys():
                 yield self.languages[language]
 
-    def _same_source_target(self):
+    def _same_source_target(self) -> bool:
         return self._source == self._target
 
-    def get_supported_languages(self, as_dict=False, **kwargs):
+    def get_supported_languages(
+        self, as_dict: bool = False, **kwargs
+    ) -> Union[list, dict]:
         """
-        return the supported languages by the google translator
+        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 self.supported_languages if not as_dict else self.languages
 
-    def is_language_supported(self, language, **kwargs):
+    def is_language_supported(self, language: str, **kwargs) -> bool:
         """
         check if the language is supported by the translator
         @param language: a string for 1 language
@@ -82,7 +85,7 @@ class BaseTranslator(ABC):
             return False
 
     @abstractmethod
-    def translate(self, text, **kwargs):
+    def translate(self, text: str, **kwargs) -> str:
         """
         translate a text using a translator under the hood and return the translated text
         @param text: text to translate
@@ -91,7 +94,7 @@ class BaseTranslator(ABC):
         """
         return NotImplemented("You need to implement the translate method!")
 
-    def _translate_file(self, path, **kwargs):
+    def _translate_file(self, path: str, **kwargs) -> str:
         """
         translate directly from file
         @param path: path to the target file
@@ -106,7 +109,7 @@ class BaseTranslator(ABC):
         except Exception as e:
             raise e
 
-    def _translate_batch(self, batch=None, **kwargs):
+    def _translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a list of texts
         @param batch: list of texts you want to translate

deep_translator/cli.py

@@ -1,13 +1,14 @@
 """Console script for deep_translator."""
 import argparse
 from deep_translator.engines import __engines__
+from typing import Optional
 
 
 class CLI(object):
     translators_dict = __engines__
     translator = None
 
-    def __init__(self, custom_args=None):
+    def __init__(self, custom_args: Optional[list] = None):
         self.custom_args = custom_args
         self.args = self.parse_args()
         translator_class = self.translators_dict.get(self.args.translator, None)
@@ -20,7 +21,7 @@ class CLI(object):
             source=self.args.source, target=self.args.target
         )
 
-    def translate(self):
+    def translate(self) -> None:
         """
         function used to provide translations from the parsed terminal arguments
         @return: None
@@ -30,7 +31,7 @@ class CLI(object):
         print("-" * 50)
         print(f"Translation result: {res}")
 
-    def get_supported_languages(self):
+    def get_supported_languages(self) -> None:
         """
         function used to return the languages supported by the translator service from the parsed terminal arguments
         @return: None
@@ -42,7 +43,7 @@ class CLI(object):
         print(f"Languages supported by '{self.args.translator}' are :\n")
         print(translator_supported_languages)
 
-    def parse_args(self):
+    def parse_args(self) -> argparse.Namespace:
         """
         function responsible for parsing terminal arguments and provide them for further use in the translation process
         """
@@ -86,7 +87,7 @@ class CLI(object):
         )
         return parsed_args
 
-    def run(self):
+    def run(self) -> None:
         if self.args.languages:
             self.get_supported_languages()
         else:

deep_translator/deepl.py

@@ -1,5 +1,5 @@
 import requests
-
+from typing import Optional, List
 from deep_translator.validate import is_empty, validate_input
 from deep_translator.constants import BASE_URLS, DEEPL_LANGUAGE_TO_CODE
 from deep_translator.exceptions import (
@@ -16,7 +16,12 @@ class DeeplTranslator(BaseTranslator):
     """
 
     def __init__(
-        self, api_key=None, source="de", target="en", use_free_api=True, **kwargs
+        self,
+        api_key: Optional[str] = None,
+        source: str = "de",
+        target: str = "en",
+        use_free_api: bool = True,
+        **kwargs
     ):
         """
         @param api_key: your DeeplTranslator api key.
@@ -41,7 +46,7 @@ class DeeplTranslator(BaseTranslator):
             **kwargs
         )
 
-    def translate(self, text, **kwargs):
+    def translate(self, text: str, **kwargs) -> str:
         """
         @param text: text to translate
         @return: translated text
@@ -77,10 +82,10 @@ class DeeplTranslator(BaseTranslator):
             # Process and return the response.
             return res["translations"][0]["text"]
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         @param batch: list of texts to translate
         @return: list of translations

deep_translator/detection.py

@@ -3,6 +3,8 @@ language detection API
 """
 import requests
 from requests.exceptions import HTTPError
+from typing import Optional, List, Union
+
 
 # Module global config
 config = {
@@ -14,7 +16,7 @@ config = {
 }
 
 
-def get_request_body(text, api_key, *args, **kwargs):
+def get_request_body(text: Union[str, List[str]], api_key: str, *args, **kwargs):
     """
     send a request and return the response body parsed as dictionary
 
@@ -46,7 +48,9 @@ def get_request_body(text, api_key, *args, **kwargs):
             raise e
 
 
-def single_detection(text, api_key=None, detailed=False, *args, **kwargs):
+def single_detection(
+    text: str, api_key: Optional[str] = None, detailed: bool = False, *args, **kwargs
+):
     """
     function responsible for detecting the language from a text
 
@@ -66,7 +70,9 @@ def single_detection(text, api_key=None, detailed=False, *args, **kwargs):
         return lang
 
 
-def batch_detection(text_list, api_key, detailed=False, *args, **kwargs):
+def batch_detection(
+    text_list: List[str], api_key: str, detailed: bool = False, *args, **kwargs
+):
     """
     function responsible for detecting the language from a text
 

deep_translator/google.py

@@ -12,6 +12,7 @@ from deep_translator.base import BaseTranslator
 from deep_translator.validate import validate_input, is_empty
 from bs4 import BeautifulSoup
 import requests
+from typing import Optional, List
 
 
 class GoogleTranslator(BaseTranslator):
@@ -19,7 +20,13 @@ class GoogleTranslator(BaseTranslator):
     class that wraps functions, which use google translate under the hood to translate text(s)
     """
 
-    def __init__(self, source="auto", target="en", proxies=None, **kwargs):
+    def __init__(
+        self,
+        source: str = "auto",
+        target: str = "en",
+        proxies: Optional[dict] = None,
+        **kwargs
+    ):
         """
         @param source: source language to translate from
         @param target: target language to translate to
@@ -37,7 +44,7 @@ class GoogleTranslator(BaseTranslator):
 
         self._alt_element_query = {"class": "result-container"}
 
-    def translate(self, text, **kwargs):
+    def translate(self, text: str, **kwargs) -> str:
         """
         function that uses google translate to translate a text
         @param text: desired text to translate
@@ -89,7 +96,7 @@ class GoogleTranslator(BaseTranslator):
             else:
                 return element.get_text(strip=True)
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         """
         translate directly from file
         @param path: path to the target file
@@ -99,7 +106,7 @@ class GoogleTranslator(BaseTranslator):
         """
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch=None, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a list of texts
         @param batch: list of texts you want to translate

deep_translator/libre.py

@@ -3,7 +3,7 @@ LibreTranslate API
 """
 
 import requests
-
+from typing import Optional, List
 from deep_translator.validate import is_empty, validate_input
 from deep_translator.base import BaseTranslator
 from deep_translator.constants import BASE_URLS, LIBRE_LANGUAGES_TO_CODES
@@ -19,7 +19,13 @@ class LibreTranslator(BaseTranslator):
     class that wraps functions, which use libre translator under the hood to translate text(s)
     """
 
-    def __init__(self, source="auto", target="en", api_key=None, **kwargs):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        source: str = "auto",
+        target: str = "en",
+        **kwargs
+    ):
         """
         @param source: source language to translate from
         List of LibreTranslate nedpoints can be found at : https://github.com/LibreTranslate/LibreTranslate#mirrors
@@ -36,7 +42,7 @@ class LibreTranslator(BaseTranslator):
             languages=LIBRE_LANGUAGES_TO_CODES,
         )
 
-    def translate(self, text, **kwargs):
+    def translate(self, text: str, **kwargs) -> str:
         """
         function that uses microsoft translate to translate a text
         @param text: desired text to translate
@@ -76,7 +82,7 @@ class LibreTranslator(BaseTranslator):
             # Process and return the response.
             return res["translatedText"]
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         """
         translate directly from file
         @param path: path to the target file
@@ -86,7 +92,7 @@ class LibreTranslator(BaseTranslator):
         """
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch=None, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a list of texts
         @param batch: list of texts you want to translate

deep_translator/linguee.py

@@ -14,6 +14,7 @@ from deep_translator.base import BaseTranslator
 from bs4 import BeautifulSoup
 import requests
 from requests.utils import requote_uri
+from typing import Optional, List, Union
 
 
 class LingueeTranslator(BaseTranslator):
@@ -21,7 +22,9 @@ class LingueeTranslator(BaseTranslator):
     class that wraps functions, which use the linguee translator under the hood to translate word(s)
     """
 
-    def __init__(self, source, target="en", proxies=None, **kwargs):
+    def __init__(
+        self, source: str, target: str = "en", proxies: Optional[dict] = None, **kwargs
+    ):
         """
         @param source: source language to translate from
         @param target: target language to translate to
@@ -37,7 +40,9 @@ class LingueeTranslator(BaseTranslator):
             payload_key=None,  # key of text in the url
         )
 
-    def translate(self, word, return_all=False, **kwargs):
+    def translate(
+        self, word: str, return_all: bool = False, **kwargs
+    ) -> Union[str, List[str]]:
         """
         function that uses linguee to translate a word
         @param word: word to translate
@@ -82,7 +87,7 @@ class LingueeTranslator(BaseTranslator):
 
             return filtered_elements if return_all else filtered_elements[0]
 
-    def translate_words(self, words, **kwargs):
+    def translate_words(self, words: List[str], **kwargs) -> List[str]:
         """
         translate a batch of words together by providing them in a list
         @param words: list of words you want to translate

deep_translator/microsoft.py

@@ -7,6 +7,7 @@ from deep_translator.constants import BASE_URLS
 from deep_translator.exceptions import ServerException, MicrosoftAPIerror
 from deep_translator.base import BaseTranslator
 from deep_translator.validate import validate_input
+from typing import Optional, List
 
 
 class MicrosoftTranslator(BaseTranslator):
@@ -16,11 +17,11 @@ class MicrosoftTranslator(BaseTranslator):
 
     def __init__(
         self,
-        api_key=None,
-        region=None,
-        source=None,
-        target=None,
-        proxies=None,
+        api_key: Optional[str] = None,
+        region: Optional[str] = None,
+        source: str = "auto",
+        target: str = "en",
+        proxies: Optional[dict] = None,
         **kwargs,
     ):
         """
@@ -60,7 +61,7 @@ class MicrosoftTranslator(BaseTranslator):
 
         return {translation_dict[k]["name"].lower(): k for k in translation_dict.keys()}
 
-    def translate(self, text, **kwargs):
+    def translate(self, text: str, **kwargs) -> str:
         """
         function that uses microsoft translate to translate a text
         @param text: desired text to translate
@@ -97,7 +98,7 @@ class MicrosoftTranslator(BaseTranslator):
                 ]
                 return "\n".join(all_translations)
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         """
         translate from a file
         @param path: path to file
@@ -105,7 +106,7 @@ class MicrosoftTranslator(BaseTranslator):
         """
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a batch of texts
         @param batch: list of texts to translate

deep_translator/mymemory.py

@@ -10,6 +10,7 @@ from deep_translator.exceptions import (
 )
 from deep_translator.base import BaseTranslator
 import requests
+from typing import Optional, List, Union
 
 
 class MyMemoryTranslator(BaseTranslator):
@@ -17,7 +18,13 @@ class MyMemoryTranslator(BaseTranslator):
     class that uses the mymemory translator to translate texts
     """
 
-    def __init__(self, source="auto", target="en", proxies=None, **kwargs):
+    def __init__(
+        self,
+        source: str = "auto",
+        target: str = "en",
+        proxies: Optional[dict] = None,
+        **kwargs,
+    ):
         """
         @param source: source language to translate from
         @param target: target language to translate to
@@ -31,7 +38,9 @@ class MyMemoryTranslator(BaseTranslator):
             payload_key="q",
         )
 
-    def translate(self, text, return_all=False, **kwargs):
+    def translate(
+        self, text: str, return_all: bool = False, **kwargs
+    ) -> Union[str, List[str]]:
         """
         function that uses the mymemory translator to translate a text
         @param text: desired text to translate
@@ -73,7 +82,7 @@ class MyMemoryTranslator(BaseTranslator):
                 next_match = next(matches)
                 return next_match if not return_all else list(all_matches)
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         """
         translate directly from file
         @param path: path to the target file
@@ -83,7 +92,7 @@ class MyMemoryTranslator(BaseTranslator):
         """
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch=None, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a list of texts
         @param batch: list of texts you want to translate

deep_translator/papago.py

@@ -6,7 +6,7 @@ from deep_translator.constants import BASE_URLS, PAPAGO_LANGUAGE_TO_CODE
 from deep_translator.exceptions import TranslationNotFound
 from deep_translator.base import BaseTranslator
 import requests
-
+from typing import Optional, List
 from deep_translator.validate import validate_input
 
 
@@ -16,7 +16,12 @@ class PapagoTranslator(BaseTranslator):
     """
 
     def __init__(
-        self, client_id=None, secret_key=None, source="auto", target="en", **kwargs
+        self,
+        client_id: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        source: str = "auto",
+        target: str = "en",
+        **kwargs,
     ):
         """
         @param source: source language to translate from
@@ -37,7 +42,7 @@ class PapagoTranslator(BaseTranslator):
             **kwargs,
         )
 
-    def translate(self, text, **kwargs):
+    def translate(self, text: str, **kwargs) -> str:
         """
         function that uses google translate to translate a text
         @param text: desired text to translate
@@ -66,7 +71,7 @@ class PapagoTranslator(BaseTranslator):
             translated_text = result.get("translatedText")
             return translated_text
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         """
         translate directly from file
         @param path: path to the target file
@@ -76,7 +81,7 @@ class PapagoTranslator(BaseTranslator):
         """
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch=None, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a list of texts
         @param batch: list of texts you want to translate

deep_translator/pons.py

@@ -15,6 +15,7 @@ from deep_translator.exceptions import (
 )
 from deep_translator.base import BaseTranslator
 from requests.utils import requote_uri
+from typing import Optional, Union, List
 
 
 class PonsTranslator(BaseTranslator):
@@ -22,7 +23,9 @@ class PonsTranslator(BaseTranslator):
     class that uses PONS translator to translate words
     """
 
-    def __init__(self, source, target="en", proxies=None, **kwargs):
+    def __init__(
+        self, source: str, target: str = "en", proxies: Optional[dict] = None, **kwargs
+    ):
         """
         @param source: source language to translate from
         @param target: target language to translate to
@@ -39,7 +42,9 @@ class PonsTranslator(BaseTranslator):
             **kwargs,
         )
 
-    def translate(self, word, return_all=False, **kwargs):
+    def translate(
+        self, word: str, return_all: bool = False, **kwargs
+    ) -> Union[str, List[str]]:
         """
         function that uses PONS to translate a word
         @param word: word to translate
@@ -84,7 +89,7 @@ class PonsTranslator(BaseTranslator):
 
             return word_list if return_all else word_list[0]
 
-    def translate_words(self, words, **kwargs):
+    def translate_words(self, words: List[str], **kwargs) -> List[str]:
         """
         translate a batch of words together by providing them in a list
         @param words: list of words you want to translate

deep_translator/qcri.py

@@ -2,6 +2,7 @@ import requests
 from deep_translator.constants import BASE_URLS, QCRI_LANGUAGE_TO_CODE
 from deep_translator.exceptions import ServerException, TranslationNotFound
 from deep_translator.base import BaseTranslator
+from typing import Optional, List
 
 
 class QcriTranslator(BaseTranslator):
@@ -9,7 +10,13 @@ class QcriTranslator(BaseTranslator):
     class that wraps functions, which use the QRCI translator under the hood to translate word(s)
     """
 
-    def __init__(self, api_key=None, source="en", target="en", **kwargs):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        source: str = "en",
+        target: str = "en",
+        **kwargs,
+    ):
         """
         @param api_key: your qrci api key. Get one for free here https://mt.qcri.org/api/v1/ref
         """
@@ -32,7 +39,9 @@ class QcriTranslator(BaseTranslator):
             **kwargs,
         )
 
-    def _get(self, endpoint, params=None, return_text=True):
+    def _get(
+        self, endpoint: str, params: Optional[dict] = None, return_text: bool = True
+    ):
         if not params:
             params = self.params
         try:
@@ -56,7 +65,7 @@ class QcriTranslator(BaseTranslator):
     def domains(self):
         return self.get_domains()
 
-    def translate(self, text, **kwargs):
+    def translate(self, text: str, **kwargs) -> str:
         params = {
             "key": self.api_key,
             "langpair": f"{self._source}-{self._target}",
@@ -78,10 +87,10 @@ class QcriTranslator(BaseTranslator):
                     raise TranslationNotFound(text)
                 return translation
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a batch of texts
         @domain: domain

deep_translator/validate.py

@@ -1,11 +1,11 @@
 from deep_translator.exceptions import NotValidPayload, NotValidLength
 
 
-def is_empty(text: str):
+def is_empty(text: str) -> bool:
     return text == ""
 
 
-def validate_input(text: str, min_chars: int = 0, max_chars: int = 5000):
+def validate_input(text: str, min_chars: int = 0, max_chars: int = 5000) -> bool:
     """
     validate the target text to translate
     @param min_chars: min characters

deep_translator/yandex.py

@@ -11,6 +11,7 @@ from deep_translator.exceptions import (
 )
 from deep_translator.base import BaseTranslator
 from deep_translator.validate import validate_input
+from typing import Optional, List
 
 
 class YandexTranslator(BaseTranslator):
@@ -18,7 +19,13 @@ class YandexTranslator(BaseTranslator):
     class that wraps functions, which use the yandex translator under the hood to translate word(s)
     """
 
-    def __init__(self, api_key=None, source="en", target="de", **kwargs):
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        source: str = "en",
+        target: str = "de",
+        **kwargs
+    ):
         """
         @param api_key: your yandex api key
         """
@@ -43,7 +50,7 @@ class YandexTranslator(BaseTranslator):
         return self.get_supported_languages()
 
     @property
-    def dirs(self, proxies=None):
+    def dirs(self, proxies: Optional[dict] = None):
 
         try:
             url = self._base_url.format(version=self.api_version, endpoint="getLangs")
@@ -58,7 +65,7 @@ class YandexTranslator(BaseTranslator):
             raise ServerException(response.status_code)
         return data.get("dirs")
 
-    def detect(self, text, proxies=None):
+    def detect(self, text: str, proxies: Optional[dict] = None):
         response = None
         params = {
             "text": text,
@@ -85,7 +92,7 @@ class YandexTranslator(BaseTranslator):
             raise ServerException(501)
         return language
 
-    def translate(self, text, proxies=None, **kwargs):
+    def translate(self, text: str, proxies: Optional[dict] = None, **kwargs) -> str:
         if validate_input(text):
             params = {
                 "text": text,
@@ -116,7 +123,7 @@ class YandexTranslator(BaseTranslator):
 
             return response["text"]
 
-    def translate_file(self, path, **kwargs):
+    def translate_file(self, path: str, **kwargs) -> str:
         """
         translate from a file
         @param path: path to file
@@ -124,7 +131,7 @@ class YandexTranslator(BaseTranslator):
         """
         return self._translate_file(path, **kwargs)
 
-    def translate_batch(self, batch, **kwargs):
+    def translate_batch(self, batch: List[str], **kwargs) -> List[str]:
         """
         translate a batch of texts
         @param batch: list of texts to translate