refactor!: Remove wait_for_finish from Actor.start

The argument contradicted the purpose of Actor.start, which only starts the run without waiting for it to finish, and the JS SDK does not expose it either. To wait for a run to finish, use Actor.call. The raw waitForFinish server param is still reachable via the underlying client.

Author: vdusek

docs/04_upgrading/upgrading_to_v4.md

@@ -69,6 +69,26 @@ 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.
 
+### `wait_for_finish` argument of `Actor.start`
+
+The `wait_for_finish` argument of `Actor.start()` has been removed. It contradicted the purpose of `Actor.start()`, which only starts the run without waiting for it to finish. The JS SDK does not expose it on `Actor.start()` either. To wait for a run to finish, use `Actor.call()`.
+
+```python
+from datetime import timedelta
+
+# Before (v3)
+run = await Actor.start('my-actor-id', wait_for_finish=60)
+
+# After (v4)
+run = await Actor.call('my-actor-id', wait=timedelta(seconds=60))
+```
+
+If you need the raw server-side `waitForFinish` behavior (return the run after the server waits up to N seconds, without polling to completion), call the underlying client directly:
+
+```python
+run = await Actor.apify_client.actor('my-actor-id').start(wait_for_finish=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,12 +889,12 @@ 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,
     ) -> Run:
         """Run an Actor on the Apify platform.
 
-        Unlike `Actor.call`, this method just starts the run without waiting for finish.
+        Unlike `Actor.call`, this method just starts the run without waiting for finish. To wait for the run to
+        finish, use `Actor.call` instead.
 
         Args:
             actor_id: The ID of the Actor to be run.
@@ -913,8 +913,6 @@ 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.
@@ -943,7 +941,6 @@ async def start(
             memory_mbytes=memory_mbytes,
             run_timeout=actor_start_timeout,
             force_permission_level=force_permission_level,
-            wait_for_finish=wait_for_finish,
             webhooks=to_client_representations(webhooks),
         )
 
@@ -1026,8 +1023,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 +1100,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.