fix!: Raise ValueError when http_client conflicts with config params

Instead of silently ignoring max_retries, min_delay_between_retries,
timeout, and headers when a custom http_client is provided, raise a
ValueError to make the conflict explicit. Uses @overload to express the
two mutually exclusive signatures for static type checkers.

Also fix docstring check/fix scripts to handle @overload stubs.

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

Author: vdusek

scripts/check_async_docstrings.py

@@ -33,10 +33,19 @@
             # Find corresponding sync method in the sync class
             sync_method = sync_class.find('DefNode', name=async_method.name)
 
-            # Skip methods with @ignore_docs decorator
-            if len(async_method.decorators) and str(async_method.decorators[0].value) == 'ignore_docs':
+            # Skip methods with @ignore_docs or @overload decorator
+            if len(async_method.decorators) and str(async_method.decorators[0].value) in ('ignore_docs', 'overload'):
                 continue
 
+            # When there are overloads, find() may return a stub instead of the implementation.
+            # Find the actual implementation by skipping overload-decorated methods.
+            if sync_method and any(str(d.value) == 'overload' for d in sync_method.decorators):
+                candidates = sync_class.find_all('DefNode', name=async_method.name)
+                sync_method = next(
+                    (m for m in candidates if not any(str(d.value) == 'overload' for d in m.decorators)),
+                    None,
+                )
+
             # If the sync method has a docstring, check if it matches the async dostring
             if sync_method and isinstance(sync_method.value[0].value, str):
                 sync_docstring = sync_method.value[0].value

scripts/fix_async_docstrings.py

@@ -30,14 +30,25 @@
             # Find corresponding sync method in the sync class
             sync_method = sync_class.find('DefNode', name=async_method.name)
 
-            # Skip methods with @ignore_docs decorator
-            if len(async_method.decorators) and str(async_method.decorators[0].value) == 'ignore_docs':
+            # Skip methods with @ignore_docs or @overload decorator
+            if len(async_method.decorators) and str(async_method.decorators[0].value) in ('ignore_docs', 'overload'):
                 continue
 
             # Skip methods that don't exist in the sync class
             if sync_method is None:
                 continue
 
+            # When there are overloads, find() may return a stub instead of the implementation.
+            # Find the actual implementation by skipping overload-decorated methods.
+            if any(str(d.value) == 'overload' for d in sync_method.decorators):
+                candidates = sync_class.find_all('DefNode', name=async_method.name)
+                sync_method = next(
+                    (m for m in candidates if not any(str(d.value) == 'overload' for d in m.decorators)),
+                    None,
+                )
+                if sync_method is None:
+                    continue
+
             # If the sync method has a docstring, copy it to the async method (with adjustments)
             if isinstance(sync_method.value[0].value, str):
                 sync_docstring = sync_method.value[0].value

src/apify_client/_apify_client.py

@@ -2,7 +2,7 @@
 
 import warnings
 from functools import cached_property
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, ClassVar, overload
 
 from apify_client._client_registry import ClientRegistry, ClientRegistryAsync
 from apify_client._consts import (
@@ -113,6 +113,29 @@ class ApifyClient:
 
     _OVERRIDABLE_DEFAULT_HEADERS: ClassVar[set[str]] = {'Accept', 'Authorization', 'Accept-Encoding', 'User-Agent'}
 
+    @overload
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        api_url: str = DEFAULT_API_URL,
+        api_public_url: str | None = DEFAULT_API_URL,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
+        timeout: timedelta = DEFAULT_TIMEOUT,
+        headers: dict[str, str] | None = None,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        api_url: str = DEFAULT_API_URL,
+        api_public_url: str | None = DEFAULT_API_URL,
+        http_client: HttpClient,
+    ) -> None: ...
+
     def __init__(
         self,
         token: str | None = None,
@@ -144,13 +167,33 @@ def __init__(
             headers: Additional HTTP headers to include in all API requests. Only used when `http_client` is not
                 provided.
             http_client: A custom HTTP client instance extending `HttpClient`. When provided, the `max_retries`,
-                `min_delay_between_retries`, `timeout`, and `headers` parameters are ignored, as the custom
+                `min_delay_between_retries`, `timeout`, and `headers` parameters must not be set, as the custom
                 client is responsible for its own configuration.
+
+        Raises:
+            ValueError: If `http_client` is provided together with `max_retries`, `min_delay_between_retries`,
+                `timeout`, or `headers`.
         """
         # We need to do this because of mocking in tests and default mutable arguments.
         api_url = DEFAULT_API_URL if api_url is None else api_url
         api_public_url = DEFAULT_API_URL if api_public_url is None else api_public_url
 
+        if http_client is not None:
+            conflicting = []
+            if max_retries != DEFAULT_MAX_RETRIES:
+                conflicting.append('max_retries')
+            if min_delay_between_retries != DEFAULT_MIN_DELAY_BETWEEN_RETRIES:
+                conflicting.append('min_delay_between_retries')
+            if timeout != DEFAULT_TIMEOUT:
+                conflicting.append('timeout')
+            if headers is not None:
+                conflicting.append('headers')
+            if conflicting:
+                raise ValueError(
+                    f'Cannot pass {", ".join(conflicting)} together with http_client. When using a custom '
+                    'HTTP client, configure these options directly on the client instance.'
+                )
+
         if headers and not http_client:
             self._check_custom_headers(headers)
 
@@ -427,6 +470,29 @@ async def main() -> None:
 
     _OVERRIDABLE_DEFAULT_HEADERS: ClassVar[set[str]] = {'Accept', 'Authorization', 'Accept-Encoding', 'User-Agent'}
 
+    @overload
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        api_url: str = DEFAULT_API_URL,
+        api_public_url: str | None = DEFAULT_API_URL,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
+        timeout: timedelta = DEFAULT_TIMEOUT,
+        headers: dict[str, str] | None = None,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        api_url: str = DEFAULT_API_URL,
+        api_public_url: str | None = DEFAULT_API_URL,
+        http_client: HttpClientAsync,
+    ) -> None: ...
+
     def __init__(
         self,
         token: str | None = None,
@@ -458,13 +524,33 @@ def __init__(
             headers: Additional HTTP headers to include in all API requests. Only used when `http_client` is not
                 provided.
             http_client: A custom HTTP client instance extending `HttpClientAsync`. When provided, the `max_retries`,
-                `min_delay_between_retries`, `timeout`, and `headers` parameters are ignored, as the custom
+                `min_delay_between_retries`, `timeout`, and `headers` parameters must not be set, as the custom
                 client is responsible for its own configuration.
+
+        Raises:
+            ValueError: If `http_client` is provided together with `max_retries`, `min_delay_between_retries`,
+                `timeout`, or `headers`.
         """
         # We need to do this because of mocking in tests and default mutable arguments.
         api_url = DEFAULT_API_URL if api_url is None else api_url
         api_public_url = DEFAULT_API_URL if api_public_url is None else api_public_url
 
+        if http_client is not None:
+            conflicting = []
+            if max_retries != DEFAULT_MAX_RETRIES:
+                conflicting.append('max_retries')
+            if min_delay_between_retries != DEFAULT_MIN_DELAY_BETWEEN_RETRIES:
+                conflicting.append('min_delay_between_retries')
+            if timeout != DEFAULT_TIMEOUT:
+                conflicting.append('timeout')
+            if headers is not None:
+                conflicting.append('headers')
+            if conflicting:
+                raise ValueError(
+                    f'Cannot pass {", ".join(conflicting)} together with http_client. When using a custom '
+                    'HTTP client, configure these options directly on the client instance.'
+                )
+
         if headers and not http_client:
             self._check_custom_headers(headers)
 

tests/unit/test_pluggable_http_client.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import warnings
 from dataclasses import dataclass, field
 from datetime import timedelta
 from typing import TYPE_CHECKING, Any
@@ -15,7 +14,6 @@
     HttpClientAsync,
     HttpResponse,
 )
-from apify_client._consts import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT
 from apify_client._http_clients import ImpitHttpClient, ImpitHttpClientAsync
 from apify_client.errors import ApifyApiError
 
@@ -227,40 +225,44 @@ def test_apify_client_custom_http_client_receives_requests() -> None:
     assert result == {'data': {'id': 'test123'}}
 
 
-def test_apify_client_custom_http_client_ignores_other_params() -> None:
-    """Test that timeout/retries/headers params don't affect custom http_client."""
+def test_apify_client_custom_http_client_rejects_conflicting_params() -> None:
+    """Test that passing config params together with http_client raises ValueError."""
     fake_client = FakeHttpClient()
-    client = ApifyClient(
-        token='test_token',
-        http_client=fake_client,
-        timeout=timedelta(seconds=999),
-        max_retries=99,
-        headers={'X-Custom': 'should-be-ignored'},
-    )
-
-    # The custom client should be used as-is
-    assert client.http_client is fake_client
 
-    # Verify the custom client retained its own defaults (params were not forwarded)
-    assert fake_client._timeout == DEFAULT_TIMEOUT
-    assert fake_client._max_retries == DEFAULT_MAX_RETRIES
+    with pytest.raises(ValueError, match=r'Cannot pass .* together with http_client'):
+        ApifyClient(  # ty: ignore[no-matching-overload]
+            token='test_token',
+            http_client=fake_client,
+            timeout=timedelta(seconds=999),
+            max_retries=99,
+            headers={'X-Custom': 'should-not-be-allowed'},
+        )
 
 
-def test_apify_client_custom_http_client_no_header_warning() -> None:
-    """Test that no header warning is raised when custom http_client is provided."""
+def test_apify_client_custom_http_client_rejects_headers() -> None:
+    """Test that passing headers together with http_client raises ValueError."""
     fake_client = FakeHttpClient()
 
-    # This should NOT raise a UserWarning even though we pass overriding headers,
-    # because headers are ignored when http_client is provided.
-    with warnings.catch_warnings():
-        warnings.simplefilter('error')
-        ApifyClient(
+    with pytest.raises(ValueError, match=r'headers.*http_client'):
+        ApifyClient(  # ty: ignore[no-matching-overload]
             token='test_token',
             http_client=fake_client,
             headers={'User-Agent': 'Custom/1.0', 'Authorization': 'Bearer custom'},
         )
 
 
+def test_apify_client_custom_http_client_accepts_only_url_params() -> None:
+    """Test that http_client can be combined with token, api_url, and api_public_url."""
+    fake_client = FakeHttpClient()
+    client = ApifyClient(
+        token='test_token',
+        api_url='https://custom.api.example.com',
+        api_public_url='https://public.api.example.com',
+        http_client=fake_client,
+    )
+    assert client.http_client is fake_client
+
+
 # -- ApifyClientAsync with custom http_client --
 
 
@@ -294,6 +296,44 @@ async def test_apify_client_async_custom_http_client_receives_requests() -> None
     assert result == {'data': {'id': 'test123'}}
 
 
+async def test_apify_client_async_custom_http_client_rejects_conflicting_params() -> None:
+    """Test that passing config params together with http_client raises ValueError for async client."""
+    fake_client = FakeHttpClientAsync()
+
+    with pytest.raises(ValueError, match=r'Cannot pass .* together with http_client'):
+        ApifyClientAsync(  # ty: ignore[no-matching-overload]
+            token='test_token',
+            http_client=fake_client,
+            timeout=timedelta(seconds=999),
+            max_retries=99,
+            headers={'X-Custom': 'should-not-be-allowed'},
+        )
+
+
+async def test_apify_client_async_custom_http_client_rejects_headers() -> None:
+    """Test that passing headers together with http_client raises ValueError for async client."""
+    fake_client = FakeHttpClientAsync()
+
+    with pytest.raises(ValueError, match=r'headers.*http_client'):
+        ApifyClientAsync(  # ty: ignore[no-matching-overload]
+            token='test_token',
+            http_client=fake_client,
+            headers={'User-Agent': 'Custom/1.0'},
+        )
+
+
+async def test_apify_client_async_custom_http_client_accepts_only_url_params() -> None:
+    """Test that async http_client can be combined with token, api_url, and api_public_url."""
+    fake_client = FakeHttpClientAsync()
+    client = ApifyClientAsync(
+        token='test_token',
+        api_url='https://custom.api.example.com',
+        api_public_url='https://public.api.example.com',
+        http_client=fake_client,
+    )
+    assert client.http_client is fake_client
+
+
 # -- Public exports --