fix: treat empty-string env vars as unset in Configuration

[vdusek]

The bug

The Apify platform sometimes exports an env var as an empty string instead of leaving it unset. Configuration handled that per field, with BeforeValidator(_default_if_empty(...)) on four fields — so every other field whose type cannot parse '' raised a raw pydantic ValidationError while Configuration was being built inside Actor.init(), before logging was configured.

Verified crashing on '': ACTOR_STORAGES_JSON, ACTOR_STARTED_AT, APIFY_DEDICATED_CPUS, ACTOR_TEST_PAY_PER_EVENT, APIFY_IS_AT_HOME, ACTOR_STANDBY_URL, APIFY_METAMORPH_AFTER_SLEEP_MILLIS, APIFY_PROXY_PORT, ACTOR_WEB_SERVER_PORT, APIFY_CHARGED_ACTOR_EVENT_COUNTS, plus inherited Crawlee fields such as CRAWLEE_PURGE_ON_START and CRAWLEE_MEMORY_MBYTES.

The fix

Drop the per-field annotations and the _default_if_empty helper, and set env_ignore_empty=True in model_config instead. The empty value is then skipped in the env settings source, so the declared field default applies and no field can be forgotten.

Skipping in the env source matters, rather than normalizing after the sources are merged: 28 of 55 fields accept several env names via AliasChoices, and only the source-level skip lets the next name be tried. With ACTOR_WEB_SERVER_PORT='' beside APIFY_CONTAINER_PORT=9999, the port resolves to 9999; discarding the merged value would silently yield the 4321 default. It also keeps the rule scoped to the environment — an '' passed to the constructor is still taken as given.

pydantic-settings moves from a transitive dependency (via crawlee) to a declared one, since _configuration.py now imports SettingsConfigDict directly.

Observable changes

'' now means "not provided" for every field, not just the four. APIFY_TOKEN='' yields None instead of '', ACTOR_INPUT_KEY='' yields 'INPUT' instead of an unusable '', and ACTOR_BUILD_TAGS='' yields None instead of []. Nothing in the SDK or Crawlee distinguishes '' from None on these fields. actor_task_id's description is updated accordingly.

Tests

The empty-string regression test grows from 4 to 16 cases, including a Crawlee-inherited field. Added alongside it: a guard that a populated typed env var is still parsed (so the rule cannot become greedy), a guard that an empty value falls through to a populated legacy alias, and a guard that a constructor-supplied '' is kept. 13 of these fail on master.

✍️ Drafted by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.89%. Comparing base (cad8d7e) to head (9c0b9b3).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1080      +/-   ##
==========================================
+ Coverage   91.83%   91.89%   +0.05%     
==========================================
  Files          51       51              
  Lines        3235     3232       -3     
==========================================
- Hits         2971     2970       -1     
+ Misses        264      262       -2     

Flag	Coverage Δ
e2e	35.27% <100.00%> (-0.03%)	⬇️
integration	56.99% <100.00%> (-0.04%)	⬇️
unit	83.26% <100.00%> (+0.04%)	⬆️

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]

closing as duplicate of #965