fix: warn when the deprecated retry and timeout globals are set

Assigning deepl.http_client.max_network_retries or min_connection_timeout
now emits a DeprecationWarning naming the replacement client option.
The module class is swapped for a ModuleType subclass whose __setattr__
warns; the assignment still takes effect, and reads do not warn.

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

Author: hive-bot

CHANGELOG.md

@@ -73,7 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `deepl.http_client.min_connection_timeout` are deprecated in favour of the
   `max_retries` and `timeout_s` client options, and will be removed in the
   next major version. They still apply to clients created without these
-  options. No warning is emitted.
+  options. Assigning either setting emits a `DeprecationWarning`.
 
 ### Fixed
 - Fixed the `DeprecationWarning` messages of `Usage.Detail.limit_exceeded` and

README.md

@@ -1386,7 +1386,8 @@ failure could create a second key.
 
 The module-level settings `deepl.http_client.max_network_retries` and
 `deepl.http_client.min_connection_timeout` are deprecated and will be removed
-in a future major version. They still apply to clients created without the
+in a future major version. Assigning either setting emits a
+`DeprecationWarning`. They still apply to clients created without the
 corresponding option, and affect every client in the process:
 
 ```python

deepl/admin_client.py

@@ -51,10 +51,11 @@ class DeepLAdminClient(BaseClient):
         the requests verify documentation for more information.
     :param max_retries: (Optional) Maximum number of times a failed request
         is retried, for failures that may be transient (e.g. HTTP 429). If
-        None, deepl.http_client.max_network_retries is used (default 5).
+        None, the deprecated deepl.http_client.max_network_retries is used
+        (default 5).
     :param timeout_s: (Optional) Minimum timeout in seconds for each attempt
-        of a request. If None, deepl.http_client.min_connection_timeout is used
-        (default 10.0).
+        of a request. If None, the deprecated
+        deepl.http_client.min_connection_timeout is used (default 10.0).
 
     All functions may raise DeepLException or a subclass if a connection error
     occurs.

deepl/http_client.py

@@ -9,17 +9,42 @@
 import random
 import requests  # type: ignore
 import socket
+import sys
 import traceback
 import time
+import types
+import warnings
 from functools import lru_cache
 from typing import Dict, List, Optional, Tuple, Union
 from .util import log_info
 from deepl import util
 
 user_agent = None
+# Deprecated in favour of the max_retries and timeout_s client options; will be
+# removed in the next major version. Assigning either emits a warning.
 max_network_retries = 5
 min_connection_timeout = 10.0
 
+_DEPRECATED_GLOBALS = {
+    "max_network_retries": "max_retries",
+    "min_connection_timeout": "timeout_s",
+}
+
+
+class _HttpClientModule(types.ModuleType):
+    def __setattr__(self, name, value):
+        if name in _DEPRECATED_GLOBALS:
+            warnings.warn(
+                f"deepl.http_client.{name} is deprecated, use the "
+                f"{_DEPRECATED_GLOBALS[name]} client option",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        super().__setattr__(name, value)
+
+
+sys.modules[__name__].__class__ = _HttpClientModule
+
 
 class _BackoffTimer:
     """Implements exponential-backoff strategy.

deepl/translator.py

@@ -79,10 +79,11 @@ class Translator(BaseClient):
         the requests verify documentation for more information.
     :param max_retries: (Optional) Maximum number of times a failed request
         is retried, for failures that may be transient (e.g. HTTP 429). If
-        None, deepl.http_client.max_network_retries is used (default 5).
+        None, the deprecated deepl.http_client.max_network_retries is used
+        (default 5).
     :param timeout_s: (Optional) Minimum timeout in seconds for each attempt
-        of a request. If None, deepl.http_client.min_connection_timeout is used
-        (default 10.0).
+        of a request. If None, the deprecated
+        deepl.http_client.min_connection_timeout is used (default 10.0).
     :param skip_language_check: Deprecated, and now has no effect as the
         corresponding internal functionality has been removed. This parameter
         will be removed in a future version.

tests/offline/conftest.py

@@ -20,4 +20,5 @@ def mocked():
 def no_retries(monkeypatch):
     """Makes the SDK fail on the first 429, 5xx or connection error instead
     of retrying with backoff."""
-    monkeypatch.setattr(deepl.http_client, "max_network_retries", 0)
+    # Patch the module dict: assigning the deprecated global would warn.
+    monkeypatch.setitem(vars(deepl.http_client), "max_network_retries", 0)

tests/offline/test_http_client.py

@@ -43,7 +43,7 @@ def test_retries_request_after_timeout(mocked):
 
 
 def test_stops_retrying_after_max_network_retries(mocked, monkeypatch):
-    monkeypatch.setattr(deepl.http_client, "max_network_retries", 1)
+    monkeypatch.setitem(vars(deepl.http_client), "max_network_retries", 1)
     mocked.get(url("v2/usage"), status=500)
     mocked.get(url("v2/usage"), status=500)
 
@@ -65,7 +65,7 @@ def test_max_retries_option_overrides_global(mocked, no_retries, make_client):
 
 
 def test_max_retries_option_stops_retrying(mocked, monkeypatch):
-    monkeypatch.setattr(deepl.http_client, "max_network_retries", 5)
+    monkeypatch.setitem(vars(deepl.http_client), "max_network_retries", 5)
     mocked.get(url("v2/usage"), status=500)
 
     with pytest.raises(deepl.DeepLException, match="Unexpected status code"):
@@ -83,6 +83,33 @@ def test_passes_timeout_option_to_requests(mocked, make_client):
     assert mocked.calls[0].request.req_kwargs["timeout"] == 42.0
 
 
+@pytest.mark.parametrize(
+    "name, value",
+    [("max_network_retries", 0), ("min_connection_timeout", 42.0)],
+)
+def test_assigning_deprecated_global_warns_and_takes_effect(
+    mocked, monkeypatch, name, value
+):
+    # Registers the restore of the original value at teardown.
+    module_dict = vars(deepl.http_client)
+    monkeypatch.setitem(module_dict, name, module_dict[name])
+    mocked.get(url("v2/usage"), status=503)
+
+    with pytest.warns(DeprecationWarning, match=f"http_client.{name}") as rec:
+        setattr(deepl.http_client, name, value)
+
+    assert rec[0].filename == __file__
+    assert module_dict[name] == value
+    with pytest.raises(deepl.DeepLException, match="Service unavailable"):
+        make_translator(
+            **({} if name == "max_network_retries" else {"max_retries": 0})
+        ).get_usage()
+    # max_network_retries=0: no retry; min_connection_timeout: sent timeout
+    assert len(mocked.calls) == 1
+    if name == "min_connection_timeout":
+        assert mocked.calls[0].request.req_kwargs["timeout"] == 42.0
+
+
 def test_raises_connection_exception_for_timeout_without_retries(
     mocked, no_retries
 ):

tests/real_api/test_proxy.py

@@ -12,7 +12,7 @@
 
 
 def test_sends_requests_through_proxy(monkeypatch, tmp_path):
-    monkeypatch.setattr(deepl.http_client, "max_network_retries", 0)
+    monkeypatch.setitem(vars(deepl.http_client), "max_network_retries", 0)
 
     # proxy.py writes below the home directory unless told otherwise, which CI
     # runners do not have.