feat: add new Formality options: PREFER_MORE and PREFER_LESS

Author: daniel-jones-dev

CHANGELOG.md

@@ -5,11 +5,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [Unreleased]
+### Added
+* Add formality options `'prefer_less'` and `'prefer_more'`.
+
+
 ## [1.10.0] - 2022-09-09
 ### Added
 * New language available: Ukrainian (`'uk'`). Add language code constant and tests.
 
   Note: older library versions also support new languages, this update only adds new code constant.
+* Add new `Formality` options: `PREFER_MORE` and `PREFER_LESS`.
 ### Changed
 * Add note and workaround to README about Poetry error on Ubuntu 22.04.
   * Pull request [#48](https://github.com/DeepLcom/deepl-python/pull/48)
@@ -194,6 +200,7 @@ Version increased to avoid conflicts with old packages on PyPI.
 Initial version.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-python/compare/v1.10.0...HEAD
 [1.10.0]: https://github.com/DeepLcom/deepl-python/compare/v1.9.0...v1.10.0
 [1.9.0]: https://github.com/DeepLcom/deepl-python/compare/v1.8.0...v1.9.0
 [1.8.0]: https://github.com/DeepLcom/deepl-python/compare/v1.7.0...v1.8.0

deepl/translator.py

@@ -399,8 +399,21 @@ class Formality(Enum):
     """Options for formality parameter."""
 
     LESS = "less"
+    """Translate using informal language."""
+
     DEFAULT = "default"
+    """Translate using the default formality."""
+
     MORE = "more"
+    """Translate using formal language."""
+
+    PREFER_MORE = "prefer_more"
+    """Translate using formal language if the target language supports
+    formality, otherwise use default formality."""
+
+    PREFER_LESS = "prefer_less"
+    """Translate using informal language if the target language supports
+    formality, otherwise use default formality."""
 
     def __str__(self):
         return self.value
@@ -701,7 +714,8 @@ def translate_text(
             translation engine from correcting some formatting aspects, and
             instead leave the formatting unchanged.
         :param formality: (Optional) Desired formality for translation, as
-            Formality enum, "less" or "more".
+            Formality enum, "less", "more", "prefer_less", "prefer_more", or
+            "default".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
         :param tag_handling: (Optional) Type of tags to parse before
@@ -846,7 +860,7 @@ def translate_document_from_filepath(
         :param target_lang: Language code to translate document into, for
             example "DE", "EN-US", "FR".
         :param formality: (Optional) Desired formality for translation, as
-            Formality enum, "less" or "more".
+            Formality enum, "less", "more", "prefer_less", or "prefer_more".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
         :return: DocumentStatus when document translation completed, this
@@ -896,7 +910,7 @@ def translate_document(
         :param target_lang: Language code to translate document into, for
             example "DE", "EN-US", "FR".
         :param formality: (Optional) Desired formality for translation, as
-            Formality enum, "less" or "more".
+            Formality enum, "less", "more", "prefer_less", or "prefer_more".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
         :param filename: (Optional) Filename including extension, only required
@@ -953,7 +967,7 @@ def translate_document_upload(
         :param target_lang: Language code to translate document into, for
             example "DE", "EN-US", "FR".
         :param formality: (Optional) Desired formality for translation, as
-            Formality enum, "less" or "more".
+            Formality enum, "less", "more", "prefer_less", or "prefer_more".
         :param glossary: (Optional) glossary or glossary ID to use for
             translation. Must match specified source_lang and target_lang.
         :param filename: (Optional) Filename including extension, only required

tests/test_cli.py

@@ -97,6 +97,7 @@ def test_text(runner):
     # Test text options
     extra_options = [
         ("--formality more", "'formality': 'more'"),
+        ("--formality prefer_less", "'formality': 'prefer_less'"),
         ("--split-sentences 0", "'split_sentences': '0'"),
         ("--preserve-formatting", "'preserve_formatting': '1'"),
         ("--tag-handling xml", "'tag_handling': 'xml'"),

tests/test_translate_document.py

@@ -108,6 +108,21 @@ def test_translate_document_formality(
         **default_lang_args,
     )
     assert "Wie geht es dir?" == output_document_path.read_text()
+    example_document_path.write_text("How are you?")
+    translator.translate_document_from_filepath(
+        example_document_path,
+        output_document_path,
+        formality=deepl.Formality.PREFER_MORE,
+        **default_lang_args,
+    )
+    assert "Wie geht es Ihnen?" == output_document_path.read_text()
+    translator.translate_document_from_filepath(
+        example_document_path,
+        output_document_path,
+        formality=deepl.Formality.PREFER_LESS,
+        **default_lang_args,
+    )
+    assert "Wie geht es dir?" == output_document_path.read_text()
 
 
 def test_document_failure_during_translation(

tests/test_translate_text.py

@@ -200,6 +200,30 @@ def test_formality(translator, server):
             "Test", target_lang="EN-US", formality="more"
         )
 
+    result = translator.translate_text(
+        input_text, target_lang="DE", formality=deepl.Formality.PREFER_LESS
+    )
+    if not server.is_mock_server:
+        assert informal == result.text
+
+    result = translator.translate_text(
+        input_text, target_lang="DE", formality=deepl.Formality.PREFER_MORE
+    )
+    if not server.is_mock_server:
+        assert formal == result.text
+
+    # Using prefer_ * with a language that does not support formality is not
+    # an error
+    translator.translate_text(
+        input_text, target_lang="TR", formality=deepl.Formality.PREFER_MORE
+    )
+    with pytest.raises(
+        deepl.DeepLException, match=r".*formality.*target_lang.*"
+    ):
+        _ = translator.translate_text(
+            input_text, target_lang="TR", formality="more"
+        )
+
 
 def test_preserve_formatting(translator):
     # Note: this test may use the mock server that will not translate the text,