Merge pull request #38 from KirillSklyarenko/microsoft_tests_readme

README.rst

@@ -431,6 +431,51 @@ Yandex Translator
 
     translated = YandexTranslator('your_api_key').translate_batch(source="auto", target="de", batch=["hello world", "happy coding"])
 
+Microsoft Translator
+------------------
+
+.. note::
+
+    You need to require an **api key** if you want to use the microsoft translator.
+    visit the official website for more information about how to get one.
+    Microsoft offers a free tier 0 subscription (2 million characters per month).
+
+- Required and optional attributes
+
+    There are two required attributes, namely "api_key" (string) and "target" (string or list).
+    Attribute "source" is optional.
+    Also, Microsoft API accepts a number of other optional attributes, you can find them here:  https://docs.microsoft.com/azure/cognitive-services/translator/reference/v3-0-translate
+    You can simply add them after the required attributes, see the example. 
+
+.. code-block:: python
+
+    text = 'happy coding'
+    translated = MicrosoftTranslator(api_key='some-key', target='de').translate(text=text)
+    translated_two_targets = MicrosoftTranslator(api_key='some-key', target=['de', 'ru']).translate(text=text)
+    translated_with_optional_attr = MicrosoftTranslator(api_key='some-key', target='de', textType='html']).translate(text=text)
+
+- You can pass languages by name or by abbreviation:
+
+.. code-block:: python
+
+    translated = MicrosoftTranslator(api_key='some-key', target='german').translate(text=text)
+
+    # Alternatively, you can pass languages by their abbreviation:
+    translated = MicrosoftTranslator(api_key='some-key', target='de').translate(text=text)
+
+- Translate batch of texts
+
+.. code-block:: python
+
+    texts = ["hallo welt", "guten morgen"]
+    translated = MicrosoftTranslator(api_key='some-key', target='english').translate_batch(texts)
+
+- Translate from a file:
+
+.. code-block:: python
+
+    translated = MicrosoftTranslator(api_key='some-key', target='german').translate_file('path/to/file')
+
 
 Usage from Terminal
 --------------------

deep_translator/tests/test_microsoft_trans.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+
+"""Tests for `deep_translator` package."""
+
+import pytest
+from unittest.mock import patch
+import requests
+
+from deep_translator import exceptions, MicrosoftTranslator
+
+
+# mocked request.post
+@patch.object(requests, 'post')
+def test_microsoft_successful_post_mock(mock_request_post):
+    returned_json = [{'translations': [{'text': 'See you later!', 'to': 'en'}]}]
+    def res():
+        r = requests.Response()
+        def json_func():
+            return returned_json
+        r.json = json_func
+        return r
+    mock_request_post.return_value = res()
+    assert MicrosoftTranslator(api_key="an_api_key", target="en").translate("auf wiedersehen!") == "See you later!"
+
+
+def test_MicrosoftAPIerror():
+    with pytest.raises(exceptions.MicrosoftAPIerror):
+        MicrosoftTranslator(api_key="empty", target="en").translate("text")
+
+
+# the remaining tests are actual requests to Microsoft API and use an api key
+# if APIkey variable is None, they are skipped
+
+APIkey = None
+
+
+@pytest.mark.skipif(APIkey is None, reason="api_key is not provided")
+def test_microsoft_successful_post_onetarget():
+    posted = MicrosoftTranslator(api_key=APIkey, target="en").translate("auf wiedersehen!")
+    assert isinstance(posted, str)
+
+
+@pytest.mark.skipif(APIkey is None, reason="api_key is not provided")
+def test_microsoft_successful_post_twotargets():
+    posted = MicrosoftTranslator(api_key=APIkey, target=["en", "ru"]).translate("auf wiedersehen!")
+    assert isinstance(posted, str)
+
+
+@pytest.mark.skipif(APIkey is None, reason="api_key is not provided")
+def test_incorrect_target_attributes():
+    with pytest.raises(exceptions.ServerException):
+        MicrosoftTranslator(api_key=APIkey, target="")
+    with pytest.raises(exceptions.ServerException):
+        MicrosoftTranslator(api_key="", target="nothing")
+
+
+@pytest.mark.skipif(APIkey is None, reason="api_key is not provided")
+def test_abbreviations():
+    m1 = MicrosoftTranslator(api_key=APIkey, source="en", target="fr")
+    m2 = MicrosoftTranslator(api_key=APIkey, source="English", target="French")
+    assert ''.join(m1.source) == ''.join(m2.source)
+    assert ''.join(m1.target) == ''.join(m2.target)