fix: raise on failed translation memory jobs and local file errors

wait_until_translation_memory_job_done() raises DeepLException with the
API's error message when the job fails or expires and returns only a
completed job. With timeout_s, the last sleep is cut to the deadline.

import_translation_memory_from_filepath() reads the file before
creating the import job, and export_translation_memory_to_filepath()
checks the output path before creating the export job. Local I/O
failures raise DeepLException with the OSError as cause, and a failed
export removes its partially written file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -153,6 +153,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `DeepLException`; before they were always `False` and `None`.
 
 ### Changed
+- `wait_until_translation_memory_job_done()` raises `DeepLException` with the
+  API's error message when the job fails or expires, instead of returning the
+  job. It returns only a completed job. With `timeout_s`, the last sleep is cut
+  short so the wait no longer runs past the timeout.
+- `import_translation_memory_from_filepath()` reads the file before creating
+  the import job; a file that cannot be read raises `DeepLException` without
+  sending a request. `export_translation_memory_to_filepath()` checks that the
+  output directory exists and the path is writable before creating the export
+  job, and raises `DeepLException` otherwise.
 - `translate_text()` accepts `glossary` and `glossary_ids` without
   `source_lang`; DeepL detects the source language and uses the glossary
   dictionary for the detected language pair. Document translation with a
@@ -245,6 +254,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed errors from the pre-signed translation memory upload and download URLs
   reporting `should_retry` as false for HTTP 429 and 5xx, and dropping the
   response body of a failed download from the message.
+- Fixed `import_translation_memory_from_filepath()` and
+  `export_translation_memory_to_filepath()` raising a raw `OSError` for local
+  file failures; they now raise `DeepLException` with the `OSError` as cause.
+  A failed export no longer leaves a partially written file behind.
 - HTTP 401 responses now raise `AuthorizationException`, like 403. Before they
   raised `DeepLException` with "Unexpected status code: 401".
 - `DeepLException.should_retry` is now `True` for every HTTP 5xx error. It was

README.md

@@ -1238,6 +1238,11 @@ Importing takes a while: the API detects the uploaded file asynchronously, so
 the job keeps reporting `awaiting_input` for roughly half a minute after the
 upload before completing. Pass `timeout_s` to bound how long to wait.
 
+The file is read before the import job is created: a missing file raises
+`ValueError`, and a file that cannot be read raises `DeepLException` (with the
+`OSError` as its cause), in both cases without sending a request. A failed or
+expired import job raises `DeepLException` with the API's error message.
+
 The three steps are also available separately, for example to upload the file
 yourself or to poll for progress. `create_translation_memory_import()` returns
 an upload URL that the file must be uploaded to before processing starts, then
@@ -1268,6 +1273,12 @@ job = deepl_client.wait_until_translation_memory_job_done(
 )
 ```
 
+`wait_until_translation_memory_job_done()` polls every 5 seconds and returns
+the job once it is completed. If the job fails or expires it raises
+`DeepLException` with the API's error message. With `timeout_s` it raises
+`DeepLException` once the timeout is exceeded, cutting the last sleep short so
+the wait does not run past the timeout.
+
 Errors from the pre-signed upload and download URLs are not DeepL API errors:
 `upload_translation_memory_file()` and `download_translation_memory_export()`
 raise a plain `DeepLException` with the response body in the message,
@@ -1296,6 +1307,12 @@ job = deepl_client.export_translation_memory_to_filepath(
 )
 ```
 
+The output path is checked before the export job is created: if its directory
+does not exist, or the path is a directory or not writable,
+`DeepLException` is raised without sending a request. If the export job
+fails, or the download or writing the file fails, `DeepLException` is raised
+and a partially written file is removed.
+
 As with import, the individual steps are available separately. Note that the
 API may reuse a previously completed export of an unchanged translation memory,
 indicated by `reused_existing`.

deepl/deepl_client.py

@@ -29,7 +29,11 @@
     TranslationMemoryJob,
     TranslationMemorySegments,
 )
-from deepl.exceptions import DeepLException, GlossaryNotFoundException
+from deepl.exceptions import (
+    ConnectionException,
+    DeepLException,
+    GlossaryNotFoundException,
+)
 from deepl.translator import (
     Translator,
     _DOWNLOAD_CHUNK_SIZE,
@@ -59,6 +63,20 @@
 _T = TypeVar("_T")
 
 
+def _tm_job_action(job: TranslationMemoryJob) -> str:
+    if job.operation == TranslationMemoryJob.OPERATION_IMPORT:
+        return "importing"
+    if job.operation == TranslationMemoryJob.OPERATION_EXPORT:
+        return "exporting"
+    return "processing"
+
+
+def _tm_job_error_message(job: TranslationMemoryJob) -> str:
+    return (
+        job.result.error_message if job.result else None
+    ) or "unknown error"
+
+
 def _parse_improvements(json: Any, text_count: int) -> List[WriteResult]:
     improvements = json.get("improvements") if isinstance(json, dict) else None
     if not isinstance(improvements, list) or len(improvements) < text_count:
@@ -2153,8 +2171,8 @@ def wait_until_translation_memory_job_done(
         job: Union[str, TranslationMemoryJob],
         timeout_s: Optional[int] = None,
     ) -> TranslationMemoryJob:
-        """Polls a translation memory job until it finishes, sleeping between
-        requests, and returns the final status.
+        """Polls a translation memory job until it completes, sleeping 5
+        seconds between requests, and returns the completed job.
 
         Note that an import job keeps reporting "awaiting_input" for a while
         after its file has been uploaded, because the API detects the upload
@@ -2163,33 +2181,43 @@ def wait_until_translation_memory_job_done(
         its own, so pass timeout_s when that is a possibility.
 
         :param job: Job ID string or TranslationMemoryJob object.
-        :param timeout_s: (Optional) Maximum time to wait before raising an
-            error. Note that this is not accurate to the second, but only
-            polls every 5 seconds.
-        :return: TranslationMemoryJob containing the status when finished.
+        :param timeout_s: (Optional) Maximum time in seconds to wait before
+            raising an error. The last sleep is cut short so that the wait
+            does not run past the timeout.
+        :return: TranslationMemoryJob containing the completed status.
+
+        :raises DeepLException: If the job fails or expires, with the API's
+            error message, or if timeout_s is exceeded.
         """
         # Validates the reference; get_translation_memory_job() encodes it.
         self._job_id(job)
-        status = self.get_translation_memory_job(job)
         start_time_s = time.time()
-        while not status.done:
-            if (
-                timeout_s is not None
-                and time.time() - start_time_s > timeout_s
-            ):
+        status = self.get_translation_memory_job(job)
+        while True:
+            if not status.ok:
                 raise DeepLException(
-                    f"Manual timeout of {timeout_s}s exceeded for"
-                    + " translation memory job",
+                    f"Error occurred while {_tm_job_action(status)} "
+                    f"translation memory: {_tm_job_error_message(status)}",
                     should_retry=False,
                 )
+            if status.done:
+                return status
             secs = 5.0
+            if timeout_s is not None:
+                remaining_s = start_time_s + timeout_s - time.time()
+                if remaining_s <= 0:
+                    raise DeepLException(
+                        f"Manual timeout of {timeout_s}s exceeded for"
+                        + " translation memory job",
+                        should_retry=False,
+                    )
+                secs = min(secs, remaining_s)
             util.log_info(
                 f"Rechecking translation memory job status after sleeping "
                 f"for {secs:.3f} seconds."
             )
             time.sleep(secs)
             status = self.get_translation_memory_job(job)
-        return status
 
     def download_translation_memory_export(
         self,
@@ -2250,9 +2278,9 @@ def import_translation_memory_from_filepath(
         :param input_path: Path to the TMX file to import.
         :param display_name: (Optional) Name for the resulting translation
             memory, defaults to the file name.
-        :param timeout_s: (Optional) Maximum time to wait for the import to
-            finish. Note that this is not accurate to the second, but only
-            polls every 5 seconds.
+        :param timeout_s: (Optional) Maximum time in seconds to wait for the
+            import to finish. The last 5-second sleep between status checks is
+            cut short so that the wait does not run past the timeout.
         :param content_type: (Optional) MIME type of the file, declared when
             creating the import job and sent with the upload. Defaults to
             "application/xml".
@@ -2262,38 +2290,40 @@ def import_translation_memory_from_filepath(
         :return: TranslationMemoryJob for the completed import; its result
             carries the new translation memory ID.
 
-        :raises DeepLException: If the import fails.
+        :raises ValueError: If input_path does not exist.
+        :raises DeepLException: If the file cannot be read, the upload is
+            rejected, the import job fails or expires, or timeout_s is
+            exceeded.
         """
         file_path = pathlib.Path(input_path)
         if not file_path.exists():
             raise ValueError(f"file does not exist: {input_path}")
+        # Read the file before creating the job, so an unreadable file fails
+        # without leaving an import job waiting for its upload.
+        try:
+            with open(file_path, "rb") as input_file:
+                content = input_file.read()
+        except OSError as e:
+            raise DeepLException(
+                f"Error reading translation memory file {input_path}: {e}"
+            ) from e
 
         created = self.create_translation_memory_import(
             file_name=file_path.name,
-            content_length=file_path.stat().st_size,
+            content_length=len(content),
             content_type=content_type,
             display_name=display_name,
             extra_body_parameters=extra_body_parameters,
         )
-        with open(file_path, "rb") as input_file:
-            self.upload_translation_memory_file(
-                created,
-                input_file,
-                content_type=content_type or "application/xml",
-            )
+        self.upload_translation_memory_file(
+            created,
+            content,
+            content_type=content_type or "application/xml",
+        )
 
-        job = self.wait_until_translation_memory_job_done(
+        return self.wait_until_translation_memory_job_done(
             created.job_id, timeout_s
         )
-        if not job.ok:
-            error_message = (
-                job.result.error_message if job.result else None
-            ) or "unknown error"
-            raise DeepLException(
-                "Error occurred while importing translation memory: "
-                f"{error_message}"
-            )
-        return job
 
     def export_translation_memory_to_filepath(
         self,
@@ -2308,30 +2338,56 @@ def export_translation_memory_to_filepath(
         :param translation_memory: Translation memory ID string or
             TranslationMemoryInfo object.
         :param output_path: Path to write the exported TMX file to.
-        :param timeout_s: (Optional) Maximum time to wait for the export to
-            finish. Note that this is not accurate to the second, but only
-            polls every 5 seconds.
+        :param timeout_s: (Optional) Maximum time in seconds to wait for the
+            export to finish. The last 5-second sleep between status checks is
+            cut short so that the wait does not run past the timeout.
         :return: TranslationMemoryJob for the completed export.
 
-        :raises DeepLException: If the export fails.
+        :raises DeepLException: If output_path cannot be written (checked
+            before the export job is created), the export job fails or
+            expires, the download fails, or timeout_s is exceeded. A partially
+            written output file is removed.
         """
+        path = pathlib.Path(output_path)
+        # Check the output path before creating the job, so a path that
+        # cannot be written fails without exporting first.
+        directory = path.parent
+        if not directory.is_dir():
+            raise DeepLException(
+                f"Output directory does not exist: {directory}"
+            )
+        if path.is_dir():
+            raise DeepLException(f"Output path is a directory: {output_path}")
+        if not os.access(path if path.exists() else directory, os.W_OK):
+            raise DeepLException(f"Output path is not writable: {output_path}")
+
         created = self.create_translation_memory_export(translation_memory)
         job = self.wait_until_translation_memory_job_done(
             created.job_id, timeout_s
         )
-        if not job.ok:
-            error_message = (
-                job.result.error_message if job.result else None
-            ) or "unknown error"
-            raise DeepLException(
-                "Error occurred while exporting translation memory: "
-                f"{error_message}"
-            )
 
-        with open(output_path, "wb") as output_file:
-            self.download_translation_memory_export(
-                job, output_file, chunk_size=8192
-            )
+        try:
+            with open(path, "wb") as output_file:
+                self.download_translation_memory_export(
+                    job, output_file, chunk_size=8192
+                )
+        except BaseException as e:
+            # Do not leave a partial file behind.
+            try:
+                path.unlink()
+            except OSError:
+                pass
+            if isinstance(e, requests.exceptions.RequestException):
+                # The download stream broke off; not a local I/O failure.
+                raise ConnectionException(
+                    f"Error downloading translation memory export: {e}"
+                ) from e
+            if isinstance(e, OSError):
+                raise DeepLException(
+                    "Error writing translation memory export to "
+                    f"{output_path}: {e}"
+                ) from e
+            raise
         return job
 
     def _asset_call(