diff --git a/docs/02_concepts/11_timeouts.mdx b/docs/02_concepts/11_timeouts.mdx
index 5adccdf4..c7080a4d 100644
--- a/docs/02_concepts/11_timeouts.mdx
+++ b/docs/02_concepts/11_timeouts.mdx
@@ -61,7 +61,7 @@ A `timedelta` longer than `timeout_max` is capped at `timeout_max`, and the clie
## Waiting for a job to finish
-Methods with a `wait_for_finish` parameter, such as `ActorClient.start` and `ActorClient.build`, ask the API to hold the response until the run or build finishes, for at most 60 seconds. When `timeout` is a tier, the client adds `wait_for_finish` (capped at 60 seconds) to the tier's value, so the request doesn't time out while the API still holds it. A `timedelta` and `'no_timeout'` are used as given.
+Methods with a `wait_for_finish` parameter, such as `ActorClient.start`, `ActorClient.build`, `RunClient.get`, and `BuildClient.get`, ask the API to hold the response until the run or build finishes, for at most 60 seconds. Pass `wait_for_finish` as a `timedelta`. The `start` and `build` methods also accept it as an `int` number of seconds. When `timeout` is a tier, the client adds `wait_for_finish` (capped at 60 seconds) to the tier's value, so the request doesn't time out while the API still holds it. A `timedelta` and `'no_timeout'` are used as given.
## Interaction with retries
diff --git a/src/apify_client/_resource_clients/_resource_client.py b/src/apify_client/_resource_clients/_resource_client.py
index d9398f7a..4ade4bf6 100644
--- a/src/apify_client/_resource_clients/_resource_client.py
+++ b/src/apify_client/_resource_clients/_resource_client.py
@@ -219,7 +219,7 @@ def __init__(
api_base_url=api_base_url,
)
- def _get(self, *, timeout: Timeout) -> dict | None:
+ def _get(self, *, timeout: Timeout, **kwargs: QueryParamValue) -> dict | None:
"""Perform a GET request for this resource, returning the parsed response or None if not found.
404s collapse to `None` only for ID-identified clients. Chained clients without a `resource_id`
@@ -229,7 +229,7 @@ def _get(self, *, timeout: Timeout) -> dict | None:
response = self._http_client.call(
url=self._build_url(),
method='GET',
- params=self._build_params(),
+ params=self._build_params(**kwargs),
timeout=timeout,
)
return response_to_dict(response)
@@ -414,7 +414,7 @@ def __init__(
api_base_url=api_base_url,
)
- async def _get(self, *, timeout: Timeout) -> dict | None:
+ async def _get(self, *, timeout: Timeout, **kwargs: QueryParamValue) -> dict | None:
"""Perform a GET request for this resource, returning the parsed response or None if not found.
404s collapse to `None` only for ID-identified clients. Chained clients without a `resource_id`
@@ -424,7 +424,7 @@ async def _get(self, *, timeout: Timeout) -> dict | None:
response = await self._http_client.call(
url=self._build_url(),
method='GET',
- params=self._build_params(),
+ params=self._build_params(**kwargs),
timeout=timeout,
)
return response_to_dict(response)
diff --git a/src/apify_client/_resource_clients/actor.py b/src/apify_client/_resource_clients/actor.py
index 3a3d183d..aa133d6d 100644
--- a/src/apify_client/_resource_clients/actor.py
+++ b/src/apify_client/_resource_clients/actor.py
@@ -26,7 +26,7 @@
from apify_client._utils.encoding import encode_key_value_store_record_value, encode_webhooks_to_base64
from apify_client._utils.http import response_to_dict
from apify_client._utils.server_args import build_actor_standby
-from apify_client._utils.time import to_seconds
+from apify_client._utils.time import to_seconds, to_whole_seconds
from apify_client._utils.wait_for_resources import (
prepare_resendable_body,
start_waiting_for_resources,
@@ -288,7 +288,7 @@ def start(
memory_mbytes: int | None = None,
run_timeout: timedelta | None = None,
force_permission_level: ActorPermissionLevel | None = None,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
webhooks: WebhooksList | None = None,
wait_for_resources: bool | timedelta = False,
timeout: Timeout = 'medium',
@@ -316,8 +316,8 @@ def start(
in the default run configuration for the Actor.
force_permission_level: Override the Actor's permissions for this run. If not set, the Actor will run
with permissions configured in the Actor settings.
- wait_for_finish: The maximum number of seconds the server waits for the run to finish. By default,
- it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the run to finish, as a `timedelta` or a number of
+ seconds. By default it is 0, and the API holds the response for at most 60 seconds.
webhooks: Optional ad-hoc webhooks (https://docs.apify.com/webhooks/ad-hoc-webhooks) associated with
the Actor run which can be used to receive a notification, e.g. when the Actor finished or failed.
If you already have a webhook set up for the Actor or task, you do not have to add it again here.
@@ -342,6 +342,7 @@ def start(
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
run_input, wait_for_resources = prepare_resendable_body(run_input, wait_for_resources=wait_for_resources)
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
build=build,
maxItems=max_items,
@@ -349,7 +350,7 @@ def start(
restartOnError=restart_on_error,
memory=memory_mbytes,
timeout=to_seconds(run_timeout, as_int=True),
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
forcePermissionLevel=force_permission_level,
webhooks=encode_webhooks_to_base64(webhooks),
)
@@ -361,7 +362,7 @@ def start(
headers={'content-type': content_type},
data=run_input,
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
),
wait_for_resources=wait_for_resources,
)
@@ -480,7 +481,7 @@ def build(
beta_packages: bool | None = None,
tag: str | None = None,
use_cache: bool | None = None,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
timeout: Timeout = 'medium',
) -> Build:
"""Build the Actor.
@@ -496,27 +497,28 @@ def build(
use_cache: If true, the Actor's Docker container will be rebuilt using layer cache
(https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache).
This is to enable quick rebuild during development. By default, the cache is not used.
- wait_for_finish: The maximum number of seconds the server waits for the build to finish before returning.
- By default it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the build to finish, as a `timedelta` or a number
+ of seconds. By default it is 0, and the API holds the response for at most 60 seconds.
timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
request outlasts the time the API holds the response.
Returns:
The build object.
"""
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
version=version_number,
betaPackages=beta_packages,
tag=tag,
useCache=use_cache,
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
)
response = self._http_client.call(
url=self._build_url('builds'),
method='POST',
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
)
result = response_to_dict(response)
@@ -539,7 +541,7 @@ def runs(self) -> RunCollectionClient:
def default_build(
self,
*,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
timeout: Timeout = 'short',
) -> BuildClient:
"""Retrieve Actor's default build.
@@ -547,23 +549,24 @@ def default_build(
https://docs.apify.com/api/v2/act-build-default-get
Args:
- wait_for_finish: The maximum number of seconds the server waits for the build to finish before returning.
- By default it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the build to finish, as a `timedelta` or a number
+ of seconds. By default it is 0, and the API holds the response for at most 60 seconds.
timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
request outlasts the time the API holds the response.
Returns:
The resource client for the default build of this Actor.
"""
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
)
response = self._http_client.call(
url=self._build_url('builds/default'),
method='GET',
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
)
result = response_to_dict(response)
@@ -932,7 +935,7 @@ async def start(
memory_mbytes: int | None = None,
run_timeout: timedelta | None = None,
force_permission_level: ActorPermissionLevel | None = None,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
webhooks: WebhooksList | None = None,
wait_for_resources: bool | timedelta = False,
timeout: Timeout = 'medium',
@@ -960,8 +963,8 @@ async def start(
in the default run configuration for the Actor.
force_permission_level: Override the Actor's permissions for this run. If not set, the Actor will run
with permissions configured in the Actor settings.
- wait_for_finish: The maximum number of seconds the server waits for the run to finish. By default,
- it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the run to finish, as a `timedelta` or a number of
+ seconds. By default it is 0, and the API holds the response for at most 60 seconds.
webhooks: Optional ad-hoc webhooks (https://docs.apify.com/webhooks/ad-hoc-webhooks) associated with
the Actor run which can be used to receive a notification, e.g. when the Actor finished or failed.
If you already have a webhook set up for the Actor or task, you do not have to add it again here.
@@ -986,6 +989,7 @@ async def start(
run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
run_input, wait_for_resources = prepare_resendable_body(run_input, wait_for_resources=wait_for_resources)
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
build=build,
maxItems=max_items,
@@ -993,7 +997,7 @@ async def start(
restartOnError=restart_on_error,
memory=memory_mbytes,
timeout=to_seconds(run_timeout, as_int=True),
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
forcePermissionLevel=force_permission_level,
webhooks=encode_webhooks_to_base64(webhooks),
)
@@ -1005,7 +1009,7 @@ async def start(
headers={'content-type': content_type},
data=run_input,
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
),
wait_for_resources=wait_for_resources,
)
@@ -1125,7 +1129,7 @@ async def build(
beta_packages: bool | None = None,
tag: str | None = None,
use_cache: bool | None = None,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
timeout: Timeout = 'medium',
) -> Build:
"""Build the Actor.
@@ -1141,27 +1145,28 @@ async def build(
use_cache: If true, the Actor's Docker container will be rebuilt using layer cache
(https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#leverage-build-cache).
This is to enable quick rebuild during development. By default, the cache is not used.
- wait_for_finish: The maximum number of seconds the server waits for the build to finish before returning.
- By default it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the build to finish, as a `timedelta` or a number
+ of seconds. By default it is 0, and the API holds the response for at most 60 seconds.
timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
request outlasts the time the API holds the response.
Returns:
The build object.
"""
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
version=version_number,
betaPackages=beta_packages,
tag=tag,
useCache=use_cache,
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
)
response = await self._http_client.call(
url=self._build_url('builds'),
method='POST',
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
)
result = response_to_dict(response)
@@ -1184,7 +1189,7 @@ def runs(self) -> RunCollectionClientAsync:
async def default_build(
self,
*,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
timeout: Timeout = 'short',
) -> BuildClientAsync:
"""Retrieve Actor's default build.
@@ -1192,23 +1197,24 @@ async def default_build(
https://docs.apify.com/api/v2/act-build-default-get
Args:
- wait_for_finish: The maximum number of seconds the server waits for the build to finish before returning.
- By default it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the build to finish, as a `timedelta` or a number
+ of seconds. By default it is 0, and the API holds the response for at most 60 seconds.
timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
request outlasts the time the API holds the response.
Returns:
The resource client for the default build of this Actor.
"""
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
)
response = await self._http_client.call(
url=self._build_url('builds/default'),
method='GET',
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
)
result = response_to_dict(response)
diff --git a/src/apify_client/_resource_clients/build.py b/src/apify_client/_resource_clients/build.py
index 59c1f3d6..e6acd5d5 100644
--- a/src/apify_client/_resource_clients/build.py
+++ b/src/apify_client/_resource_clients/build.py
@@ -6,6 +6,7 @@
from apify_client._models import Build, BuildResponse
from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
from apify_client._utils.http import response_to_dict
+from apify_client._utils.time import to_seconds
if TYPE_CHECKING:
from datetime import timedelta
@@ -35,18 +36,26 @@ def __init__(
**kwargs,
)
- def get(self, *, timeout: Timeout = 'short') -> Build | None:
+ def get(self, *, wait_for_finish: timedelta | None = None, timeout: Timeout = 'short') -> Build | None:
"""Return information about the Actor build.
https://docs.apify.com/api/v2#/reference/actor-builds/build-object/get-build
Args:
- timeout: Timeout for the API HTTP request.
+ wait_for_finish: The maximum duration to wait for the build to finish before returning the
+ (unfinished) build object. The API holds the response for at most 60 seconds, so a longer
+ duration has no additional effect.
+ timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
+ request outlasts the time the API holds the response.
Returns:
The retrieved Actor build data.
"""
- result = self._get(timeout=timeout)
+ wait_for_finish_secs = to_seconds(wait_for_finish, as_int=True)
+ result = self._get(
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
+ waitForFinish=wait_for_finish_secs,
+ )
if result is None:
return None
return BuildResponse.model_validate(result).data
@@ -155,18 +164,26 @@ def __init__(
**kwargs,
)
- async def get(self, *, timeout: Timeout = 'short') -> Build | None:
+ async def get(self, *, wait_for_finish: timedelta | None = None, timeout: Timeout = 'short') -> Build | None:
"""Return information about the Actor build.
https://docs.apify.com/api/v2#/reference/actor-builds/build-object/get-build
Args:
- timeout: Timeout for the API HTTP request.
+ wait_for_finish: The maximum duration to wait for the build to finish before returning the
+ (unfinished) build object. The API holds the response for at most 60 seconds, so a longer
+ duration has no additional effect.
+ timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
+ request outlasts the time the API holds the response.
Returns:
The retrieved Actor build data.
"""
- result = await self._get(timeout=timeout)
+ wait_for_finish_secs = to_seconds(wait_for_finish, as_int=True)
+ result = await self._get(
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
+ waitForFinish=wait_for_finish_secs,
+ )
if result is None:
return None
return BuildResponse.model_validate(result).data
diff --git a/src/apify_client/_resource_clients/run.py b/src/apify_client/_resource_clients/run.py
index 8c49d02c..d5eaf8df 100644
--- a/src/apify_client/_resource_clients/run.py
+++ b/src/apify_client/_resource_clients/run.py
@@ -59,18 +59,26 @@ def __init__(
**kwargs,
)
- def get(self, *, timeout: Timeout = 'short') -> Run | None:
+ def get(self, *, wait_for_finish: timedelta | None = None, timeout: Timeout = 'short') -> Run | None:
"""Return information about the Actor run.
https://docs.apify.com/api/v2#/reference/actor-runs/run-object/get-run
Args:
- timeout: Timeout for the API HTTP request.
+ wait_for_finish: The maximum duration to wait for the run to finish before returning the (unfinished)
+ run object. The API holds the response for at most 60 seconds, so a longer duration has no
+ additional effect.
+ timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
+ request outlasts the time the API holds the response.
Returns:
The retrieved Actor run data.
"""
- result = self._get(timeout=timeout)
+ wait_for_finish_secs = to_seconds(wait_for_finish, as_int=True)
+ result = self._get(
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
+ waitForFinish=wait_for_finish_secs,
+ )
if result is None:
return None
return RunResponse.model_validate(result).data
@@ -616,18 +624,26 @@ def __init__(
**kwargs,
)
- async def get(self, *, timeout: Timeout = 'short') -> Run | None:
+ async def get(self, *, wait_for_finish: timedelta | None = None, timeout: Timeout = 'short') -> Run | None:
"""Return information about the Actor run.
https://docs.apify.com/api/v2#/reference/actor-runs/run-object/get-run
Args:
- timeout: Timeout for the API HTTP request.
+ wait_for_finish: The maximum duration to wait for the run to finish before returning the (unfinished)
+ run object. The API holds the response for at most 60 seconds, so a longer duration has no
+ additional effect.
+ timeout: Timeout for the API HTTP request. A timeout tier is extended by `wait_for_finish`, so the
+ request outlasts the time the API holds the response.
Returns:
The retrieved Actor run data.
"""
- result = await self._get(timeout=timeout)
+ wait_for_finish_secs = to_seconds(wait_for_finish, as_int=True)
+ result = await self._get(
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
+ waitForFinish=wait_for_finish_secs,
+ )
if result is None:
return None
return RunResponse.model_validate(result).data
diff --git a/src/apify_client/_resource_clients/task.py b/src/apify_client/_resource_clients/task.py
index 162a0045..189688b8 100644
--- a/src/apify_client/_resource_clients/task.py
+++ b/src/apify_client/_resource_clients/task.py
@@ -17,7 +17,7 @@
from apify_client._utils.encoding import encode_webhooks_to_base64
from apify_client._utils.http import response_to_dict
from apify_client._utils.server_args import build_actor_standby
-from apify_client._utils.time import to_seconds
+from apify_client._utils.time import to_seconds, to_whole_seconds
from apify_client._utils.wait_for_resources import start_waiting_for_resources, start_waiting_for_resources_async
if TYPE_CHECKING:
@@ -249,7 +249,7 @@ def start(
memory_mbytes: int | None = None,
run_timeout: timedelta | None = None,
restart_on_error: bool | None = None,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
webhooks: WebhooksList | None = None,
wait_for_resources: bool | timedelta = False,
timeout: Timeout = 'medium',
@@ -271,8 +271,8 @@ def start(
in the task settings.
restart_on_error: If true, the Task run process will be restarted whenever it exits with
a non-zero status code.
- wait_for_finish: The maximum number of seconds the server waits for the run to finish. By default,
- it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the run to finish, as a `timedelta` or a number of
+ seconds. By default it is 0, and the API holds the response for at most 60 seconds.
webhooks: Optional ad-hoc webhooks (https://docs.apify.com/webhooks/ad-hoc-webhooks) associated with
the Actor run which can be used to receive a notification, e.g. when the Actor finished or failed.
If you already have a webhook set up for the Actor or task, you do not have to add it again here.
@@ -296,6 +296,7 @@ def start(
if task_input is not None and not isinstance(task_input, TaskInput):
task_input = TaskInput.model_validate(task_input)
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
build=build,
maxItems=max_items,
@@ -303,7 +304,7 @@ def start(
memory=memory_mbytes,
timeout=to_seconds(run_timeout, as_int=True),
restartOnError=restart_on_error,
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
webhooks=encode_webhooks_to_base64(webhooks),
)
@@ -314,7 +315,7 @@ def start(
headers={'content-type': 'application/json; charset=utf-8'},
json=task_input.model_dump() if task_input is not None else None,
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
),
wait_for_resources=wait_for_resources,
)
@@ -687,7 +688,7 @@ async def start(
memory_mbytes: int | None = None,
run_timeout: timedelta | None = None,
restart_on_error: bool | None = None,
- wait_for_finish: int | None = None,
+ wait_for_finish: timedelta | int | None = None,
webhooks: WebhooksList | None = None,
wait_for_resources: bool | timedelta = False,
timeout: Timeout = 'medium',
@@ -709,8 +710,8 @@ async def start(
in the task settings.
restart_on_error: If true, the Task run process will be restarted whenever it exits with
a non-zero status code.
- wait_for_finish: The maximum number of seconds the server waits for the run to finish. By default,
- it is 0, the maximum value is 60.
+ wait_for_finish: The maximum time the server waits for the run to finish, as a `timedelta` or a number of
+ seconds. By default it is 0, and the API holds the response for at most 60 seconds.
webhooks: Optional ad-hoc webhooks (https://docs.apify.com/webhooks/ad-hoc-webhooks) associated with
the Actor run which can be used to receive a notification, e.g. when the Actor finished or failed.
If you already have a webhook set up for the Actor or task, you do not have to add it again here.
@@ -734,6 +735,7 @@ async def start(
if task_input is not None and not isinstance(task_input, TaskInput):
task_input = TaskInput.model_validate(task_input)
+ wait_for_finish_secs = to_whole_seconds(wait_for_finish)
request_params = self._build_params(
build=build,
maxItems=max_items,
@@ -741,7 +743,7 @@ async def start(
memory=memory_mbytes,
timeout=to_seconds(run_timeout, as_int=True),
restartOnError=restart_on_error,
- waitForFinish=wait_for_finish,
+ waitForFinish=wait_for_finish_secs,
webhooks=encode_webhooks_to_base64(webhooks),
)
@@ -752,7 +754,7 @@ async def start(
headers={'content-type': 'application/json; charset=utf-8'},
json=task_input.model_dump() if task_input is not None else None,
params=request_params,
- timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish),
+ timeout=self._timeout_for_wait_for_finish(timeout, wait_for_finish_secs),
),
wait_for_resources=wait_for_resources,
)
diff --git a/src/apify_client/_utils/time.py b/src/apify_client/_utils/time.py
index 4e8c761b..da249cbb 100644
--- a/src/apify_client/_utils/time.py
+++ b/src/apify_client/_utils/time.py
@@ -1,9 +1,7 @@
from __future__ import annotations
-from typing import TYPE_CHECKING, Literal, overload
-
-if TYPE_CHECKING:
- from datetime import timedelta
+from datetime import timedelta
+from typing import Literal, overload
@overload
@@ -30,3 +28,10 @@ def to_seconds(td: timedelta | None, *, as_int: bool = False) -> float | int | N
return None
seconds = td.total_seconds()
return int(seconds) if as_int else seconds
+
+
+def to_whole_seconds(duration: timedelta | int | None) -> int | None:
+ """Convert a duration given as a `timedelta` or as a number of seconds to whole seconds."""
+ if isinstance(duration, timedelta):
+ return to_seconds(duration, as_int=True)
+ return duration
diff --git a/tests/unit/test_wait_for_finish_timeout.py b/tests/unit/test_wait_for_finish_timeout.py
index aaa2ce28..5218a402 100644
--- a/tests/unit/test_wait_for_finish_timeout.py
+++ b/tests/unit/test_wait_for_finish_timeout.py
@@ -8,7 +8,7 @@
from unittest.mock import Mock
import pytest
-from werkzeug import Response
+from werkzeug import Request, Response
from apify_client import ApifyClient, ApifyClientAsync
@@ -23,6 +23,8 @@
ACTOR_ID = 'test_actor_id'
TASK_ID = 'test_task_id'
+RUN_ID = 'test_run_id'
+BUILD_ID = 'test_build_id'
RUN_RESPONSE = {
'data': {
@@ -109,8 +111,30 @@ class CallSite:
),
id='task start',
),
+ pytest.param(
+ CallSite(
+ invoke=lambda client, **kwargs: client.run(RUN_ID).get(**kwargs),
+ method='GET',
+ path=f'/v2/actor-runs/{RUN_ID}',
+ response_body=RUN_RESPONSE,
+ tier_secs=5,
+ ),
+ id='run get',
+ ),
+ pytest.param(
+ CallSite(
+ invoke=lambda client, **kwargs: client.build(BUILD_ID).get(**kwargs),
+ method='GET',
+ path=f'/v2/actor-builds/{BUILD_ID}',
+ response_body=BUILD_RESPONSE,
+ tier_secs=5,
+ ),
+ id='build get',
+ ),
]
+SECONDS_CALL_SITES = [call_site for call_site in CALL_SITES if call_site.id not in {'run get', 'build get'}]
+
@pytest.fixture(params=[pytest.param(ApifyClient, id='sync'), pytest.param(ApifyClientAsync, id='async')])
def client(request: pytest.FixtureRequest, httpserver: HTTPServer) -> ApifyClient | ApifyClientAsync:
@@ -143,6 +167,28 @@ async def call_and_capture_timeout(
return send_request.call_args_list[0].kwargs['timeout']
+async def call_and_capture_wait_for_finish(
+ client: ApifyClient | ApifyClientAsync,
+ httpserver: HTTPServer,
+ call_site: CallSite,
+ wait_for_finish: timedelta | int | None,
+) -> str | None:
+ """Invoke the call site against a mocked endpoint and return the `waitForFinish` query parameter it sent."""
+ captured: list[Request] = []
+
+ def handler(request: Request) -> Response:
+ captured.append(request)
+ return Response(json.dumps(call_site.response_body), status=200, mimetype='application/json')
+
+ httpserver.expect_request(call_site.path, method=call_site.method).respond_with_handler(handler)
+
+ result = call_site.invoke(client, wait_for_finish=wait_for_finish)
+ if inspect.isawaitable(result):
+ await result
+
+ return captured[0].args.get('waitForFinish')
+
+
@pytest.mark.parametrize('call_site', CALL_SITES)
async def test_default_timeout_covers_wait_for_finish(
client: ApifyClient | ApifyClientAsync,
@@ -151,7 +197,9 @@ async def test_default_timeout_covers_wait_for_finish(
call_site: CallSite,
) -> None:
"""The default timeout tier is extended by `wait_for_finish`, so the request outlasts the API's hold."""
- timeout = await call_and_capture_timeout(client, monkeypatch, httpserver, call_site, wait_for_finish=60)
+ timeout = await call_and_capture_timeout(
+ client, monkeypatch, httpserver, call_site, wait_for_finish=timedelta(seconds=60)
+ )
assert timeout == call_site.tier_secs + 60
@@ -165,7 +213,7 @@ async def test_explicit_timeout_ignores_wait_for_finish(
) -> None:
"""An explicit `timedelta` timeout is used as given, whatever `wait_for_finish` is."""
timeout = await call_and_capture_timeout(
- client, monkeypatch, httpserver, call_site, wait_for_finish=60, timeout=timedelta(seconds=7)
+ client, monkeypatch, httpserver, call_site, wait_for_finish=timedelta(seconds=60), timeout=timedelta(seconds=7)
)
assert timeout == 7
@@ -194,3 +242,36 @@ def test_timeout_for_wait_for_finish(
actor_client = client.actor(ACTOR_ID)
assert actor_client._timeout_for_wait_for_finish(timeout, wait_for_finish) == expected
+
+
+@pytest.mark.parametrize(
+ ('wait_for_finish', 'expected'),
+ [
+ pytest.param(timedelta(seconds=45, milliseconds=500), '45', id='rounded down to whole seconds'),
+ pytest.param(None, None, id='omitted by default'),
+ ],
+)
+@pytest.mark.parametrize('call_site', CALL_SITES)
+async def test_sends_wait_for_finish_in_whole_seconds(
+ client: ApifyClient | ApifyClientAsync,
+ httpserver: HTTPServer,
+ call_site: CallSite,
+ wait_for_finish: timedelta | None,
+ expected: str | None,
+) -> None:
+ """A `timedelta` `wait_for_finish` is sent as `waitForFinish` in whole seconds, and an unset one is omitted."""
+ sent = await call_and_capture_wait_for_finish(client, httpserver, call_site, wait_for_finish)
+
+ assert sent == expected
+
+
+@pytest.mark.parametrize('call_site', SECONDS_CALL_SITES)
+async def test_start_and_build_accept_wait_for_finish_in_seconds(
+ client: ApifyClient | ApifyClientAsync,
+ httpserver: HTTPServer,
+ call_site: CallSite,
+) -> None:
+ """The `start` and `build` methods also accept `wait_for_finish` as a number of seconds."""
+ sent = await call_and_capture_wait_for_finish(client, httpserver, call_site, 45)
+
+ assert sent == '45'