refactor: Standardize timeout handling with Timeout type alias

- Add `Timeout` type alias (`timedelta | Literal['no_timeout'] | None`)
  to `_consts.py` and export it from the public API
- Accept `None` on abstract `HttpClient.call()` / `HttpClientAsync.call()`
  so the HTTP client resolves its own default timeout internally
- Move `_calculate_timeout` into the impit HTTP client implementation
  since exponential timeout growth on retries is client-specific logic
- Add `timeout` parameter to all public resource client methods for
  user-controllable per-request HTTP timeouts
- Add timeout parameter to base methods `_list()`, `_create()`, and
  `_get_or_create()` which previously lacked it
- Rename domain-specific Actor/Task run timeout from `timeout` to
  `run_timeout` to avoid ambiguity with the HTTP request timeout
- Update docstrings to document three-state timeout semantics

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

Author: vdusek

src/apify_client/__init__.py

@@ -1,6 +1,7 @@
 from importlib import metadata
 
 from ._apify_client import ApifyClient, ApifyClientAsync
+from ._consts import Timeout
 from ._http_clients import (
     HttpClient,
     HttpClientAsync,
@@ -19,5 +20,6 @@
     'HttpResponse',
     'ImpitHttpClient',
     'ImpitHttpClientAsync',
+    'Timeout',
     '__version__',
 ]

src/apify_client/_apify_client.py

@@ -9,7 +9,7 @@
     DEFAULT_API_URL,
     DEFAULT_MAX_RETRIES,
     DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
-    DEFAULT_TIMEOUT,
+    DEFAULT_REQUEST_TIMEOUT,
 )
 from apify_client._docs import docs_group
 from apify_client._http_clients import HttpClient, HttpClientAsync, ImpitHttpClient, ImpitHttpClientAsync
@@ -114,7 +114,7 @@ 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_TIMEOUT,
+        timeout: timedelta = DEFAULT_REQUEST_TIMEOUT,
         headers: dict[str, str] | None = None,
     ) -> None:
         """Initialize the Apify API client.
@@ -455,7 +455,7 @@ 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_TIMEOUT,
+        timeout: timedelta = DEFAULT_REQUEST_TIMEOUT,
         headers: dict[str, str] | None = None,
     ) -> None:
         """Initialize the Apify API client.

src/apify_client/_consts.py

@@ -1,10 +1,17 @@
 from __future__ import annotations
 
 from datetime import timedelta
-from typing import Any
+from typing import Any, Literal
 
 from apify_client._models import ActorJobStatus
 
+Timeout = timedelta | Literal['no_timeout'] | None
+"""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.
+"""
+
 JsonSerializable = str | int | float | bool | None | dict[str, Any] | list[Any]
 """Type for representing json-serializable values. It's close enough to the real thing supported by json.parse.
 It was suggested in a discussion with (and approved by) Guido van Rossum, so I'd consider it correct enough.
@@ -16,8 +23,8 @@
 API_VERSION = 'v2'
 """Current Apify API version."""
 
-DEFAULT_TIMEOUT = timedelta(seconds=360)
-"""Default request timeout."""
+DEFAULT_REQUEST_TIMEOUT = timedelta(seconds=30)
+"""Default timeout for individual API requests."""
 
 DEFAULT_MAX_RETRIES = 8
 """Default maximum number of retries for failed requests."""
@@ -31,12 +38,6 @@
 DEFAULT_WAIT_WHEN_JOB_NOT_EXIST = timedelta(seconds=3)
 """How long to wait for a job to exist before giving up."""
 
-FAST_OPERATION_TIMEOUT = timedelta(seconds=5)
-"""Timeout for fast, idempotent operations (e.g., GET, DELETE)."""
-
-STANDARD_OPERATION_TIMEOUT = timedelta(seconds=30)
-"""Timeout for operations that may take longer (e.g., list operations, batch operations)."""
-
 TERMINAL_STATUSES = frozenset(
     {
         ActorJobStatus.SUCCEEDED,

src/apify_client/_http_clients/_base.py

@@ -10,15 +10,19 @@
 from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 from urllib.parse import urlencode
 
-from apify_client._consts import DEFAULT_MAX_RETRIES, DEFAULT_MIN_DELAY_BETWEEN_RETRIES, DEFAULT_TIMEOUT
+from apify_client._consts import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
+    DEFAULT_REQUEST_TIMEOUT,
+    Timeout,
+)
 from apify_client._docs import docs_group
 from apify_client._statistics import ClientStatistics
-from apify_client._utils import to_seconds
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterator, Mapping
 
-    from apify_client._consts import JsonSerializable
+    from apify_client._consts import JsonSerializable, Timeout
 
 
 @docs_group('HTTP clients')
@@ -85,7 +89,7 @@ def __init__(
         self,
         *,
         token: str | None = None,
-        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout: timedelta = DEFAULT_REQUEST_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
         statistics: ClientStatistics | None = None,
@@ -192,12 +196,6 @@ def _build_url_with_params(self, url: str, params: dict[str, Any] | None = None)
 
         return f'{url}?{query_string}'
 
-    def _calculate_timeout(self, attempt: int, timeout: timedelta | None = None) -> float:
-        """Calculate timeout for a request attempt with exponential increase, bounded by client timeout."""
-        timeout_secs = to_seconds(timeout or self._timeout)
-        client_timeout_secs = to_seconds(self._timeout)
-        return min(client_timeout_secs, timeout_secs * 2 ** (attempt - 1))
-
 
 @docs_group('HTTP clients')
 class HttpClient(HttpClientBase, ABC):
@@ -219,7 +217,7 @@ def call(
         data: str | bytes | bytearray | None = None,
         json: Any = None,
         stream: bool | None = None,
-        timeout: timedelta | None = None,
+        timeout: Timeout = None,
     ) -> HttpResponse:
         """Make an HTTP request.
 
@@ -231,7 +229,8 @@ 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 this specific request.
+            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.
 
         Returns:
             The HTTP response object.
@@ -240,7 +239,6 @@ def call(
             ApifyApiError: If the request fails after all retries or returns a non-retryable error status.
             ValueError: If both json and data are provided.
         """
-        ...
 
 
 @docs_group('HTTP clients')
@@ -262,7 +260,7 @@ async def call(
         data: str | bytes | bytearray | None = None,
         json: Any = None,
         stream: bool | None = None,
-        timeout: timedelta | None = None,
+        timeout: Timeout = None,
     ) -> HttpResponse:
         """Make an HTTP request.
 
@@ -274,7 +272,8 @@ 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 this specific request.
+            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.
 
         Returns:
             The HTTP response object.
@@ -283,4 +282,3 @@ async def call(
             ApifyApiError: If the request fails after all retries or returns a non-retryable error status.
             ValueError: If both json and data are provided.
         """
-        ...

src/apify_client/_http_clients/_impit.py

@@ -10,7 +10,12 @@
 
 import impit
 
-from apify_client._consts import DEFAULT_MAX_RETRIES, DEFAULT_MIN_DELAY_BETWEEN_RETRIES, DEFAULT_TIMEOUT
+from apify_client._consts import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
+    DEFAULT_REQUEST_TIMEOUT,
+    Timeout,
+)
 from apify_client._docs import docs_group
 from apify_client._http_clients import HttpClient, HttpClientAsync
 from apify_client._logging import log_context, logger_name
@@ -20,7 +25,7 @@
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
-    from apify_client._consts import JsonSerializable
+    from apify_client._consts import JsonSerializable, Timeout
     from apify_client._http_clients import HttpResponse
     from apify_client._statistics import ClientStatistics
 
@@ -45,6 +50,24 @@ def _is_retryable_error(exc: Exception) -> bool:
     )
 
 
+def _compute_timeout(
+    client_timeout: timedelta,
+    attempt: int,
+    timeout: Timeout,
+) -> float:
+    """Compute timeout for a request attempt with exponential increase, bounded by client timeout.
+
+    For `'no_timeout'`, returns 0 (impit interprets this as no timeout). For `None`, uses the client-level timeout.
+    For `timedelta` values, doubles the timeout with each attempt but caps at the client-level timeout.
+    """
+    if timeout == 'no_timeout':
+        return 0
+
+    timeout_secs = to_seconds(timeout or client_timeout)
+    client_timeout_secs = to_seconds(client_timeout)
+    return min(client_timeout_secs, timeout_secs * 2 ** (attempt - 1))
+
+
 @docs_group('HTTP clients')
 class ImpitHttpClient(HttpClient):
     """Synchronous HTTP client for the Apify API built on top of [Impit](https://github.com/apify/impit).
@@ -58,7 +81,7 @@ def __init__(
         self,
         *,
         token: str | None = None,
-        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout: timedelta = DEFAULT_REQUEST_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
         statistics: ClientStatistics | None = None,
@@ -99,7 +122,7 @@ def call(
         data: str | bytes | bytearray | None = None,
         json: JsonSerializable | None = None,
         stream: bool | None = None,
-        timeout: timedelta | None = None,
+        timeout: Timeout = None,
     ) -> HttpResponse:
         """Make an HTTP request with automatic retry and exponential backoff.
 
@@ -111,7 +134,8 @@ 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 override for this request.
+            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.
 
         Returns:
             The HTTP response object.
@@ -154,7 +178,7 @@ def _make_request(
         params: dict[str, Any] | None,
         content: bytes | None,
         stream: bool | None,
-        timeout: timedelta | None,
+        timeout: Timeout,
     ) -> impit.Response:
         """Execute a single HTTP request attempt.
 
@@ -167,7 +191,7 @@ def _make_request(
             params: Query parameters.
             content: Request body content.
             stream: Whether to stream the response.
-            timeout: Timeout override for this request.
+            timeout: Timeout for this request.
 
         Returns:
             The HTTP response object.
@@ -188,7 +212,7 @@ def _make_request(
                 url=url_with_params,
                 headers=headers,
                 content=content,
-                timeout=self._calculate_timeout(attempt, timeout),
+                timeout=_compute_timeout(self._timeout, attempt, timeout),
                 stream=stream or False,
             )
 
@@ -284,7 +308,7 @@ def __init__(
         self,
         *,
         token: str | None = None,
-        timeout: timedelta = DEFAULT_TIMEOUT,
+        timeout: timedelta = DEFAULT_REQUEST_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
         min_delay_between_retries: timedelta = DEFAULT_MIN_DELAY_BETWEEN_RETRIES,
         statistics: ClientStatistics | None = None,
@@ -325,7 +349,7 @@ async def call(
         data: str | bytes | bytearray | None = None,
         json: JsonSerializable | None = None,
         stream: bool | None = None,
-        timeout: timedelta | None = None,
+        timeout: Timeout = None,
     ) -> HttpResponse:
         """Make an HTTP request with automatic retry and exponential backoff.
 
@@ -337,7 +361,8 @@ 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 override for this request.
+            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.
 
         Returns:
             The HTTP response object.
@@ -380,7 +405,7 @@ async def _make_request(
         params: dict[str, Any] | None,
         content: bytes | None,
         stream: bool | None,
-        timeout: timedelta | None,
+        timeout: Timeout,
     ) -> impit.Response:
         """Execute a single HTTP request attempt.
 
@@ -393,7 +418,7 @@ async def _make_request(
             params: Query parameters.
             content: Request body content.
             stream: Whether to stream the response.
-            timeout: Timeout override for this request.
+            timeout: Timeout for this request.
 
         Returns:
             The HTTP response object.
@@ -414,7 +439,7 @@ async def _make_request(
                 url=url_with_params,
                 headers=headers,
                 content=content,
-                timeout=self._calculate_timeout(attempt, timeout),
+                timeout=_compute_timeout(self._timeout, attempt, timeout),
                 stream=stream or False,
             )