feat!: Make HTTP client pluggable with abstract base classes

- Introduce `HttpClient` and `HttpClientAsync` ABCs that users can extend to provide custom HTTP client implementations via `ApifyClient(http_client=...)` and `ApifyClientAsync(http_client=...)`
- Factor impit-specific logic into `ImpitHttpClient`/`ImpitHttpClientAsync`, keeping `_base.py` free of any `impit` dependency
- Add `HttpResponse` protocol with full streaming support (`iter_bytes`, `aiter_bytes`, `read`, `aread`, `close`, `aclose`)
- Export all public types (`HttpClient`, `HttpClientAsync`, `HttpResponse`, `ImpitHttpClient`, `ImpitHttpClientAsync`) from `apify_client`

Author: vdusek

src/apify_client/__init__.py

@@ -1,7 +1,23 @@
 from importlib import metadata
 
 from ._apify_client import ApifyClient, ApifyClientAsync
+from ._http_clients import (
+    HttpClient,
+    HttpClientAsync,
+    HttpResponse,
+    ImpitHttpClient,
+    ImpitHttpClientAsync,
+)
 
 __version__ = metadata.version('apify-client')
 
-__all__ = ['ApifyClient', 'ApifyClientAsync', '__version__']
+__all__ = [
+    'ApifyClient',
+    'ApifyClientAsync',
+    'HttpClient',
+    'HttpClientAsync',
+    'HttpResponse',
+    'ImpitHttpClient',
+    'ImpitHttpClientAsync',
+    '__version__',
+]

src/apify_client/_apify_client.py

@@ -12,7 +12,12 @@
     DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
     DEFAULT_TIMEOUT,
 )
-from apify_client._http_clients import HttpClient, HttpClientAsync
+from apify_client._http_clients import (
+    HttpClient,
+    HttpClientAsync,
+    ImpitHttpClient,
+    ImpitHttpClientAsync,
+)
 from apify_client._resource_clients import (
     ActorClient,
     ActorClientAsync,
@@ -94,6 +99,7 @@ def __init__(
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
         timeout: timedelta = DEFAULT_TIMEOUT,
         headers: dict[str, str] | None = None,
+        http_client: HttpClient | None = None,
     ) -> None:
         """Initialize a new instance.
 
@@ -103,17 +109,23 @@ def __init__(
                 be an internal URL that is not globally accessible, in such case `api_public_url` should be set as well.
             api_public_url: The globally accessible URL of the Apify API server. It should be set only if the `api_url`
                 is an internal URL that is not globally accessible. Defaults to https://api.apify.com.
-            max_retries: How many times to retry a failed request at most.
+            max_retries: How many times to retry a failed request at most. Only used when `http_client` is not
+                provided.
             min_delay_between_retries: How long will the client wait between retrying requests
-                (increases exponentially from this value).
-            timeout: The socket timeout of the HTTP requests sent to the Apify API.
-            headers: Additional HTTP headers to include in all API requests.
+                (increases exponentially from this value). Only used when `http_client` is not provided.
+            timeout: The socket timeout of the HTTP requests sent to the Apify API. Only used when `http_client`
+                is not provided.
+            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
+                client is responsible for its own configuration.
         """
         # 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 headers:
+        if headers and not http_client:
             self._check_custom_headers(headers)
 
         self._token = token
@@ -128,14 +140,17 @@ def __init__(
         self._statistics = ClientStatistics()
         """Collector for client request statistics."""
 
-        self._http_client = HttpClient(
-            token=self._token,
-            timeout=timeout,
-            max_retries=max_retries,
-            min_delay_between_retries=min_delay_between_retries,
-            statistics=self._statistics,
-            headers=headers,
-        )
+        if http_client is not None:
+            self._http_client: HttpClient = http_client
+        else:
+            self._http_client = ImpitHttpClient(
+                token=self._token,
+                timeout=timeout,
+                max_retries=max_retries,
+                min_delay_between_retries=min_delay_between_retries,
+                statistics=self._statistics,
+                headers=headers,
+            )
         """HTTP client used to communicate with the Apify API."""
 
         self._client_registry = ClientRegistry(
@@ -198,6 +213,15 @@ def token(self) -> str | None:
         """The Apify API token used by the client."""
         return self._token
 
+    @property
+    def http_client(self) -> HttpClient:
+        """The HTTP client instance used for API communication.
+
+        Returns the custom HTTP client if one was provided during initialization,
+        or the default `ImpitHttpClient` otherwise.
+        """
+        return self._http_client
+
     def actor(self, actor_id: str) -> ActorClient:
         """Retrieve the sub-client for manipulating a single Actor.
 
@@ -355,6 +379,7 @@ def __init__(
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
         timeout: timedelta = DEFAULT_TIMEOUT,
         headers: dict[str, str] | None = None,
+        http_client: HttpClientAsync | None = None,
     ) -> None:
         """Initialize a new instance.
 
@@ -364,17 +389,23 @@ def __init__(
                 be an internal URL that is not globally accessible, in such case `api_public_url` should be set as well.
             api_public_url: The globally accessible URL of the Apify API server. It should be set only if the `api_url`
                 is an internal URL that is not globally accessible. Defaults to https://api.apify.com.
-            max_retries: How many times to retry a failed request at most.
+            max_retries: How many times to retry a failed request at most. Only used when `http_client` is not
+                provided.
             min_delay_between_retries: How long will the client wait between retrying requests
-                (increases exponentially from this value).
-            timeout: The socket timeout of the HTTP requests sent to the Apify API.
-            headers: Additional HTTP headers to include in all API requests.
+                (increases exponentially from this value). Only used when `http_client` is not provided.
+            timeout: The socket timeout of the HTTP requests sent to the Apify API. Only used when `http_client`
+                is not provided.
+            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
+                client is responsible for its own configuration.
         """
         # 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 headers:
+        if headers and not http_client:
             self._check_custom_headers(headers)
 
         self._token = token
@@ -389,14 +420,17 @@ def __init__(
         self._statistics = ClientStatistics()
         """Collector for client request statistics."""
 
-        self._http_client = HttpClientAsync(
-            token=self._token,
-            timeout=timeout,
-            max_retries=max_retries,
-            min_delay_between_retries=min_delay_between_retries,
-            statistics=self._statistics,
-            headers=headers,
-        )
+        if http_client is not None:
+            self._http_client: HttpClientAsync = http_client
+        else:
+            self._http_client = ImpitHttpClientAsync(
+                token=self._token,
+                timeout=timeout,
+                max_retries=max_retries,
+                min_delay_between_retries=min_delay_between_retries,
+                statistics=self._statistics,
+                headers=headers,
+            )
         """HTTP client used to communicate with the Apify API."""
 
         self._client_registry = ClientRegistryAsync(
@@ -459,6 +493,15 @@ def token(self) -> str | None:
         """The Apify API token used by the client."""
         return self._token
 
+    @property
+    def http_client(self) -> HttpClientAsync:
+        """The HTTP client instance used for API communication.
+
+        Returns the custom HTTP client if one was provided during initialization,
+        or the default `ImpitHttpClientAsync` otherwise.
+        """
+        return self._http_client
+
     def actor(self, actor_id: str) -> ActorClientAsync:
         """Retrieve the sub-client for manipulating a single Actor.
 

src/apify_client/_http_clients/__init__.py

@@ -1,6 +1,10 @@
-from ._http_client import HttpClient, HttpClientAsync
+from ._base import HttpClient, HttpClientAsync, HttpResponse
+from ._impit import ImpitHttpClient, ImpitHttpClientAsync
 
 __all__ = [
     'HttpClient',
     'HttpClientAsync',
+    'HttpResponse',
+    'ImpitHttpClient',
+    'ImpitHttpClientAsync',
 ]