feat: Refactor the implementation to use hierarchy of classes

Author: mixalturek

README.md

@@ -48,21 +48,28 @@
 
     or any other Python package manager that consumes PyPI.
 
-    To enable brotli request-body compression (better than gzip, especially for large payloads), install the optional extra:
+    The client compresses request bodies with gzip by default (no extra dependencies required). To opt in to brotli
+    (better compression ratio), install the optional extra and pass `encoding='brotli'`:
 
     ```bash
     pip install "apify-client[brotli]"
     # or
     uv add "apify-client[brotli]"
     ```
 
-    Without this extra the client falls back to gzip automatically. You can also force gzip at runtime without uninstalling the extra:
-
     ```python
-    client = ApifyClient(token='MY-APIFY-TOKEN', compression_algorithm='gzip', compression_quality=9)
+    client = ApifyClient(token='MY-APIFY-TOKEN', encoding='brotli')
     ```
 
-    Both `compression_algorithm` (`'brotli'` or `'gzip'`) and `compression_quality` (brotli: `1–11`, gzip: `1–9`, default `6`) are configurable on the client constructor.
+    For fine-grained control over compression quality, inject a compressor instance directly:
+
+    ```python
+    from apify_client.http_compressors import BrotliHttpCompressor, GzipHttpCompressor
+
+    client = ApifyClient(token='MY-APIFY-TOKEN', encoding=BrotliHttpCompressor(quality=11))
+    # or
+    client = ApifyClient(token='MY-APIFY-TOKEN', encoding=GzipHttpCompressor(quality=9))
+    ```
 
 - From [conda-forge](https://anaconda.org/conda-forge/apify-client), it can be installed with [conda](https://docs.conda.io/en/latest/):
 

src/apify_client/_apify_client.py

@@ -7,8 +7,6 @@
 from apify_client._consts import (
     API_VERSION,
     DEFAULT_API_URL,
-    DEFAULT_COMPRESSION_ALGORITHM,
-    DEFAULT_COMPRESSION_QUALITY,
     DEFAULT_MAX_RETRIES,
     DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
     DEFAULT_TIMEOUT_LONG,
@@ -76,11 +74,42 @@
 from apify_client._statistics import ClientStatistics
 from apify_client._utils import check_custom_headers
 from apify_client.http_clients import HttpClient, HttpClientAsync, ImpitHttpClient, ImpitHttpClientAsync
+from apify_client.http_compressors import GzipHttpCompressor
+from apify_client.http_compressors._base import HttpCompressor
 
 if TYPE_CHECKING:
     from datetime import timedelta
 
-    from apify_client.types import CompressionAlgorithm
+    from apify_client.types import HttpCompressionAlgorithm
+
+
+def _resolve_compressor(encoding: HttpCompressionAlgorithm | HttpCompressor) -> HttpCompressor:
+    """Convert an encoding string or `HttpCompressor` instance into a concrete `HttpCompressor`.
+
+    Args:
+        encoding: Either a string literal (`'gzip'` or `'brotli'`) or an `HttpCompressor` instance.
+
+    Returns:
+        A ready-to-use `HttpCompressor`.
+
+    Raises:
+        ImportError: If `'brotli'` is requested but the `brotli` extra is not installed.
+        ValueError: If `encoding` is not a recognized compression algorithm.
+    """
+    if isinstance(encoding, HttpCompressor):
+        return encoding
+    elif encoding == 'gzip':
+        return GzipHttpCompressor()
+    elif encoding == 'brotli':
+        # The import is here so the ImportError is raised at call time,
+        # not at module import time, giving users a clear message.
+        from apify_client.http_compressors import BrotliHttpCompressor  # noqa: PLC0415
+
+        return BrotliHttpCompressor()
+    else:
+        # The backend supports also `deflate` and `identity` (no compression). One can build
+        # a custom compressor if needed.
+        raise ValueError(f'Unsupported compression algorithm: {encoding!r}')
 
 
 @docs_group('Apify API clients')
@@ -126,8 +155,7 @@ def __init__(
         timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
         timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         headers: dict[str, str] | None = None,
-        compression_algorithm: CompressionAlgorithm = DEFAULT_COMPRESSION_ALGORITHM,
-        compression_quality: int = DEFAULT_COMPRESSION_QUALITY,
+        encoding: HttpCompressionAlgorithm | HttpCompressor = 'gzip',
     ) -> None:
         """Initialize the Apify API client.
 
@@ -149,11 +177,9 @@ def __init__(
             timeout_long: Default timeout for long-duration API operations (long-polling, streaming, ...).
             timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             headers: Additional HTTP headers to include in all API requests.
-            compression_algorithm: Algorithm used to compress request bodies. `'brotli'` (default) uses brotli
-                when the `brotli` extra is installed and falls back to gzip when unavailable. `'gzip'` always
-                uses gzip regardless of whether the extra is installed.
-            compression_quality: Compression quality level. Valid range is `1-11` for brotli and `1-9` for gzip.
-                Defaults to `6`.
+            encoding: Compression algorithm for request bodies. Pass `'gzip'` (default, no extra required) or
+                `'brotli'` (requires `pip install "apify-client[brotli]"`). For custom quality or full control,
+                pass an `HttpCompressor` instance directly, e.g. `BrotliHttpCompressor(quality=11)`.
         """
         # 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
@@ -216,8 +242,7 @@ def __init__(
         self._timeout_long = timeout_long
         self._timeout_max = timeout_max
         self._headers = headers
-        self._compression_algorithm = compression_algorithm
-        self._compression_quality = compression_quality
+        self._encoding = encoding
 
     @classmethod
     def with_custom_http_client(
@@ -283,8 +308,7 @@ def http_client(self) -> HttpClient:
                 min_delay_between_retries=self._min_delay_between_retries,
                 statistics=self._statistics,
                 headers=self._headers,
-                compression_algorithm=self._compression_algorithm,
-                compression_quality=self._compression_quality,
+                compressor=_resolve_compressor(self._encoding),
             )
 
         return self._http_client
@@ -491,8 +515,7 @@ def __init__(
         timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
         timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         headers: dict[str, str] | None = None,
-        compression_algorithm: CompressionAlgorithm = DEFAULT_COMPRESSION_ALGORITHM,
-        compression_quality: int = DEFAULT_COMPRESSION_QUALITY,
+        encoding: HttpCompressionAlgorithm | HttpCompressor = 'gzip',
     ) -> None:
         """Initialize the Apify API client.
 
@@ -514,11 +537,9 @@ def __init__(
             timeout_long: Default timeout for long-duration API operations (long-polling, streaming, ...).
             timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             headers: Additional HTTP headers to include in all API requests.
-            compression_algorithm: Algorithm used to compress request bodies. `'brotli'` (default) uses brotli
-                when the `brotli` extra is installed and falls back to gzip when unavailable. `'gzip'` always
-                uses gzip regardless of whether the extra is installed.
-            compression_quality: Compression quality level. Valid range is `1-11` for brotli and `1-9` for gzip.
-                Defaults to `6`.
+            encoding: Compression algorithm for request bodies. Pass `'gzip'` (default, no extra required) or
+                `'brotli'` (requires `pip install "apify-client[brotli]"`). For custom quality or full control,
+                pass an `HttpCompressor` instance directly, e.g. `BrotliHttpCompressor(quality=11)`.
         """
         # 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
@@ -581,8 +602,7 @@ def __init__(
         self._timeout_long = timeout_long
         self._timeout_max = timeout_max
         self._headers = headers
-        self._compression_algorithm = compression_algorithm
-        self._compression_quality = compression_quality
+        self._encoding = encoding
 
     @classmethod
     def with_custom_http_client(
@@ -648,8 +668,7 @@ def http_client(self) -> HttpClientAsync:
                 min_delay_between_retries=self._min_delay_between_retries,
                 statistics=self._statistics,
                 headers=self._headers,
-                compression_algorithm=self._compression_algorithm,
-                compression_quality=self._compression_quality,
+                compressor=_resolve_compressor(self._encoding),
             )
         return self._http_client
 

src/apify_client/_consts.py

@@ -1,10 +1,6 @@
 from __future__ import annotations
 
 from datetime import timedelta
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from apify_client.types import CompressionAlgorithm
 
 DEFAULT_API_URL = 'https://api.apify.com'
 """Default base URL for the Apify API."""
@@ -38,21 +34,3 @@
 
 OVERRIDABLE_DEFAULT_HEADERS = {'Accept', 'Authorization', 'Accept-Encoding', 'User-Agent'}
 """Headers that can be overridden by users, but will trigger a warning if they do so, as it may lead to API errors."""
-
-DEFAULT_COMPRESSION_ALGORITHM: CompressionAlgorithm = 'brotli'
-"""Default compression algorithm for request bodies."""
-
-DEFAULT_COMPRESSION_QUALITY: int = 6
-"""Default compression quality for request bodies (brotli: 1-11, gzip: 1-9)."""
-
-BROTLI_QUALITY_MIN: int = 1
-"""Minimum quality level for brotli compression."""
-
-BROTLI_QUALITY_MAX: int = 11
-"""Maximum quality level for brotli compression."""
-
-GZIP_QUALITY_MIN: int = 1
-"""Minimum quality level for gzip compression."""
-
-GZIP_QUALITY_MAX: int = 9
-"""Maximum quality level for gzip compression."""

src/apify_client/_utils.py

@@ -5,10 +5,14 @@
 import io
 import json
 import string
+import sys
 import time
 import warnings
 from base64 import b64encode, urlsafe_b64encode
+from contextlib import contextmanager
+from dataclasses import dataclass
 from functools import cache
+from types import ModuleType
 from typing import TYPE_CHECKING, Any, Literal, TypeVar, overload
 
 import impit
@@ -18,6 +22,7 @@
 from apify_client.errors import InvalidResponseBodyError, NotFoundError
 
 if TYPE_CHECKING:
+    from collections.abc import Generator
     from datetime import timedelta
 
     from apify_client.errors import ApifyApiError
@@ -27,7 +32,50 @@
 T = TypeVar('T')
 
 _BASE62_CHARSET = string.digits + string.ascii_letters
-"""Module-level constant for base62 encoding."""
+
+
+@dataclass
+class _FailedImport:
+    message: str
+
+
+class _ImportWrapper(ModuleType):
+    """Module subclass that converts `_FailedImport` attribute accesses into `ImportError`."""
+
+    def __getattr__(self, name: str) -> object:
+        obj = super().__getattribute__(name)
+        if isinstance(obj, _FailedImport):
+            raise ImportError(obj.message)  # noqa: TRY004
+        return obj
+
+
+@contextmanager
+def try_import(module_name: str, symbol_name: str) -> Generator[None, None, None]:
+    """Context manager for optional imports.
+
+    If the import inside the block raises `ImportError`, the named symbol in the given module is
+    replaced with a `_FailedImport` placeholder. Accessing that placeholder later (after
+    `install_import_hook` has been called) raises a clear `ImportError` with the original message.
+
+    Args:
+        module_name: Fully-qualified name of the module whose namespace to update (pass `__name__`).
+        symbol_name: The name that would have been imported, used as the placeholder key.
+    """
+    try:
+        yield
+    except ImportError as exc:
+        sys.modules[module_name].__dict__[symbol_name] = _FailedImport(str(exc))
+
+
+def install_import_hook(module_name: str) -> None:
+    """Replace a module's class with `_ImportWrapper` to activate deferred `ImportError` raising.
+
+    Must be called after all `try_import` blocks in the same `__init__.py`.
+
+    Args:
+        module_name: Fully-qualified name of the module to wrap (pass `__name__`).
+    """
+    sys.modules[module_name].__class__ = _ImportWrapper
 
 
 @overload