translate_document and translate_document_from_filepath return final DocumentStatus, allowing the number of billed characters to be queried

Author: daniel-jones-dev

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Add `error_message` property to `DocumentStatus`, describing the error in case of document translation failure.
 ### Changed
 * Improve error message if `translate_text_with_glossary` is called without an instance of `GlossaryInfo`.
+* `translate_document` and `translate_document_from_filepath` return final `DocumentStatus`, allowing the number of
+  billed characters to be queried.
 ### Deprecated
 ### Removed
 ### Fixed

deepl/translator.py

@@ -779,7 +779,7 @@ def translate_document_from_filepath(
         target_lang: str,
         formality: Union[str, Formality] = Formality.DEFAULT,
         glossary: Union[str, GlossaryInfo, None] = None,
-    ) -> None:
+    ) -> DocumentStatus:
         """Upload document at given input path, translate it into the target
         language, and download result to given output path.
 
@@ -794,6 +794,8 @@ def translate_document_from_filepath(
             Formality enum, "less" or "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
+            allows the number of billed characters to be queried.
 
         :raises DocumentTranslationException: If an error occurs during
             translation. The exception includes information about the document
@@ -802,7 +804,7 @@ def translate_document_from_filepath(
         with open(input_path, "rb") as in_file:
             with open(output_path, "wb") as out_file:
                 try:
-                    self.translate_document(
+                    return self.translate_document(
                         in_file,
                         out_file,
                         target_lang=target_lang,
@@ -824,7 +826,7 @@ def translate_document(
         target_lang: str,
         formality: Union[str, Formality] = Formality.DEFAULT,
         glossary: Union[str, GlossaryInfo, None] = None,
-    ) -> None:
+    ) -> DocumentStatus:
         """Upload document, translate it into the target language, and download
         result.
 
@@ -841,6 +843,8 @@ def translate_document(
             Formality enum, "less" or "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
+            allows the number of billed characters to be queried.
 
         :raises DocumentTranslationException: If an error occurs during
             translation, the exception includes the document handle.
@@ -877,6 +881,7 @@ def translate_document(
                 f"Error occurred while translating document: {error_message}",
                 handle,
             )
+        return status
 
     def translate_document_upload(
         self,

tests/test_translate_document.py

@@ -19,12 +19,15 @@ def test_translate_document_from_filepath(
     example_document_translation,
     output_document_path,
 ):
-    translator.translate_document_from_filepath(
+    status = translator.translate_document_from_filepath(
         example_document_path,
         output_path=output_document_path,
         **default_lang_args,
     )
     assert example_document_translation == output_document_path.read_text()
+    assert status.billed_characters == len(example_text["EN"])
+    assert status.status == deepl.DocumentStatus.Status.DONE
+    assert status.done
 
     # Note: cases with invalid file paths are not tested, because standard
     #     library functions are used.