refactor: Standardize timeout handling across all resource clients

- Replace three inconsistent timeout constants (DEFAULT_TIMEOUT 360s,
  FAST_OPERATION_TIMEOUT 5s, STANDARD_OPERATION_TIMEOUT 30s) with a
  single DEFAULT_REQUEST_TIMEOUT (30s) that grows exponentially on retry
- Add `timeout` parameter to all public resource client methods for
  user-controllable HTTP request 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

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

Author: vdusek

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

@@ -16,8 +16,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 +31,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,7 +10,7 @@
 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
 from apify_client._docs import docs_group
 from apify_client._statistics import ClientStatistics
 from apify_client._utils import to_seconds
@@ -85,7 +85,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,
@@ -240,7 +240,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')
@@ -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,7 @@
 
 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
 from apify_client._docs import docs_group
 from apify_client._http_clients import HttpClient, HttpClientAsync
 from apify_client._logging import log_context, logger_name
@@ -58,7 +58,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,
@@ -284,7 +284,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,

src/apify_client/_resource_clients/_resource_client.py

@@ -6,7 +6,12 @@
 from functools import cached_property
 from typing import TYPE_CHECKING, Any
 
-from apify_client._consts import DEFAULT_WAIT_FOR_FINISH, DEFAULT_WAIT_WHEN_JOB_NOT_EXIST, TERMINAL_STATUSES
+from apify_client._consts import (
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_WAIT_FOR_FINISH,
+    DEFAULT_WAIT_WHEN_JOB_NOT_EXIST,
+    TERMINAL_STATUSES,
+)
 from apify_client._docs import docs_group
 from apify_client._internal_models import ActorJobResponse
 from apify_client._logging import WithLogDetailsClient
@@ -192,7 +197,7 @@ def __init__(
             params=params,
         )
 
-    def _get(self, *, timeout: timedelta | None = None) -> dict | None:
+    def _get(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT) -> dict | None:
         """Perform a GET request for this resource, returning the parsed response or None if not found."""
         try:
             response = self._http_client.call(
@@ -206,7 +211,7 @@ def _get(self, *, timeout: timedelta | None = None) -> dict | None:
             catch_not_found_or_throw(exc)
             return None
 
-    def _update(self, *, timeout: timedelta | None = None, **kwargs: Any) -> dict:
+    def _update(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT, **kwargs: Any) -> dict:
         """Perform a PUT request to update this resource with the given fields."""
         response = self._http_client.call(
             url=self._build_url(),
@@ -217,7 +222,7 @@ def _update(self, *, timeout: timedelta | None = None, **kwargs: Any) -> dict:
         )
         return response_to_dict(response)
 
-    def _delete(self, *, timeout: timedelta | None = None) -> None:
+    def _delete(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT) -> None:
         """Perform a DELETE request to delete this resource, ignoring 404 errors."""
         try:
             self._http_client.call(
@@ -229,32 +234,41 @@ def _delete(self, *, timeout: timedelta | None = None) -> None:
         except ApifyApiError as exc:
             catch_not_found_or_throw(exc)
 
-    def _list(self, **kwargs: Any) -> dict:
+    def _list(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT, **kwargs: Any) -> dict:
         """Perform a GET request to list resources."""
         response = self._http_client.call(
             url=self._build_url(),
             method='GET',
             params=self._build_params(**kwargs),
+            timeout=timeout,
         )
         return response_to_dict(response)
 
-    def _create(self, **kwargs: Any) -> dict:
+    def _create(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT, **kwargs: Any) -> dict:
         """Perform a POST request to create a resource."""
         response = self._http_client.call(
             url=self._build_url(),
             method='POST',
             params=self._build_params(),
             json=self._clean_json_payload(kwargs),
+            timeout=timeout,
         )
         return response_to_dict(response)
 
-    def _get_or_create(self, *, name: str | None = None, resource_fields: dict | None = None) -> dict:
+    def _get_or_create(
+        self,
+        *,
+        name: str | None = None,
+        resource_fields: dict | None = None,
+        timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT,
+    ) -> dict:
         """Perform a POST request to get or create a named resource."""
         response = self._http_client.call(
             url=self._build_url(),
             method='POST',
             params=self._build_params(name=name),
             json=self._clean_json_payload(resource_fields) if resource_fields is not None else None,
+            timeout=timeout,
         )
         return response_to_dict(response)
 
@@ -263,6 +277,7 @@ def _wait_for_finish(
         url: str,
         params: dict,
         wait_duration: timedelta | None = None,
+        timeout: timedelta | None = None,
     ) -> dict | None:
         """Wait synchronously for an Actor job (run or build) to finish.
 
@@ -273,6 +288,7 @@ def _wait_for_finish(
             url: Full URL to the job endpoint.
             params: Base query parameters to include in each request.
             wait_duration: Maximum time to wait (None = indefinite).
+            timeout: Timeout for each HTTP request (None = no timeout).
 
         Returns:
             Job data dict when finished, or None if job doesn't exist after
@@ -298,6 +314,7 @@ def _wait_for_finish(
                     url=url,
                     method='GET',
                     params={**params, 'waitForFinish': wait_for_finish},
+                    timeout=timeout,
                 )
                 result = response_to_dict(response)
                 actor_job_response = ActorJobResponse.model_validate(result)
@@ -359,7 +376,7 @@ def __init__(
             params=params,
         )
 
-    async def _get(self, *, timeout: timedelta | None = None) -> dict | None:
+    async def _get(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT) -> dict | None:
         """Perform a GET request for this resource, returning the parsed response or None if not found."""
         try:
             response = await self._http_client.call(
@@ -373,7 +390,7 @@ async def _get(self, *, timeout: timedelta | None = None) -> dict | None:
             catch_not_found_or_throw(exc)
             return None
 
-    async def _update(self, *, timeout: timedelta | None = None, **kwargs: Any) -> dict:
+    async def _update(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT, **kwargs: Any) -> dict:
         """Perform a PUT request to update this resource with the given fields."""
         response = await self._http_client.call(
             url=self._build_url(),
@@ -384,7 +401,7 @@ async def _update(self, *, timeout: timedelta | None = None, **kwargs: Any) -> d
         )
         return response_to_dict(response)
 
-    async def _delete(self, *, timeout: timedelta | None = None) -> None:
+    async def _delete(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT) -> None:
         """Perform a DELETE request to delete this resource, ignoring 404 errors."""
         try:
             await self._http_client.call(
@@ -396,32 +413,41 @@ async def _delete(self, *, timeout: timedelta | None = None) -> None:
         except ApifyApiError as exc:
             catch_not_found_or_throw(exc)
 
-    async def _list(self, **kwargs: Any) -> dict:
+    async def _list(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT, **kwargs: Any) -> dict:
         """Perform a GET request to list resources."""
         response = await self._http_client.call(
             url=self._build_url(),
             method='GET',
             params=self._build_params(**kwargs),
+            timeout=timeout,
         )
         return response_to_dict(response)
 
-    async def _create(self, **kwargs: Any) -> dict:
+    async def _create(self, *, timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT, **kwargs: Any) -> dict:
         """Perform a POST request to create a resource."""
         response = await self._http_client.call(
             url=self._build_url(),
             method='POST',
             params=self._build_params(),
             json=self._clean_json_payload(kwargs),
+            timeout=timeout,
         )
         return response_to_dict(response)
 
-    async def _get_or_create(self, *, name: str | None = None, resource_fields: dict | None = None) -> dict:
+    async def _get_or_create(
+        self,
+        *,
+        name: str | None = None,
+        resource_fields: dict | None = None,
+        timeout: timedelta | None = DEFAULT_REQUEST_TIMEOUT,
+    ) -> dict:
         """Perform a POST request to get or create a named resource."""
         response = await self._http_client.call(
             url=self._build_url(),
             method='POST',
             params=self._build_params(name=name),
             json=self._clean_json_payload(resource_fields) if resource_fields is not None else None,
+            timeout=timeout,
         )
         return response_to_dict(response)
 
@@ -430,6 +456,7 @@ async def _wait_for_finish(
         url: str,
         params: dict,
         wait_duration: timedelta | None = None,
+        timeout: timedelta | None = None,
     ) -> dict | None:
         """Wait asynchronously for an Actor job (run or build) to finish.
 
@@ -440,6 +467,7 @@ async def _wait_for_finish(
             url: Full URL to the job endpoint.
             params: Base query parameters to include in each request.
             wait_duration: Maximum time to wait (None = indefinite).
+            timeout: Timeout for each HTTP request (None = no timeout).
 
         Returns:
             Job data dict when finished, or None if job doesn't exist after
@@ -465,6 +493,7 @@ async def _wait_for_finish(
                     url=url,
                     method='GET',
                     params={**params, 'waitForFinish': wait_for_finish},
+                    timeout=timeout,
                 )
                 result = response_to_dict(response)
                 actor_job_response = ActorJobResponse.model_validate(result)