feat(beta): Add a timeout for waiting on document translation

Author: leoncheng57

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 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
+* (beta) optional parameter to specify timeout for document translation calls
+<!-- * add to here -->
+### Changed
+<!-- * add to here -->
 
 ## [1.21.0] - 2025-01-15
 ### Added
@@ -324,7 +330,8 @@ Version increased to avoid conflicts with old packages on PyPI.
 ## [0.1.0] - 2021-07-26
 Initial version.
 
-
+<!-- Unreleased shoud never be deleted -->
+[Unreleased]: https://github.com/DeepLcom/deepl-python/compare/v1.21.0...HEAD
 [1.21.0]: https://github.com/DeepLcom/deepl-python/compare/v1.20.0...v1.21.0
 [1.20.0]: https://github.com/DeepLcom/deepl-python/compare/v1.19.1...v1.20.0
 [1.19.1]: https://github.com/DeepLcom/deepl-python/compare/v1.19.0...v1.19.1

deepl/translator.py

@@ -536,6 +536,7 @@ def translate_document_from_filepath(
         target_lang: str,
         formality: Union[str, Formality] = Formality.DEFAULT,
         glossary: Union[str, GlossaryInfo, None] = None,
+        timeout_s: Optional[int] = None,
     ) -> DocumentStatus:
         """Upload document at given input path, translate it into the target
         language, and download result to given output path.
@@ -551,6 +552,9 @@ def translate_document_from_filepath(
             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 timeout_s: (beta) (Optional) Maximum time to wait before
+            the call raises an error. Note that this is not accurate to the
+            second, but only polls every 5 seconds.
         :return: DocumentStatus when document translation completed, this
             allows the number of billed characters to be queried.
 
@@ -574,6 +578,7 @@ def translate_document_from_filepath(
                         formality=formality,
                         glossary=glossary,
                         output_format=output_format,
+                        timeout_s=timeout_s,
                     )
                 except Exception as e:
                     out_file.close()
@@ -591,6 +596,7 @@ def translate_document(
         glossary: Union[str, GlossaryInfo, None] = None,
         filename: Optional[str] = None,
         output_format: Optional[str] = None,
+        timeout_s: Optional[int] = None,
     ) -> DocumentStatus:
         """Upload document, translate it into the target language, and download
         result.
@@ -612,6 +618,9 @@ def translate_document(
             if uploading string or bytes containing file content.
         :param output_format: (Optional) Desired output file extension, if
             it differs from the input file format.
+        :param timeout_s: (beta) (Optional) Maximum time to wait before
+            the call raises an error. Note that this is not accurate to the
+            second, but only polls every 5 seconds.
         :return: DocumentStatus when document translation completed, this
             allows the number of billed characters to be queried.
 
@@ -630,7 +639,7 @@ def translate_document(
         )
 
         try:
-            status = self.translate_document_wait_until_done(handle)
+            status = self.translate_document_wait_until_done(handle, timeout_s)
             if status.ok:
                 self.translate_document_download(handle, output_document)
         except Exception as e:
@@ -752,27 +761,44 @@ def translate_document_get_status(
         )
 
     def translate_document_wait_until_done(
-        self, handle: DocumentHandle
+        self,
+        handle: DocumentHandle,
+        timeout_s: Optional[int] = None,
     ) -> DocumentStatus:
         """
         Continually polls the status of the document translation associated
         with the given handle, sleeping in between requests, and returns the
         final status when the translation completes (whether successful or
         not).
-
         :param handle: DocumentHandle to the document translation to wait on.
+        :param timeout_s: (beta) (Optional) Maximum time to wait before
+            the call raises an error. Note that this is not accurate to the
+            second, but only polls every 5 seconds.
         :return: DocumentStatus containing the status when completed.
         """
         status = self.translate_document_get_status(handle)
+        start_time_s = time.time()
         while status.ok and not status.done:
-            secs = 5.0  # seconds_remaining is currently unreliable, so just
-            # poll equidistantly
-            util.log_info(
-                f"Rechecking document translation status "
-                f"after sleeping for {secs:.3f} seconds."
-            )
-            time.sleep(secs)
-            status = self.translate_document_get_status(handle)
+            if (
+                timeout_s is not None
+                and time.time() - start_time_s > timeout_s
+            ):
+                raise DeepLException(
+                    f"Manual timeout of {timeout_s}s exceeded for"
+                    + " document translation",
+                    should_retry=False,
+                )
+            else:
+                secs = (
+                    5.0  # seconds_remaining is currently unreliable, so just
+                )
+                # poll equidistantly
+                util.log_info(
+                    f"Rechecking document translation status "
+                    f"after sleeping for {secs:.3f} seconds."
+                )
+                time.sleep(secs)
+                status = self.translate_document_get_status(handle)
         return status
 
     def translate_document_download(

tests/test_translate_document.py

@@ -73,6 +73,48 @@ def test_translate_document_with_waiting(
     assert example_document_translation == output_document_path.read_text()
 
 
+@needs_mock_server
+def test_translate_document_with_timeout_succeeds(
+    translator,
+    server,
+    example_document_path,
+    example_document_translation,
+    output_document_path,
+):
+    server.set_doc_queue_time(2 * 1000)
+    server.set_doc_translate_time(2 * 1000)
+
+    translator.translate_document_from_filepath(
+        example_document_path,
+        output_path=output_document_path,
+        timeout_s=10,
+        **default_lang_args,
+    )
+    assert example_document_translation == output_document_path.read_text()
+
+
+@needs_mock_server
+def test_translate_document_with_manual_timeout_fails(
+    translator,
+    server,
+    example_document_path,
+    output_document_path,
+):
+    server.set_doc_queue_time(11 * 1000)
+    server.set_doc_translate_time(11 * 1000)
+
+    with pytest.raises(
+        deepl.DeepLException,
+        match="Manual timeout of 10s exceeded for document translation",
+    ):
+        translator.translate_document_from_filepath(
+            example_document_path,
+            output_path=output_document_path,
+            timeout_s=10,
+            **default_lang_args,
+        )
+
+
 @needs_mock_server
 def test_translate_large_document(
     translator, example_large_document_path, example_large_document_translation