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'