feat: add show_billed_characters option to translate_text()

Author: daniel-jones-dev

CHANGELOG.md

@@ -5,6 +5,11 @@ 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
+* Added `billed_characters` to response from `translate_text()`.
+
+
 ## [1.18.0] - 2024-04-26
 ### Added
 * New language available: Arabic (`'ar'`). Add language code constants and tests.
@@ -294,6 +299,7 @@ Version increased to avoid conflicts with old packages on PyPI.
 Initial version.
 
 
+[Unreleased]: https://github.com/DeepLcom/deepl-python/compare/v1.18.0...HEAD
 [1.18.0]: https://github.com/DeepLcom/deepl-python/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/DeepLcom/deepl-python/compare/v1.16.1...v1.17.0
 [1.16.1]: https://github.com/DeepLcom/deepl-python/compare/v1.16.0...v1.16.1

README.md

@@ -96,9 +96,10 @@ There are additional optional arguments to control translation, see
 [Text translation options](#text-translation-options) below.
 
 `translate_text()` returns a `TextResult`, or a list of `TextResult`s
-corresponding to your input text(s). `TextResult` has two properties: `text` is
-the translated text, and `detected_source_lang` is the detected source language
-code.
+corresponding to your input text(s). `TextResult` has the following properties:
+- `text` is the translated text,
+- `detected_source_lang` is the detected source language code,
+- `billed_characters` is the number of characters billed for the translation. 
 
 ```python
 # Translate text into a target language, in this case, French:
@@ -107,12 +108,15 @@ print(result.text)  # "Bonjour, le monde !"
 
 # Translate multiple texts into British English
 result = translator.translate_text(
-    ["お元気ですか？", "¿Cómo estás?"], target_lang="EN-GB"
+    ["お元気ですか？", "¿Cómo estás?"],
+    target_lang="EN-GB",
 )
 print(result[0].text)  # "How are you?"
 print(result[0].detected_source_lang)  # "JA" the language code for Japanese
+print(result[0].billed_characters)  # 7 - the number of characters in the source text "お元気ですか？"
 print(result[1].text)  # "How are you?"
 print(result[1].detected_source_lang)  # "ES" the language code for Spanish
+print(result[1].billed_characters)  # 12 - the number of characters in the source text "¿Cómo estás?"
 
 # Translate into German with less and more Formality:
 print(

deepl/__main__.py

@@ -78,6 +78,7 @@ def action_document(
 def action_text(
     translator: deepl.Translator,
     show_detected_source: bool = False,
+    show_billed_characters: Optional[bool] = None,
     **kwargs,
 ):
     """Action function for the text command."""
@@ -88,6 +89,13 @@ def action_text(
     for output in output_list:
         if show_detected_source:
             print(f"Detected source language: {output.detected_source_lang}")
+        if show_billed_characters:
+            text_value = (
+                "unknown"
+                if output.billed_characters is None
+                else output.billed_characters
+            )
+            print(f"Billed characters: {text_value}")
         print(output.text)
 
 
@@ -311,6 +319,12 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
         action="store_true",
         help="leave original formatting unchanged during translation",
     )
+    parser_text.add_argument(
+        "--show-billed-characters",
+        dest="show_billed_characters",
+        action="store_true",
+        help="print billed characters for each text",
+    )
     parser_text.add_argument(
         "text",
         nargs="+",

deepl/api_data.py

@@ -12,9 +12,15 @@
 class TextResult:
     """Holds the result of a text translation request."""
 
-    def __init__(self, text: str, detected_source_lang: str):
+    def __init__(
+        self,
+        text: str,
+        detected_source_lang: str,
+        billed_characters: int,
+    ):
         self.text = text
         self.detected_source_lang = detected_source_lang
+        self.billed_characters = billed_characters
 
     def __str__(self):
         return self.text

deepl/translator.py

@@ -411,6 +411,10 @@ def translate_text(
         )
         request_data["text"] = text
 
+        # Always send show_billed_characters=true, remove when the API default
+        # is changed to true
+        request_data["show_billed_characters"] = True
+
         if context is not None:
             request_data["context"] = context
         if split_sentences is not None:
@@ -452,12 +456,17 @@ def join_tags(tag_argument: Union[str, Iterable[str]]) -> List[str]:
         output = []
         for translation in translations:
             text = translation.get("text", "") if translation else ""
-            lang = (
+            detected_source_language = (
                 translation.get("detected_source_language", "")
                 if translation
                 else ""
             )
-            output.append(TextResult(text, detected_source_lang=lang))
+            billed_characters = util.get_int_safe(
+                translation, "billed_characters"
+            )
+            output.append(
+                TextResult(text, detected_source_language, billed_characters)
+            )
 
         return output if multi_input else output[0]
 

tests/test_general.py

@@ -32,10 +32,11 @@ def test_example_translation(lang, translator):
 
     input_text = example_text[lang]
     source_lang = deepl.Language.remove_regional_variant(lang)
-    result_text = translator.translate_text(
+    result = (translator.translate_text(
         input_text, source_lang=source_lang, target_lang="EN-US"
-    ).text.lower()
-    assert "proton" in result_text
+    ))
+    assert "proton" in result.text.lower()
+    assert result.billed_characters == len(input_text)
 
 
 @needs_real_server

tests/test_translate_text.py

@@ -14,6 +14,7 @@ def test_single_text(translator):
     assert example_text["DE"] == result.text
     assert "EN" == result.detected_source_lang
     assert example_text["DE"] == str(result)
+    assert result.billed_characters == len(example_text["EN"])
 
 
 def test_string_list(translator):