refactor!: Rename wait_for_finish to wait in Actor.start

Unify the argument with Actor.call and Actor.call_task, which use wait: timedelta
for the same concept. The value is now a timedelta instead of an int in seconds.

Author: vdusek

docs/04_upgrading/upgrading_to_v4.md

@@ -69,6 +69,20 @@ The deprecated `latest_sdk_version`, `log_format`, and `standby_port` fields hav
 - In place of `standby_port`, use `web_server_port`.
 - `latest_sdk_version` and `log_format` don't have replacement. SDK version checking isn't supported for the Python SDK and the log format should be adjusted in code instead.
 
+## `Actor.start` — `wait_for_finish` is now `wait`
+
+The `wait_for_finish: int` argument of `Actor.start()` has been renamed to `wait: timedelta`, matching `Actor.call()` and `Actor.call_task()`. The behavior is unchanged: the server still waits at most the given time (capped at 300 seconds) before returning the run info.
+
+```python
+from datetime import timedelta
+
+# Before (v3)
+run = await Actor.start('my-actor-id', wait_for_finish=60)
+
+# After (v4)
+run = await Actor.start('my-actor-id', wait=timedelta(seconds=60))
+```
+
 ## Built on `apify-client` v3
 
 The SDK is now built on [`apify-client`](https://docs.apify.com/api/client/python) v3 and no longer depends on `apify-shared`. The sections below cover the user-visible consequences; see the client's [Upgrading to v3](https://docs.apify.com/api/client/python/docs/upgrading/upgrading-to-v3) guide for the full list of changes in the client itself.

src/apify/_actor.py

@@ -889,8 +889,8 @@ async def start(
         memory_mbytes: int | None = None,
         timeout: timedelta | None | Literal['inherit'] = None,
         force_permission_level: ActorPermissionLevel | None = None,
-        wait_for_finish: int | None = None,
         webhooks: list[Webhook] | None = None,
+        wait: timedelta | None = None,
     ) -> Run:
         """Run an Actor on the Apify platform.
 
@@ -913,11 +913,11 @@ async def start(
                 to the time remaining from this Actor timeout.
             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 300.
             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.
+            wait: The maximum time the server waits for the run to finish. By default, it does not wait at all.
+                The maximum value is 300 seconds.
 
         Returns:
             Info about the started Actor run
@@ -943,7 +943,7 @@ async def start(
             memory_mbytes=memory_mbytes,
             run_timeout=actor_start_timeout,
             force_permission_level=force_permission_level,
-            wait_for_finish=wait_for_finish,
+            wait_for_finish=int(wait.total_seconds()) if wait is not None else None,
             webhooks=to_client_representations(webhooks),
         )
 
@@ -1026,8 +1026,7 @@ async def call(
             webhooks: Optional webhooks (https://docs.apify.com/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, you do not have to add it again here.
-            wait: The maximum number of seconds the server waits for the run to finish. If not provided,
-                waits indefinitely.
+            wait: The maximum time the server waits for the run to finish. If not provided, waits indefinitely.
             logger: Logger used to redirect logs from the Actor run. Using "default" literal means that a predefined
                 default logger will be used. Setting `None` will disable any log propagation. Passing custom logger
                 will redirect logs to the provided logger.
@@ -1104,8 +1103,7 @@ async def call_task(
             webhooks: Optional webhooks (https://docs.apify.com/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, you do not have to add it again here.
-            wait: The maximum number of seconds the server waits for the run to finish. If not provided, waits
-                indefinitely.
+            wait: The maximum time the server waits for the run to finish. If not provided, waits indefinitely.
 
         Returns:
             Info about the started Actor run.