From 6f74daf523ac7b20f2d30aa99be91bda0aeccdf3 Mon Sep 17 00:00:00 2001 From: dheerajitbhu <73860752+dheerajitbhu@users.noreply.github.com> Date: Wed, 11 Nov 2026 11:05:26 -0800 Subject: [PATCH 1/3] feat: add wait_for_finish to RunClient.get and BuildClient.get Closes: #1176 --- docs/02_concepts/11_timeouts.mdx | 2 +- .../_resource_clients/_resource_client.py | 8 +- src/apify_client/_resource_clients/build.py | 29 ++++-- src/apify_client/_resource_clients/run.py | 28 ++++-- tests/unit/test_wait_for_finish_timeout.py | 95 ++++++++++++++++++- 5 files changed, 144 insertions(+), 18 deletions(-) diff --git a/docs/02_concepts/11_timeouts.mdx b/docs/02_concepts/11_timeouts.mdx index 5adccdf40..dcbddd735 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. 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 d9398f7af..4ade4bf6f 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/build.py b/src/apify_client/_resource_clients/build.py index 59c1f3d6b..e6acd5d50 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 8c49d02c2..d5eaf8dfa 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/tests/unit/test_wait_for_finish_timeout.py b/tests/unit/test_wait_for_finish_timeout.py index aaa2ce281..608c1a940 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': { @@ -57,6 +59,14 @@ } +def _as_wait_for_finish_timedelta(kwargs: dict[str, Any]) -> dict[str, Any]: + """Convert the `wait_for_finish` seconds used by the other call sites to the `timedelta` `get` expects.""" + wait_for_finish = kwargs.get('wait_for_finish') + if wait_for_finish is None: + return kwargs + return {**kwargs, 'wait_for_finish': timedelta(seconds=wait_for_finish)} + + @dataclass(frozen=True) class CallSite: """A client method that sends `waitForFinish`, with the endpoint it calls and its default timeout tier.""" @@ -109,6 +119,41 @@ class CallSite: ), id='task start', ), + pytest.param( + CallSite( + invoke=lambda client, **kwargs: client.run(RUN_ID).get(**_as_wait_for_finish_timedelta(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(**_as_wait_for_finish_timedelta(kwargs)), + method='GET', + path=f'/v2/actor-builds/{BUILD_ID}', + response_body=BUILD_RESPONSE, + tier_secs=5, + ), + id='build get', + ), +] + +GET_CALL_SITES = [ + pytest.param( + lambda client, **kwargs: client.run(RUN_ID).get(**kwargs), + f'/v2/actor-runs/{RUN_ID}', + RUN_RESPONSE, + id='run get', + ), + pytest.param( + lambda client, **kwargs: client.build(BUILD_ID).get(**kwargs), + f'/v2/actor-builds/{BUILD_ID}', + BUILD_RESPONSE, + id='build get', + ), ] @@ -194,3 +239,51 @@ 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(('invoke', 'path', 'response_body'), GET_CALL_SITES) +async def test_get_sends_wait_for_finish_as_whole_seconds( + client: ApifyClient | ApifyClientAsync, + httpserver: HTTPServer, + invoke: Callable[..., Any], + path: str, + response_body: dict, +) -> None: + """`get` sends `wait_for_finish` as the `waitForFinish` query parameter, rounded down to whole seconds.""" + captured: list[Request] = [] + + def handler(request: Request) -> Response: + captured.append(request) + return Response(json.dumps(response_body), status=200, mimetype='application/json') + + httpserver.expect_request(path, method='GET').respond_with_handler(handler) + + result = invoke(client, wait_for_finish=timedelta(seconds=45, milliseconds=500)) + if inspect.isawaitable(result): + await result + + assert captured[0].args.get('waitForFinish') == '45' + + +@pytest.mark.parametrize(('invoke', 'path', 'response_body'), GET_CALL_SITES) +async def test_get_omits_wait_for_finish_by_default( + client: ApifyClient | ApifyClientAsync, + httpserver: HTTPServer, + invoke: Callable[..., Any], + path: str, + response_body: dict, +) -> None: + """`get` omits the `waitForFinish` query parameter when `wait_for_finish` is not given.""" + captured: list[Request] = [] + + def handler(request: Request) -> Response: + captured.append(request) + return Response(json.dumps(response_body), status=200, mimetype='application/json') + + httpserver.expect_request(path, method='GET').respond_with_handler(handler) + + result = invoke(client) + if inspect.isawaitable(result): + await result + + assert 'waitForFinish' not in captured[0].args From f8049d9b0952415163626ea0f76dc20d4c72d457 Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Mon, 16 Nov 2026 09:06:36 +0100 Subject: [PATCH 2/3] feat: accept a `timedelta` for `wait_for_finish` in `start()` and `build()` --- src/apify_client/_resource_clients/actor.py | 68 ++++++------ src/apify_client/_resource_clients/task.py | 24 +++-- src/apify_client/_utils/time.py | 13 ++- tests/unit/test_wait_for_finish_timeout.py | 112 +++++++++----------- 4 files changed, 109 insertions(+), 108 deletions(-) diff --git a/src/apify_client/_resource_clients/actor.py b/src/apify_client/_resource_clients/actor.py index 3a3d183df..aa133d6d7 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/task.py b/src/apify_client/_resource_clients/task.py index 162a0045a..189688b8b 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 4e8c761bc..da249cbbc 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 608c1a940..5218a4029 100644 --- a/tests/unit/test_wait_for_finish_timeout.py +++ b/tests/unit/test_wait_for_finish_timeout.py @@ -59,14 +59,6 @@ } -def _as_wait_for_finish_timedelta(kwargs: dict[str, Any]) -> dict[str, Any]: - """Convert the `wait_for_finish` seconds used by the other call sites to the `timedelta` `get` expects.""" - wait_for_finish = kwargs.get('wait_for_finish') - if wait_for_finish is None: - return kwargs - return {**kwargs, 'wait_for_finish': timedelta(seconds=wait_for_finish)} - - @dataclass(frozen=True) class CallSite: """A client method that sends `waitForFinish`, with the endpoint it calls and its default timeout tier.""" @@ -121,7 +113,7 @@ class CallSite: ), pytest.param( CallSite( - invoke=lambda client, **kwargs: client.run(RUN_ID).get(**_as_wait_for_finish_timedelta(kwargs)), + invoke=lambda client, **kwargs: client.run(RUN_ID).get(**kwargs), method='GET', path=f'/v2/actor-runs/{RUN_ID}', response_body=RUN_RESPONSE, @@ -131,7 +123,7 @@ class CallSite: ), pytest.param( CallSite( - invoke=lambda client, **kwargs: client.build(BUILD_ID).get(**_as_wait_for_finish_timedelta(kwargs)), + invoke=lambda client, **kwargs: client.build(BUILD_ID).get(**kwargs), method='GET', path=f'/v2/actor-builds/{BUILD_ID}', response_body=BUILD_RESPONSE, @@ -141,20 +133,7 @@ class CallSite: ), ] -GET_CALL_SITES = [ - pytest.param( - lambda client, **kwargs: client.run(RUN_ID).get(**kwargs), - f'/v2/actor-runs/{RUN_ID}', - RUN_RESPONSE, - id='run get', - ), - pytest.param( - lambda client, **kwargs: client.build(BUILD_ID).get(**kwargs), - f'/v2/actor-builds/{BUILD_ID}', - BUILD_RESPONSE, - 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')]) @@ -188,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, @@ -196,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 @@ -210,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 @@ -241,49 +244,34 @@ def test_timeout_for_wait_for_finish( assert actor_client._timeout_for_wait_for_finish(timeout, wait_for_finish) == expected -@pytest.mark.parametrize(('invoke', 'path', 'response_body'), GET_CALL_SITES) -async def test_get_sends_wait_for_finish_as_whole_seconds( +@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, - invoke: Callable[..., Any], - path: str, - response_body: dict, + call_site: CallSite, + wait_for_finish: timedelta | None, + expected: str | None, ) -> None: - """`get` sends `wait_for_finish` as the `waitForFinish` query parameter, rounded down to whole seconds.""" - captured: list[Request] = [] - - def handler(request: Request) -> Response: - captured.append(request) - return Response(json.dumps(response_body), status=200, mimetype='application/json') - - httpserver.expect_request(path, method='GET').respond_with_handler(handler) + """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) - result = invoke(client, wait_for_finish=timedelta(seconds=45, milliseconds=500)) - if inspect.isawaitable(result): - await result - - assert captured[0].args.get('waitForFinish') == '45' + assert sent == expected -@pytest.mark.parametrize(('invoke', 'path', 'response_body'), GET_CALL_SITES) -async def test_get_omits_wait_for_finish_by_default( +@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, - invoke: Callable[..., Any], - path: str, - response_body: dict, + call_site: CallSite, ) -> None: - """`get` omits the `waitForFinish` query parameter when `wait_for_finish` is not given.""" - captured: list[Request] = [] - - def handler(request: Request) -> Response: - captured.append(request) - return Response(json.dumps(response_body), status=200, mimetype='application/json') - - httpserver.expect_request(path, method='GET').respond_with_handler(handler) - - result = invoke(client) - if inspect.isawaitable(result): - await result + """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 'waitForFinish' not in captured[0].args + assert sent == '45' From 541f43f37f343a214d26ff0903f8d18fb02025f1 Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Mon, 16 Nov 2026 09:06:38 +0100 Subject: [PATCH 3/3] docs: describe the accepted `wait_for_finish` types --- docs/02_concepts/11_timeouts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/02_concepts/11_timeouts.mdx b/docs/02_concepts/11_timeouts.mdx index dcbddd735..c7080a4dd 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`, `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. 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