feat: deprecate downloads without output_file and raise the default chunk_size

translate_document_download() and download_translation_memory_export()
now emit a DeprecationWarning when called without output_file; they
still return the streaming requests.Response. Their default chunk_size
is 64 KiB instead of 1 byte, so writing to output_file no longer makes
one write call per byte. The written content is unchanged.

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

Author: hive-bot

CHANGELOG.md

@@ -62,8 +62,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `/v2/glossary-language-pairs` endpoints. Public signatures and return
   types are unchanged, but the returned language lists may now include
   additional languages.
+- The default `chunk_size` of `translate_document_download()` and
+  `download_translation_memory_export()` is now 64 KiB instead of 1 byte, so
+  downloads into `output_file` no longer write one byte per call. The written
+  content is unchanged; an explicit `chunk_size` still applies.
 
 ### Deprecated
+- Calling `translate_document_download()` or
+  `download_translation_memory_export()` without `output_file` now emits a
+  `DeprecationWarning`. It still returns the streaming `requests.Response`; in
+  the next major version `output_file` will be required and both methods will
+  return `None`.
 - Passing `skip_language_check` to `Translator()` or `DeepLClient()`, or
   `skip_cache` to `get_source_languages()` or `get_target_languages()`, now
   emits a `DeprecationWarning`. Both parameters have no effect and will be

README.md

@@ -342,6 +342,12 @@ these steps individually, you can instead use the following functions directly:
   `translate_document_wait_until_done()`), and
 - `translate_document_download()`
 
+`translate_document_download()` writes the translated document to the
+file-like object given as `output_file`, in chunks of `chunk_size` bytes
+(default 64 KiB). Calling it without `output_file` returns the streaming
+`requests.Response` instead; this is deprecated, emits a `DeprecationWarning`,
+and `output_file` will be required in the next major version.
+
 #### Document translation options
 
 In addition to the input file, output file, `source_lang` and `target_lang`
@@ -1140,6 +1146,11 @@ with open("/path/to/exported.tmx", "wb") as output_file:
     )
 ```
 
+`download_translation_memory_export()` writes in chunks of `chunk_size` bytes
+(default 64 KiB). Calling it without `output_file` returns the streaming
+`requests.Response` instead; this is deprecated, emits a `DeprecationWarning`,
+and `output_file` will be required in the next major version.
+
 #### Deleting a translation memory
 
 Use `delete_translation_memory()` to delete a translation memory by ID.

deepl/deepl_client.py

@@ -26,7 +26,12 @@
     TranslationMemorySegments,
 )
 from deepl.exceptions import DeepLException
-from deepl.translator import Translator, _warn_skip_language_check
+from deepl.translator import (
+    Translator,
+    _DOWNLOAD_CHUNK_SIZE,
+    _warn_download_without_output_file,
+    _warn_skip_language_check,
+)
 from deepl import util
 import os
 import pathlib
@@ -1712,17 +1717,18 @@ def download_translation_memory_export(
         self,
         job: TranslationMemoryJob,
         output_file: Union[BinaryIO, Any, None] = None,
-        chunk_size: int = 1,
+        chunk_size: int = _DOWNLOAD_CHUNK_SIZE,
     ) -> Optional[requests.Response]:
         """Downloads the TMX file of a completed export job.
 
         :param job: Completed export TranslationMemoryJob carrying the
             download URL.
-        :param output_file: (Optional) File-like object to store the
-            downloaded TMX file. If not provided, use iter_content() on the
-            returned response object to read streamed file data.
-        :param chunk_size: (Optional) Size of chunk in bytes for streaming.
-            Only used if output_file is specified.
+        :param output_file: File-like object to store the downloaded TMX
+            file. Omitting it is deprecated: the requests.Response is then
+            returned instead, and iter_content() reads the streamed file data.
+            In the next major version output_file will be required.
+        :param chunk_size: (Optional) Size of chunk in bytes for streaming,
+            default 64 KiB. Only used if output_file is specified.
         :return: None if output_file is specified, otherwise the
             requests.Response.
         """
@@ -1745,6 +1751,7 @@ def download_translation_memory_export(
             for chunk in content.iter_content(chunk_size=chunk_size):
                 output_file.write(chunk)
             return None
+        _warn_download_without_output_file()
         return content
 
     def import_translation_memory_from_filepath(

deepl/translator.py

@@ -50,6 +50,18 @@ def _warn_skip_language_check() -> None:
     )
 
 
+# Default chunk size for writing downloads into output_file.
+_DOWNLOAD_CHUNK_SIZE = 64 * 1024
+
+
+def _warn_download_without_output_file() -> None:
+    warnings.warn(
+        "returning the response is deprecated; pass output_file",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
 def _warn_skip_cache() -> None:
     warnings.warn(
         "skip_cache is deprecated and has no effect",
@@ -932,20 +944,18 @@ def translate_document_download(
         self,
         handle: DocumentHandle,
         output_file: Union[TextIO, BinaryIO, Any, None] = None,
-        chunk_size: int = 1,
+        chunk_size: int = _DOWNLOAD_CHUNK_SIZE,
     ) -> Optional[requests.Response]:
         """Downloads the translated document for the request associated with
-        given handle and returns a response object for streaming the data. Call
-        iter_content() on the response object to read streamed file data.
-        Alternatively, a file-like object may be given as output_file where the
-        complete file will be downloaded and written to.
+        given handle and writes it to the file-like object output_file.
 
         :param handle: DocumentHandle associated with request.
-        :param output_file: (Optional) File-like object to store downloaded
-            document. If not provided, use iter_content() on the returned
-            response object to read streamed file data.
-        :param chunk_size: (Optional) Size of chunk in bytes for streaming.
-            Only used if output_file is specified.
+        :param output_file: File-like object to store downloaded document.
+            Omitting it is deprecated: the requests.Response is then returned
+            instead, and iter_content() reads the streamed file data. In the
+            next major version output_file will be required.
+        :param chunk_size: (Optional) Size of chunk in bytes for streaming,
+            default 64 KiB. Only used if output_file is specified.
         :return: None if output_file is specified, otherwise the
             requests.Response will be returned.
         """
@@ -973,6 +983,7 @@ def translate_document_download(
                 output_file.write(chunk)
             return None
         else:
+            _warn_download_without_output_file()
             return response
 
     def get_source_languages(

tests/offline/test_translate_document.py

@@ -359,10 +359,13 @@ def test_raises_when_downloading_document_that_is_not_ready(
     assert exc_info.value.http_status_code == 503
 
 
-def test_returns_streaming_response_when_downloading_without_file(mocked):
+def test_warns_and_returns_streaming_response_when_downloading_without_file(
+    mocked,
+):
     reply_with_result(mocked, b"translated")
 
-    response = make_translator().translate_document_download(HANDLE)
+    with pytest.warns(DeprecationWarning, match="pass output_file"):
+        response = make_translator().translate_document_download(HANDLE)
 
     assert b"".join(response.iter_content(chunk_size=4)) == b"translated"
 

tests/offline/test_translation_memories.py

@@ -540,15 +540,16 @@ def test_downloads_export_without_authorization_into_file_object(mocked):
     assert output.getvalue() == b"<tmx/>"
 
 
-def test_returns_streaming_response_when_downloading_export_without_file(
+def test_warns_and_returns_response_when_downloading_export_without_file(
     mocked,
 ):
     mocked.get(DOWNLOAD_URL, body=b"<tmx/>", match=storage_request())
     job = TranslationMemoryJob.from_json(
         job_json("completed", "export", download_url=DOWNLOAD_URL)
     )
 
-    response = make_deepl_client().download_translation_memory_export(job)
+    with pytest.warns(DeprecationWarning, match="pass output_file"):
+        response = make_deepl_client().download_translation_memory_export(job)
 
     assert b"".join(response.iter_content(chunk_size=3)) == b"<tmx/>"