From fcec1cf647ec27e656c43f50c73a1d6154da8122 Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Fri, 13 Nov 2026 11:38:42 +0100 Subject: [PATCH] fix: mark named child runs as experimental --- src/apify/_actor.py | 38 ++++++++++++++-- tests/unit/actor/test_actor_child_runs.py | 53 ++++++++++++++++++++++- 2 files changed, 86 insertions(+), 5 deletions(-) diff --git a/src/apify/_actor.py b/src/apify/_actor.py index bb17a6e7..605c21d8 100644 --- a/src/apify/_actor.py +++ b/src/apify/_actor.py @@ -76,6 +76,16 @@ _ensure_context = ensure_context('_active') +def _warn_child_runs_experimental() -> None: + warnings.warn( + 'Named child runs (`run_name`, `abort_with_parent` and `Actor.child_runs`) are experimental. Their behavior ' + 'and interface may change in future versions.', + UserWarning, + # This helper, the SDK method, and its `ensure_context` wrapper sit between the warning and the caller. + stacklevel=4, + ) + + def _warn_max_items_deprecated() -> None: warnings.warn( '`max_items` is deprecated and will be removed in version 5.0.0. It works only with legacy pay-per-result ' @@ -445,7 +455,11 @@ def child_runs(self) -> dict[str, RunClientAsync]: A run started or reattached with a custom `token` since the last migration or resurrection of this Actor run uses that token. Any other run uses the default client. + + Warning: + This is an experimental feature. The behavior and interface may change in future versions. """ + _warn_child_runs_experimental() return self._child_run_registry.run_clients(self.apify_client) @cached_property @@ -1103,7 +1117,8 @@ async def start( to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or - with a different input raises a `ValueError`. + with a different input raises a `ValueError`. Named child runs are experimental, so their behavior + and interface may change in future versions. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and @@ -1116,6 +1131,9 @@ async def start( if abort_with_parent and run_name is None: raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') + if run_name is not None: + _warn_child_runs_experimental() + if max_items is not None: _warn_max_items_deprecated() @@ -1304,7 +1322,8 @@ async def call( to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or - with a different input raises a `ValueError`. + with a different input raises a `ValueError`. Named child runs are experimental, so their behavior + and interface may change in future versions. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and @@ -1317,6 +1336,9 @@ async def call( if abort_with_parent and run_name is None: raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') + if run_name is not None: + _warn_child_runs_experimental() + if max_items is not None: _warn_max_items_deprecated() @@ -1491,7 +1513,8 @@ async def start_task( to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or - with a different input raises a `ValueError`. + with a different input raises a `ValueError`. Named child runs are experimental, so their behavior + and interface may change in future versions. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and @@ -1504,6 +1527,9 @@ async def start_task( if abort_with_parent and run_name is None: raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') + if run_name is not None: + _warn_child_runs_experimental() + if max_items is not None: _warn_max_items_deprecated() @@ -1591,7 +1617,8 @@ async def call_task( to the recorded run. A `SUCCEEDED` run is returned as is, an `ABORTED` or `TIMED-OUT` one is resurrected, and a new run is started only when nothing is recorded under the name, or the recorded run `FAILED` or no longer exists. Using `run_name` to attach to a run of a different Actor, task or - with a different input raises a `ValueError`. + with a different input raises a `ValueError`. Named child runs are experimental, so their behavior + and interface may change in future versions. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and @@ -1604,6 +1631,9 @@ async def call_task( if abort_with_parent and run_name is None: raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') + if run_name is not None: + _warn_child_runs_experimental() + if max_items is not None: _warn_max_items_deprecated() diff --git a/tests/unit/actor/test_actor_child_runs.py b/tests/unit/actor/test_actor_child_runs.py index e4bd5d2c..48fe1842 100644 --- a/tests/unit/actor/test_actor_child_runs.py +++ b/tests/unit/actor/test_actor_child_runs.py @@ -1,6 +1,7 @@ from __future__ import annotations import asyncio +import warnings from datetime import timedelta from typing import TYPE_CHECKING, Any from unittest.mock import AsyncMock, MagicMock, Mock @@ -24,6 +25,9 @@ from apify.storages import KeyValueStore +pytestmark = pytest.mark.filterwarnings('ignore:Named child runs:UserWarning') + + def make_run(run_id: str, status: str) -> Run: return Run.model_validate( { @@ -493,7 +497,8 @@ async def test_named_start_forwards_max_items_to_resurrect( with pytest.warns(FutureWarning, match='max_items') as warnings: await Actor.start('some-actor', run_name='scrape-eu', max_items=10) - assert [warning.filename for warning in warnings] == [__file__] + future_warnings = [warning for warning in warnings if warning.category is FutureWarning] + assert [warning.filename for warning in future_warnings] == [__file__] [(_, kwargs)] = apify_client_async_patcher.calls['run']['resurrect'] assert kwargs['max_items'] == 10 @@ -1171,3 +1176,49 @@ async def test_removing_all_aborting_listeners_keeps_aborting_child_runs( await apify_event_manager.wait_for_all_listeners_to_complete() assert len(apify_client_async_patcher.calls['run']['abort']) == 1 + + +@pytest.mark.parametrize( + 'method_name', + [ + pytest.param('start', id='start'), + pytest.param('call', id='call'), + pytest.param('start_task', id='start task'), + pytest.param('call_task', id='call task'), + ], +) +async def test_named_run_warns_experimental( + apify_client_async_patcher: ApifyClientAsyncPatcher, method_name: str +) -> None: + """A run started with `run_name` warns that named child runs are experimental, pointing at the caller.""" + apify_client_async_patcher.patch('actor', 'start', return_value=make_run('new-run', 'READY')) + apify_client_async_patcher.patch('task', 'start', return_value=make_run('new-run', 'READY')) + apify_client_async_patcher.patch('run', 'wait_for_finish', return_value=make_run('new-run', 'SUCCEEDED')) + + async with Actor: + method = getattr(Actor, method_name) + target = 'some-task' if method_name.endswith('_task') else 'some-actor' + kwargs = {'logger': None} if method_name == 'call' else {} + with pytest.warns(UserWarning, match='experimental') as warnings: + await method(target, run_name='scrape-eu', **kwargs) + + assert [warning.filename for warning in warnings] == [__file__] + + +async def test_unnamed_start_does_not_warn_experimental(apify_client_async_patcher: ApifyClientAsyncPatcher) -> None: + """A run started without `run_name` emits no experimental warning.""" + apify_client_async_patcher.patch('actor', 'start', return_value=make_run('new-run', 'READY')) + + async with Actor: + with warnings.catch_warnings(): + warnings.simplefilter('error') + await Actor.start('some-actor') + + +async def test_child_runs_warns_experimental() -> None: + """Accessing `Actor.child_runs` warns that named child runs are experimental, pointing at the caller.""" + async with Actor: + with pytest.warns(UserWarning, match='experimental') as warnings: + _ = Actor.child_runs + + assert [warning.filename for warning in warnings] == [__file__]