Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/02_concepts/11_timeouts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <ApiLink to="class/ActorClient#start">`ActorClient.start`</ApiLink> and <ApiLink to="class/ActorClient#build">`ActorClient.build`</ApiLink>, 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 <ApiLink to="class/ActorClient#start">`ActorClient.start`</ApiLink>, <ApiLink to="class/ActorClient#build">`ActorClient.build`</ApiLink>, <ApiLink to="class/RunClient#get">`RunClient.get`</ApiLink>, and <ApiLink to="class/BuildClient#get">`BuildClient.get`</ApiLink>, 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

Expand Down
8 changes: 4 additions & 4 deletions src/apify_client/_resource_clients/_resource_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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)
Expand Down Expand Up @@ -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`
Expand All @@ -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)
Expand Down
68 changes: 37 additions & 31 deletions src/apify_client/_resource_clients/actor.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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.
Expand All @@ -342,14 +342,15 @@ 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,
maxTotalChargeUsd=max_total_charge_usd,
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),
)
Expand All @@ -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,
)
Expand Down Expand Up @@ -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.
Expand All @@ -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)
Expand All @@ -539,31 +541,32 @@ 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.

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)

Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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.
Expand All @@ -986,14 +989,15 @@ 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,
maxTotalChargeUsd=max_total_charge_usd,
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),
)
Expand All @@ -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,
)
Expand Down Expand Up @@ -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.
Expand All @@ -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)
Expand All @@ -1184,31 +1189,32 @@ 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.

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)

Expand Down
29 changes: 23 additions & 6 deletions src/apify_client/_resource_clients/build.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading