three tier timeout

Author: vdusek

docs/02_concepts/code/05_retries_async.py

@@ -10,5 +10,5 @@ async def main() -> None:
         token=TOKEN,
         max_retries=8,
         min_delay_between_retries=timedelta(milliseconds=500),
-        timeout=timedelta(seconds=360),
+        timeout_short=timedelta(seconds=360),
     )

docs/02_concepts/code/05_retries_sync.py

@@ -10,5 +10,5 @@ def main() -> None:
         token=TOKEN,
         max_retries=8,
         min_delay_between_retries=timedelta(milliseconds=500),
-        timeout=timedelta(seconds=360),
+        timeout_short=timedelta(seconds=360),
     )

src/apify_client/_apify_client.py

@@ -9,8 +9,10 @@
     DEFAULT_API_URL,
     DEFAULT_MAX_RETRIES,
     DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-    DEFAULT_REQUEST_TIMEOUT,
-    DEFAULT_REQUEST_TIMEOUT_MAX,
+    DEFAULT_TIMEOUT,
+    DEFAULT_TIMEOUT_LONG,
+    DEFAULT_TIMEOUT_MAX,
+    DEFAULT_TIMEOUT_SHORT,
 )
 from apify_client._docs import docs_group
 from apify_client._http_clients import HttpClient, HttpClientAsync, ImpitHttpClient, ImpitHttpClientAsync
@@ -115,8 +117,10 @@ def __init__(
         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_REQUEST_TIMEOUT,
-        timeout_max: timedelta = DEFAULT_REQUEST_TIMEOUT_MAX,
+        timeout_short: timedelta = DEFAULT_TIMEOUT_SHORT,
+        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
+        timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         headers: dict[str, str] | None = None,
     ) -> None:
         """Initialize the Apify API client.
@@ -134,7 +138,9 @@ def __init__(
             max_retries: How many times to retry a failed request at most.
             min_delay_between_retries: How long will the client wait between retrying requests
                 (increases exponentially from this value).
-            timeout: The initial socket timeout of the HTTP requests sent to the Apify API.
+            timeout_short: Timeout for fast CRUD operations (e.g., get, update, delete).
+            timeout: Timeout for batch, list, and data transfer operations.
+            timeout_long: Timeout for long-polling, streaming, and other heavy operations.
             timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             headers: Additional HTTP headers to include in all API requests.
         """
@@ -194,7 +200,9 @@ def __init__(
         # Configuration for the default HTTP client (used if a custom client is not provided).
         self._max_retries = max_retries
         self._min_delay_between_retries = min_delay_between_retries
+        self._timeout_short = timeout_short
         self._timeout = timeout
+        self._timeout_long = timeout_long
         self._timeout_max = timeout_max
         self._headers = headers
 
@@ -253,7 +261,9 @@ def http_client(self) -> HttpClient:
         if self._http_client is None:
             self._http_client = ImpitHttpClient(
                 token=self._token,
+                timeout_short=self._timeout_short,
                 timeout=self._timeout,
+                timeout_long=self._timeout_long,
                 timeout_max=self._timeout_max,
                 max_retries=self._max_retries,
                 min_delay_between_retries=self._min_delay_between_retries,
@@ -460,8 +470,10 @@ def __init__(
         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_REQUEST_TIMEOUT,
-        timeout_max: timedelta = DEFAULT_REQUEST_TIMEOUT_MAX,
+        timeout_short: timedelta = DEFAULT_TIMEOUT_SHORT,
+        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
+        timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         headers: dict[str, str] | None = None,
     ) -> None:
         """Initialize the Apify API client.
@@ -479,7 +491,9 @@ def __init__(
             max_retries: How many times to retry a failed request at most.
             min_delay_between_retries: How long will the client wait between retrying requests
                 (increases exponentially from this value).
-            timeout: The initial socket timeout of the HTTP requests sent to the Apify API.
+            timeout_short: Timeout for fast CRUD operations (e.g., get, update, delete).
+            timeout: Timeout for batch, list, and data transfer operations.
+            timeout_long: Timeout for long-polling, streaming, and other heavy operations.
             timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             headers: Additional HTTP headers to include in all API requests.
         """
@@ -539,7 +553,9 @@ def __init__(
         # Configuration for the default HTTP client (used if a custom client is not provided).
         self._max_retries = max_retries
         self._min_delay_between_retries = min_delay_between_retries
+        self._timeout_short = timeout_short
         self._timeout = timeout
+        self._timeout_long = timeout_long
         self._timeout_max = timeout_max
         self._headers = headers
 
@@ -598,7 +614,9 @@ def http_client(self) -> HttpClientAsync:
         if self._http_client is None:
             self._http_client = ImpitHttpClientAsync(
                 token=self._token,
+                timeout_short=self._timeout_short,
                 timeout=self._timeout,
+                timeout_long=self._timeout_long,
                 timeout_max=self._timeout_max,
                 max_retries=self._max_retries,
                 min_delay_between_retries=self._min_delay_between_retries,

src/apify_client/_consts.py

@@ -5,11 +5,11 @@
 
 from apify_client._models import ActorJobStatus
 
-Timeout = timedelta | Literal['no_timeout'] | None
+Timeout = timedelta | Literal['no_timeout', 'short', 'default', 'long']
 """Type for the `timeout` parameter on resource client methods.
 
-`None` uses the timeout configured on the HTTP client, a `timedelta` overrides it for this call,
-and `'no_timeout'` disables the timeout entirely.
+`'short'`, `'default'`, and `'long'` are tier literals resolved by the HTTP client to configured values.
+A `timedelta` overrides the timeout for this call, and `'no_timeout'` disables the timeout entirely.
 """
 
 JsonSerializable = str | int | float | bool | None | dict[str, Any] | list[Any]
@@ -23,10 +23,16 @@
 API_VERSION = 'v2'
 """Current Apify API version."""
 
-DEFAULT_REQUEST_TIMEOUT = timedelta(seconds=10)
-"""Default initial timeout for individual API requests."""
+DEFAULT_TIMEOUT_SHORT = timedelta(seconds=5)
+"""Default timeout for fast CRUD operations (e.g., get, update, delete)."""
 
-DEFAULT_REQUEST_TIMEOUT_MAX = timedelta(seconds=600)
+DEFAULT_TIMEOUT = timedelta(seconds=30)
+"""Default timeout for batch, list, and data transfer operations."""
+
+DEFAULT_TIMEOUT_LONG = timedelta(seconds=300)
+"""Default timeout for long-polling, streaming, and other heavy operations."""
+
+DEFAULT_TIMEOUT_MAX = timedelta(seconds=600)
 """Default maximum timeout cap for individual API requests (limits exponential growth)."""
 
 DEFAULT_MAX_RETRIES = 4

src/apify_client/_http_clients/_base.py

@@ -13,8 +13,10 @@
 from apify_client._consts import (
     DEFAULT_MAX_RETRIES,
     DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-    DEFAULT_REQUEST_TIMEOUT,
-    DEFAULT_REQUEST_TIMEOUT_MAX,
+    DEFAULT_TIMEOUT,
+    DEFAULT_TIMEOUT_LONG,
+    DEFAULT_TIMEOUT_MAX,
+    DEFAULT_TIMEOUT_SHORT,
     Timeout,
 )
 from apify_client._docs import docs_group
@@ -90,8 +92,10 @@ def __init__(
         self,
         *,
         token: str | None = None,
-        timeout: timedelta = DEFAULT_REQUEST_TIMEOUT,
-        timeout_max: timedelta = DEFAULT_REQUEST_TIMEOUT_MAX,
+        timeout_short: timedelta = DEFAULT_TIMEOUT_SHORT,
+        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout_long: timedelta = DEFAULT_TIMEOUT_LONG,
+        timeout_max: timedelta = DEFAULT_TIMEOUT_MAX,
         max_retries: int = DEFAULT_MAX_RETRIES,
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
         statistics: ClientStatistics | None = None,
@@ -101,14 +105,18 @@ def __init__(
 
         Args:
             token: Apify API token for authentication.
-            timeout: Initial request timeout.
+            timeout_short: Timeout for fast CRUD operations (e.g., get, update, delete).
+            timeout: Timeout for batch, list, and data transfer operations.
+            timeout_long: Timeout for long-polling, streaming, and other heavy operations.
             timeout_max: Maximum timeout cap for exponential timeout growth across retries.
             max_retries: Maximum number of retries for failed requests.
             min_delay_between_retries: Minimum delay between retries.
             statistics: Statistics tracker for API calls. Created automatically if not provided.
             headers: Additional HTTP headers to include in all requests.
         """
+        self._timeout_short = timeout_short
         self._timeout = timeout
+        self._timeout_long = timeout_long
         self._timeout_max = timeout_max
         self._max_retries = max_retries
         self._min_delay_between_retries = min_delay_between_retries
@@ -133,6 +141,45 @@ def __init__(
 
         self._headers = {**default_headers, **(headers or {})}
 
+    @property
+    def timeout_short(self) -> timedelta:
+        """Timeout for fast CRUD operations (e.g., get, update, delete)."""
+        return self._timeout_short
+
+    @property
+    def timeout(self) -> timedelta:
+        """Timeout for batch, list, and data transfer operations."""
+        return self._timeout
+
+    @property
+    def timeout_long(self) -> timedelta:
+        """Timeout for long-polling, streaming, and other heavy operations."""
+        return self._timeout_long
+
+    @property
+    def timeout_max(self) -> timedelta:
+        """Maximum timeout cap for exponential timeout growth across retries."""
+        return self._timeout_max
+
+    def _resolve_timeout(self, timeout: Timeout) -> timedelta | None:
+        """Resolve a timeout tier literal or value to a concrete timedelta.
+
+        Args:
+            timeout: The timeout specification to resolve.
+
+        Returns:
+            A `timedelta` for tier literals and explicit values, `None` for `'no_timeout'`.
+        """
+        if timeout == 'no_timeout':
+            return None
+        if timeout == 'short':
+            return self._timeout_short
+        if timeout == 'default':
+            return self._timeout
+        if timeout == 'long':
+            return self._timeout_long
+        return timeout
+
     @staticmethod
     def _parse_params(params: dict[str, Any] | None) -> dict[str, Any] | None:
         """Convert request parameters to Apify API-compatible formats.
@@ -221,7 +268,7 @@ def call(
         data: str | bytes | bytearray | None = None,
         json: Any = None,
         stream: bool | None = None,
-        timeout: Timeout = None,
+        timeout: Timeout = 'default',
     ) -> HttpResponse:
         """Make an HTTP request.
 
@@ -233,8 +280,9 @@ def call(
             data: Raw request body data. Cannot be used together with json.
             json: JSON-serializable data for the request body. Cannot be used together with data.
             stream: Whether to stream the response body.
-            timeout: Timeout for the API HTTP request. `None` uses the timeout configured on the client,
-                a `timedelta` overrides it for this call, and `'no_timeout'` disables the timeout entirely.
+            timeout: Timeout for the API HTTP request.
+                Use `'short'`, `'default'`, or `'long'` tier literals for preconfigured timeouts.
+                A `timedelta` overrides it for this call, and `'no_timeout'` disables the timeout entirely.
 
         Returns:
             The HTTP response object.
@@ -264,7 +312,7 @@ async def call(
         data: str | bytes | bytearray | None = None,
         json: Any = None,
         stream: bool | None = None,
-        timeout: Timeout = None,
+        timeout: Timeout = 'default',
     ) -> HttpResponse:
         """Make an HTTP request.
 
@@ -276,8 +324,9 @@ async def call(
             data: Raw request body data. Cannot be used together with json.
             json: JSON-serializable data for the request body. Cannot be used together with data.
             stream: Whether to stream the response body.
-            timeout: Timeout for the API HTTP request. `None` uses the timeout configured on the client,
-                a `timedelta` overrides it for this call, and `'no_timeout'` disables the timeout entirely.
+            timeout: Timeout for the API HTTP request.
+                Use `'short'`, `'default'`, or `'long'` tier literals for preconfigured timeouts.
+                A `timedelta` overrides it for this call, and `'no_timeout'` disables the timeout entirely.
 
         Returns:
             The HTTP response object.