fix: Unify retry policy and keep custom HTTP clients backward compatible

Author: vdusek

docs/02_concepts/10_custom_http_clients.mdx

@@ -111,8 +111,8 @@ Responses use one separate abstraction:
 To plug in your custom implementation, use the <ApiLink to="class/ApifyClient#with_custom_http_client">`ApifyClient.with_custom_http_client`</ApiLink> class method.
 
 The built-in Impit and HTTPX classes are thin transport adapters over the request implementation in `HttpClient` and
-`HttpClientAsync`. Custom transport adapters implement the abstract request, error-classification, and lifecycle hooks;
-they inherit request construction, retries, timeout growth, API error conversion, logging, and statistics from the base.
+`HttpClientAsync`. Custom transport adapters implement the request, error-classification, and lifecycle hooks. They
+inherit request construction, retries, timeout growth, API error conversion, logging, and statistics from the base.
 
 All of these are available from the `apify_client.http_clients` module:
 
@@ -122,12 +122,16 @@ All of these are available from the `apify_client.http_clients` module:
 
 ### The transport contract
 
-The public `call` method provides the shared request pipeline. A concrete transport implements these abstract methods:
+The public `call` method provides the shared request pipeline. A concrete transport implements these hooks:
 
-- `_send_request(...)` sends one prepared request and returns an `HttpResponse`.
-- `_is_retryable_transport_error(exc)` classifies transport failures for the shared retry loop.
-- `is_timeout_error(exc)` identifies transport-specific timeout exceptions for higher-level client features.
-- `close()` or `aclose()` closes resources owned by the transport.
+- `_send_request(...)` sends one prepared request and returns an `HttpResponse`. The inherited `call` needs it, so
+  every transport adapter has to implement it.
+- `_is_retryable_transport_error(exc)` classifies transport failures for the shared retry loop. The default classifies
+  nothing as retryable, so a transport that skips it gives up on the first connection failure.
+- `is_timeout_error(exc)` identifies transport-specific timeout exceptions for higher-level client features. The
+  default recognizes Python's `TimeoutError`.
+- `close()` or `aclose()` closes resources owned by the transport. The default does nothing, which is correct for a
+  transport that owns no pool or session.
 
 The `@override` decorators in the built-in Impit and HTTPX adapters make these implementations explicit and allow type
 checkers to catch misspelled or incompatible overrides.
@@ -195,6 +199,6 @@ example when you need to:
 - **Modify requests** - Add custom fields, modify the body, or change headers.
 - **Collect custom metrics** - Measure request latency, track error rates, or count API calls.
 
-For a complete implementation using a transport with a different response API, see
-[Build a custom HTTP client with AIOHTTP](/api/client/python/docs/guides/custom-http-client-httpx). You can also refer
-to the <ApiLink to="class/HttpClient">`HttpClient` API reference</ApiLink> for the synchronous contract.
+For complete synchronous and asynchronous implementations over a transport with a different response API, see
+[Build a custom HTTP client](../03_guides/05_custom_http_client.mdx). You can also refer to the
+<ApiLink to="class/HttpClient">`HttpClient` API reference</ApiLink> for the synchronous contract.

docs/02_concepts/code/10_plugging_in_async.py

@@ -33,7 +33,10 @@ async def _send_request(
 
     @override
     def _is_retryable_transport_error(self, exc: Exception) -> bool:
-        return False
+        # List the transport's transient failures here, e.g. its timeout
+        # and connection errors. Returning False for everything opts out
+        # of transport retries entirely.
+        return isinstance(exc, TimeoutError)
 
 
 async def main() -> None:

docs/02_concepts/code/10_plugging_in_sync.py

@@ -33,7 +33,10 @@ def _send_request(
 
     @override
     def _is_retryable_transport_error(self, exc: Exception) -> bool:
-        return False
+        # List the transport's transient failures here, e.g. its timeout
+        # and connection errors. Returning False for everything opts out
+        # of transport retries entirely.
+        return isinstance(exc, TimeoutError)
 
 
 def main() -> None:

docs/03_guides/05_custom_http_client.mdx

@@ -1,53 +1,63 @@
 ---
-id: custom-http-client-httpx
-title: Build a custom HTTP client with AIOHTTP
-description: Implement the asynchronous HTTP client contract with AIOHTTP.
+id: custom-http-client
+title: Build a custom HTTP client
+description: Implement the HTTP client contract with AIOHTTP and requests.
 ---
 
 import ApiLink from '@theme/ApiLink';
 import CodeBlock from '@theme/CodeBlock';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-import CustomHttpClientExample from '!!raw-loader!./code/05_custom_http_client_async.py';
+import CustomHttpClientAsyncExample from '!!raw-loader!./code/05_custom_http_client_async.py';
+import CustomHttpClientSyncExample from '!!raw-loader!./code/05_custom_http_client_sync.py';
 
-This guide implements a custom <ApiLink to="class/HttpClientAsync">`HttpClientAsync`</ApiLink> using
-[AIOHTTP](https://docs.aiohttp.org/). It demonstrates how to integrate a transport that does not already implement the
-<ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink> protocol. Because AIOHTTP is asynchronous, this guide focuses
-on the async client contract; a synchronous custom transport would implement <ApiLink to="class/HttpClient">`HttpClient`</ApiLink>
-in the same role.
+This guide implements a custom <ApiLink to="class/HttpClientAsync">`HttpClientAsync`</ApiLink> with
+[AIOHTTP](https://docs.aiohttp.org/) and a custom <ApiLink to="class/HttpClient">`HttpClient`</ApiLink> with
+[requests](https://requests.readthedocs.io/). Neither library satisfies the
+<ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink> protocol, so both examples also show how to adapt a
+foreign response API.
 
 For an overview of the architecture and the built-in Impit and HTTPX implementations, see
-[HTTP clients](/api/client/python/docs/concepts/custom-http-clients).
+[HTTP clients](../02_concepts/10_custom_http_clients.mdx).
 
 ## Installation
 
-Install AIOHTTP alongside the Apify client. AIOHTTP is only used by this custom implementation and is not an
-`apify-client` extra:
+Install the transport alongside the Apify client. Neither AIOHTTP nor requests is an `apify-client` extra:
 
 ```bash
-pip install apify-client aiohttp
-# or
-uv add apify-client aiohttp
+pip install apify-client aiohttp   # for the asynchronous client
+pip install apify-client requests  # for the synchronous client
 ```
 
 ## Implementation
 
-The example has three parts:
-
-1. `AiohttpResponse` adapts AIOHTTP's response API to the <ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink>
-   protocol expected by resource clients.
-2. `AiohttpHttpClient` implements the abstract transport, error-classification, timeout-classification, and lifecycle
-   hooks. It inherits request preparation, retry handling, timeout growth, and API error conversion from
-   <ApiLink to="class/HttpClientAsync">`HttpClientAsync`</ApiLink>.
-3. <ApiLink to="class/ApifyClientAsync#with_custom_http_client">`ApifyClientAsync.with_custom_http_client()`</ApiLink>
-   connects the implementation to the resource clients and applies the API token. The async context manager closes
-   the AIOHTTP session at shutdown.
-
-<CodeBlock className="language-python">
-    {CustomHttpClientExample}
-</CodeBlock>
+Each example has three parts:
+
+1. The response adapter, `AiohttpResponse` or `RequestsResponse`, maps the library's own response onto the
+   <ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink> protocol that resource clients expect.
+2. The client, `AiohttpHttpClient` or `RequestsHttpClient`, implements the transport, error-classification,
+   timeout-classification, and lifecycle hooks. It inherits request preparation, retry handling, timeout growth,
+   and API error conversion from its base class.
+3. `with_custom_http_client()` connects the implementation to the resource clients and applies the API token. The
+   context manager closes the session at shutdown.
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {CustomHttpClientAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {CustomHttpClientSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
 
 :::warning
-This is a compact integration example, not a replacement for all built-in client behavior. A production custom client
-should account for transport-specific details such as proxy configuration, TLS settings, redirects, and response
-resource cleanup. The shared base provides retries, logging, statistics, timeout growth, and API error conversion.
+These are compact integration examples, not a replacement for all built-in client behavior. A production custom
+client should account for transport-specific details such as proxy configuration, TLS settings, redirects, and
+response resource cleanup. The shared base provides retries, logging, statistics, timeout growth, and API error
+conversion.
 :::

docs/03_guides/code/05_custom_http_client_sync.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import json as jsonlib
+from typing import TYPE_CHECKING, Any
+
+import requests
+from typing_extensions import override
+
+from apify_client import ApifyClient
+from apify_client.http_clients import HttpClient, HttpResponse
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator, Mapping
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+class RequestsResponse:
+    """Adapt a requests response to the Apify client's HttpResponse protocol."""
+
+    def __init__(self, response: requests.Response) -> None:
+        self._response = response
+        self._body: bytes | None = None
+
+    @property
+    def status_code(self) -> int:
+        return self._response.status_code
+
+    @property
+    def headers(self) -> Mapping[str, str]:
+        return self._response.headers
+
+    @property
+    def content(self) -> bytes:
+        if self._body is None:
+            raise RuntimeError(
+                'The streamed response has not been read yet; use read() or iter_bytes()'
+            )
+        return self._body
+
+    @property
+    def text(self) -> str:
+        encoding = self._response.encoding or 'utf-8'
+        return self.content.decode(encoding, errors='replace')
+
+    def json(self) -> Any:
+        return jsonlib.loads(self.text)
+
+    def read(self) -> bytes:
+        if self._body is None:
+            self._body = self._response.content
+        return self._body
+
+    async def aread(self) -> bytes:
+        return self.read()
+
+    def close(self) -> None:
+        self._response.close()
+
+    async def aclose(self) -> None:
+        self.close()
+
+    def iter_bytes(self) -> Iterator[bytes]:
+        if self._body is not None:
+            if self._body:
+                yield self._body
+            return
+        yield from self._response.iter_content(64 * 1024)
+
+    async def aiter_bytes(self) -> AsyncIterator[bytes]:
+        for chunk in self.iter_bytes():
+            yield chunk
+
+
+class RequestsHttpClient(HttpClient):
+    """Minimal custom synchronous HTTP client backed by requests."""
+
+    @override
+    def __init__(self) -> None:
+        super().__init__()
+        self._session = requests.Session()
+
+    @override
+    def is_timeout_error(self, exc: Exception) -> bool:
+        return super().is_timeout_error(exc) or isinstance(exc, requests.Timeout)
+
+    @override
+    def close(self) -> None:
+        self._session.close()
+
+    @override
+    def _send_request(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: dict[str, str],
+        content: bytes | None,
+        timeout: float | None,
+        stream: bool,
+    ) -> HttpResponse:
+        response = self._session.request(
+            method=method,
+            url=url,
+            headers=headers,
+            data=content,
+            timeout=timeout,
+            stream=stream,
+        )
+        adapted_response = RequestsResponse(response)
+
+        if not stream:
+            adapted_response.read()
+
+        return adapted_response
+
+    @override
+    def _is_retryable_transport_error(self, exc: Exception) -> bool:
+        return isinstance(
+            exc,
+            (
+                requests.ConnectionError,
+                requests.Timeout,
+                requests.exceptions.ChunkedEncodingError,
+            ),
+        )
+
+
+def main() -> None:
+    with RequestsHttpClient() as http_client:
+        client = ApifyClient.with_custom_http_client(
+            token=TOKEN,
+            http_client=http_client,
+        )
+        actor = client.actor('apify/hello-world').get()
+        print(actor)
+
+
+if __name__ == '__main__':
+    main()

src/apify_client/_resource_clients/log.py

@@ -34,7 +34,7 @@ def __init__(
             **kwargs,
         )
 
-    def is_timeout_error(self, exc: Exception) -> bool:
+    def _is_timeout_error(self, exc: Exception) -> bool:
         """Return whether an exception came from the configured HTTP client's timeout handling."""
         return self._http_client.is_timeout_error(exc)
 
@@ -146,7 +146,7 @@ def __init__(
             **kwargs,
         )
 
-    def is_timeout_error(self, exc: Exception) -> bool:
+    def _is_timeout_error(self, exc: Exception) -> bool:
         """Return whether an exception came from the configured HTTP client's timeout handling."""
         return self._http_client.is_timeout_error(exc)
 

src/apify_client/_streamed_log.py

@@ -160,7 +160,7 @@ def _stream_log(self) -> None:
                     # Flush the last buffered part even if the read timed out or was stopped.
                     self._log_buffer_content(include_last_part=True)
         except Exception as exc:
-            if self._log_client.is_timeout_error(exc):
+            if self._log_client._is_timeout_error(exc):  # noqa: SLF001
                 # The stream cannot continue, so warn and let the thread end instead of leaking a traceback (#1040).
                 self._to_logger.warning('Log streaming stopped: the log stream request timed out.')
             else:
@@ -239,7 +239,7 @@ async def _stream_log(self) -> None:
                     # Flush the last buffered part even if the task is cancelled by `stop()`.
                     self._log_buffer_content(include_last_part=True)
         except Exception as exc:
-            if self._log_client.is_timeout_error(exc):
+            if self._log_client._is_timeout_error(exc):  # noqa: SLF001
                 # A timeout on the long-lived stream is an expected terminal condition, not an error.
                 self._to_logger.warning('Log streaming stopped: the log stream request timed out.')
             else:

src/apify_client/_utils/errors.py

@@ -2,9 +2,7 @@
 
 from typing import TYPE_CHECKING
 
-import impit
-
-from apify_client.errors import InvalidResponseBodyError, NotFoundError
+from apify_client.errors import NotFoundError
 
 if TYPE_CHECKING:
     from apify_client.errors import ApifyApiError
@@ -33,19 +31,3 @@ def catch_not_found_for_resource_or_throw(exc: ApifyApiError, resource_id: str |
     if resource_id is None:
         raise exc
     catch_not_found_or_throw(exc)
-
-
-def is_retryable_error(exc: Exception) -> bool:
-    """Check if the given error is retryable.
-
-    All `impit.HTTPError` subclasses are considered retryable because they represent transport-level failures
-    (network issues, timeouts, protocol errors, body decoding errors) that are typically transient. HTTP status
-    code errors are handled separately in `_make_request` based on the response status code, not here.
-    """
-    return isinstance(
-        exc,
-        (
-            InvalidResponseBodyError,
-            impit.HTTPError,
-        ),
-    )