feat: support document translation output_format parameter, used to control translated file format

Author: daniel-jones-dev

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Added
+* Added `output_format` parameter for document upload function, that indicates
+  the file extension of the desired file format for the translated document. 
 * Added basic usage example of the library
 ### Fixed
 * Fixed typechecking errors when using `mypy`'s `strict` mode

README.md

@@ -244,6 +244,10 @@ arguments, the available `translate_document()` and
 
 - `formality`: same as in [Text translation options](#text-translation-options).
 - `glossary`: same as in [Text translation options](#text-translation-options).
+- `output_format`: (`translate_document()` only)
+  file extension of desired format of translated file, for example: `'pdf'`. If
+  unspecified, by default the translated file will be in the same format as the
+  input file. 
 
 ### Glossaries
 

deepl/__main__.py

@@ -8,7 +8,7 @@
 import os
 import pathlib
 import sys
-from typing import List
+from typing import List, Optional
 from deepl.util import _optional_import
 
 # Program name for integration with click.testing
@@ -51,7 +51,11 @@ def action_languages(translator: deepl.Translator, glossary: bool):
 
 
 def action_document(
-    translator: deepl.Translator, file: List[str], dest: str, **kwargs
+    translator: deepl.Translator,
+    file: List[str],
+    dest: str,
+    output_format: Optional[str],
+    **kwargs,
 ):
     """Action function for the document command."""
     if not os.path.exists(dest):
@@ -60,7 +64,12 @@ def action_document(
         raise Exception("Destination already exists, and is not a directory")
 
     for this_file in file:
-        output_path = os.path.join(dest, os.path.basename(this_file))
+        outfile_name = (
+            this_file
+            if not output_format
+            else (os.path.splitext(this_file)[0] + "." + output_format)
+        )
+        output_path = os.path.join(dest, os.path.basename(outfile_name))
         translator.translate_document_from_filepath(
             this_file, output_path, **kwargs
         )
@@ -370,6 +379,9 @@ def add_common_arguments(subparser: argparse.ArgumentParser):
     parser_document.add_argument(
         "file", nargs="+", help="file(s) to be translated."
     )
+    parser_document.add_argument(
+        "--output-format", type=str, default=None, help="output file extension"
+    )
     parser_document.add_argument(
         "dest", help="destination directory to store translated files."
     )

deepl/translator.py

@@ -540,6 +540,11 @@ def translate_document_from_filepath(
             translation. The exception includes information about the document
             request.
         """
+        # Determine output_format from output path
+        in_ext = pathlib.PurePath(input_path).suffix.lower()
+        out_ext = pathlib.PurePath(output_path).suffix.lower()
+        output_format = None if in_ext == out_ext else out_ext[1:]
+
         with open(input_path, "rb") as in_file:
             with open(output_path, "wb") as out_file:
                 try:
@@ -550,6 +555,7 @@ def translate_document_from_filepath(
                         source_lang=source_lang,
                         formality=formality,
                         glossary=glossary,
+                        output_format=output_format,
                     )
                 except Exception as e:
                     out_file.close()
@@ -566,6 +572,7 @@ def translate_document(
         formality: Union[str, Formality] = Formality.DEFAULT,
         glossary: Union[str, GlossaryInfo, None] = None,
         filename: Optional[str] = None,
+        output_format: Optional[str] = None,
     ) -> DocumentStatus:
         """Upload document, translate it into the target language, and download
         result.
@@ -585,6 +592,8 @@ def translate_document(
             translation. Must match specified source_lang and target_lang.
         :param filename: (Optional) Filename including extension, only required
             if uploading string or bytes containing file content.
+        :param output_format: (Optional) Desired output file extension, if
+            it differs from the input file format.
         :return: DocumentStatus when document translation completed, this
             allows the number of billed characters to be queried.
 
@@ -599,6 +608,7 @@ def translate_document(
             formality=formality,
             glossary=glossary,
             filename=filename,
+            output_format=output_format,
         )
 
         try:
@@ -625,6 +635,7 @@ def translate_document_upload(
         formality: Union[str, Formality, None] = None,
         glossary: Union[str, GlossaryInfo, None] = None,
         filename: Optional[str] = None,
+        output_format: Optional[str] = None,
     ) -> DocumentHandle:
         """Upload document to be translated and return handle associated with
         request.
@@ -642,12 +653,16 @@ def translate_document_upload(
             translation. Must match specified source_lang and target_lang.
         :param filename: (Optional) Filename including extension, only required
             if uploading string or bytes containing file content.
+        :param output_format: (Optional) Desired output file extension, if
+            it differs from the input file format.
         :return: DocumentHandle with ID and key identifying document.
         """
 
         request_data = self._check_language_and_formality(
             source_lang, target_lang, formality, glossary
         )
+        if output_format:
+            request_data["output_format"] = output_format
 
         files: Dict[str, Any] = {}
         if isinstance(input_document, (str, bytes)):

tests/conftest.py

@@ -323,27 +323,38 @@ def example_document_translation():
 
 
 @pytest.fixture
-def example_large_document_path(tmpdir):
+def example_large_document_translation():
+    return (example_text["DE"] + "\n") * 1000
+
+
+@pytest.fixture
+def input_dir_path(tmpdir):
     tmpdir = pathlib.Path(tmpdir)
-    path = tmpdir / "input" / "example_document.txt"
-    path.parent.mkdir()
-    path.write_text((example_text["EN"] + "\n") * 1000)
+    path = tmpdir / "input"
+    path.mkdir(exist_ok=True)
     return path
 
 
 @pytest.fixture
-def example_large_document_translation():
-    return (example_text["DE"] + "\n") * 1000
+def output_dir_path(tmpdir):
+    tmpdir = pathlib.Path(tmpdir)
+    path = tmpdir / "output"
+    path.mkdir(exist_ok=True)
+    return path
 
 
 @pytest.fixture
-def output_document_path(tmpdir):
-    tmpdir = pathlib.Path(tmpdir)
-    path = tmpdir / "output" / "example_document.txt"
-    path.parent.mkdir()
+def example_large_document_path(input_dir_path):
+    path = input_dir_path / "example_document.txt"
+    path.write_text((example_text["EN"] + "\n") * 1000)
     return path
 
 
+@pytest.fixture
+def output_document_path(output_dir_path):
+    return output_dir_path / "example_document.txt"
+
+
 # Decorate test functions with "@needs_mock_server" to skip them if a real
 #  server is used
 needs_mock_server = pytest.mark.skipif(

tests/test_translate_document.py

@@ -125,6 +125,25 @@ def test_translate_document_formality(
     assert "Wie geht es dir?" == output_document_path.read_text()
 
 
+@needs_mock_server
+def test_document_output_format(
+    translator,
+    example_document_path,
+    output_dir_path,
+):
+    # Mock server supports only TXT and HTML files, so translate TXT->HTML
+    example_document_path.write_text(example_text["EN"])
+    output_document_path = output_dir_path / "example.html"
+    translator.translate_document_from_filepath(
+        example_document_path,
+        output_document_path,
+        **default_lang_args,
+    )
+
+    output = output_document_path.read_text()
+    assert example_text["DE"] == output
+
+
 def test_document_failure_during_translation(
     translator, example_document_path, output_document_path
 ):