Skip to content
Merged
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
38 changes: 34 additions & 4 deletions src/apify/_actor.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 '
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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()

Expand Down Expand Up @@ -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
Expand All @@ -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()

Expand Down Expand Up @@ -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
Expand All @@ -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()

Expand Down Expand Up @@ -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
Expand All @@ -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()

Expand Down
53 changes: 52 additions & 1 deletion tests/unit/actor/test_actor_child_runs.py
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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(
{
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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__]
Loading