Skip to content

docs: describe how to compose Actors - #1160

Draft
vdusek wants to merge 2 commits into
feat/child-run-budgetfrom
docs/child-runs
Draft

vdusek wants to merge 2 commits into
feat/child-run-budgetfrom
docs/child-runs

Conversation

@vdusek

@vdusek vdusek commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #1155.

Docs for the whole child runs stack, moved out of #1149, #1151, #1153, #1154 and #1155 so those PRs only carry code and tests. Adds sections on named child runs, the Actor.child_runs property, aborting child runs with the parent, the concurrency limit and the shared charge budget to the "Interacting with other Actors" guide, each with a code sample.

✍️ Drafted by Claude Code

@vdusek vdusek added adhoc Ad-hoc unplanned task added during the sprint. t-tooling Issues with this label are in the ownership of the tooling team. labels Oct 6, 2026
@vdusek vdusek self-assigned this Oct 6, 2026
@codecov

codecov Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.35%. Comparing base (befffb2) to head (8e7ec8c).

Additional details and impacted files
@@                  Coverage Diff                   @@
##           feat/child-run-budget    #1160   +/-   ##
======================================================
  Coverage                  93.35%   93.35%           
======================================================
  Files                         54       54           
  Lines                       3896     3896           
======================================================
  Hits                        3637     3637           
  Misses                       259      259           
Flag Coverage Δ
e2e ?
integration 50.43% <ø> (ø)
unit 90.27% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@vdusek
vdusek added this pull request to stack #1152 October 6, 2026 13:22
@vdusek vdusek changed the title docs: document named child runs docs: describe how to compose Actors Oct 6, 2026
vdusek added a commit that referenced this pull request Oct 9, 2026
`Actor.child_runs` is a sync property that maps each run name to a
`RunClientAsync` for the current run under that name. It has the same
shape as `Actor.childRuns` in the JS SDK (apify/apify-sdk-js#759). The
client covers the run and its storages:

```python
run = await Actor.child_runs['scrape-eu'].wait_for_finish()
```

The SDK reads the registry from the default key-value store when the
Actor initializes, so runs recorded before a migration or resurrection
are included and reading the property makes no API calls. That adds one
record read to every init. A malformed record fails the init and leaves
the Actor uninitialized. Runs started without a `run_name` aren't
tracked. Runs that were replaced under a name stay in the `history` of
the `__ACTOR_CHILD_RUNS` record and aren't exposed.

A run started or reattached with a custom `token` gets a client with
that token. A run recorded before a migration and not reattached since
gets the default client, because the token isn't stored.

It also fixes a duplicate `max_items` deprecation warning from #1149: a
named start that resurrects its recorded run no longer warns a second
time from inside the SDK.

Docs are in #1160.

Closes: #1129

*✍️ Drafted by Claude Code*
vdusek added a commit that referenced this pull request Oct 15, 2026
Follow-up to #1149 and #1151 that aligns named child runs with the final
version of apify/apify-sdk-js#759.

Changes:

- A different Actor, task or input under an existing `run_name` raises a
`ValueError` only when the recorded run would be reused (reattached,
returned as `SUCCEEDED`, or resurrected). When the recorded run `FAILED`
or is gone, a new run starts with the new request, the old run moves to
`history`, and the record takes the new checksum ([agreed
here](apify/apify-sdk-js#759 (comment))).
- The client of a named run is stored only after the run is started or
reused.
- The `run_name` docstrings describe the new rule.

No action on [B4nan's
comment](apify/apify-sdk-js#759 (comment))
about loading the child-run record lazily instead of in Actor init. JS
kept the load in `init()`, because the synchronous `Actor.childRuns`
getter needs the records, and Python already loads them the same way in
`__aenter__`.

The docs in #1160 still say a name is bound to its first input. That
will be fixed there.

*✍️ Drafted by Claude Code*

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

adhoc Ad-hoc unplanned task added during the sprint. t-tooling Issues with this label are in the ownership of the tooling team.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants