[DaveHanns]

Summary

Adds an actor_path argument to ActorVersionCollectionClient.create and ActorVersionClient.update, sync and async. The client sends it as actorPath: the Actor's directory inside the uploaded source of a SOURCE_FILES or TARBALL version, such as actors/my-actor. With it, a monorepo Actor can be built from an upload of the whole repository.

Closes #1186

Changes

• actor_path: str | None = None sits after github_gist_url in all four methods. It's left out of the request when not passed.
• The argument goes into the actor_path field of the generated CreateVersionRequest and UpdateVersionRequest models, like the other source-location arguments. The returned version exposes it as Version.actor_path.
• The docstrings list the path rules the API enforces, such as the length of 1 to 255 characters, and say the argument works only for SOURCE_FILES and TARBALL versions.
• The update docstring says how the stored path is removed. An update that sends source_type, source_files, or tarball_url without actor_path removes it, and actor_path=None alone keeps it.

Tests

• New unit tests in tests/unit/test_actor_version_fields.py capture the request body. They check that actorPath is sent on create and update and that the returned Version.actor_path reads it back. They also check that actorPath is absent when the argument is not passed. Each test runs sync and async on both HTTP transports.
• A new integration test in tests/integration/test_actor_version.py covers the round trip on the API. It creates a version with a path, checks that a build_tag update keeps it, and checks that a new upload and a source_type update each remove it.
• With models generated locally from the API specification plus docs(api): describe actorPath on multi-file and zip Actor versions apify-docs#3084, uv run poe check-code passes: lint, type check, docstring check, and 2,462 unit tests (1 skipped, as on master). The integration suite wasn't run locally, since it calls the real API.

Notes for reviewers

• Merge only after all three of these happen:
  • apify/apify-core#31479 is deployed, or the API rejects the field.
  • docs(api): describe actorPath on multi-file and zip Actor versions apify-docs#3084 is merged and published, so the published specification describes actorPath.
  • The nightly regenerate-models PR has landed on master with the new actor_path fields. Then merge master into this branch.
• Until the regenerated models are on master, CI fails on purpose. With the current models, 8 of the 16 new unit test cases fail because the client sends actor_path instead of actorPath, and the type check reports that Version has no actor_path.
• Merging publishes a beta release and a changelog entry right away.
• There's no separate way to send null. In this client, None means "not passed", and every update method drops None from the payload. A new upload without actor_path already removes the path, and so does an update with only the current source_type. Explicit null in update() methods is tracked in Let update() methods clear a field by sending null #1135.
• There's no new page in docs/02_concepts/. Those pages explain how the client works, such as retries and pagination, and a new argument on two methods doesn't fit one. The docstrings document the argument, and they feed the API reference.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.66%. Comparing base (cbed860) to head (cec4a61).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1187   +/-   ##
=======================================
  Coverage   95.66%   95.66%           
=======================================
  Files          61       61           
  Lines        6461     6461           
=======================================
  Hits         6181     6181           
  Misses        280      280           

Flag	Coverage Δ
integration	91.05% <ø> (-0.02%)	⬇️
unit	90.54% <ø> (+0.18%)	⬆️

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.

[DaveHanns]

Don't merge yet. This PR depends on:

1. apify/apify-core#31479, merged and deployed.
2. docs(api): describe actorPath on multi-file and zip Actor versions apify-docs#3084, merged and published to docs.apify.com.
3. The nightly chore: Regenerate models from the published OpenAPI spec PR that picks up the docs change, merged to master.

Until then, CI fails on purpose: the code passes actor_path to the regenerated request models, and the integration test needs the deployed API. After step 3, merge master into this branch, and CI should pass.

[vdusek]

I'll convert this to draft, please make it ready for a review once this has green CI (requirements in other repos are merged).