fix(deps): exclude argcomplete 3.7.1 on Python < 3.10, gate releases on tests

[jim-fal]

Problem

argcomplete 3.7.1, released 2026-08-04 15:03 UTC, annotates

choices: Final[Mapping[str, str | bytes]]

in a class body (completers.py:35) while still declaring requires-python >=3.8. PEP 604 X | Y at runtime needs 3.10, so on 3.9 the import raises:

TypeError: unsupported operand type(s) for |: 'type' and 'type'

On 3.8 it fails one line earlier still, at the PEP 585 -> Iterable[str] return annotation.

fal.cli.parser imports argcomplete at module scope, so this takes down the entire CLI import chain — fal.cli.parser → fal.cli.runners → fal.cli.apps → fal.cli.main → fal.cli.

Blast radius

Not only CI. Every fal version already on PyPI is affected, because the open argcomplete>=3.1.0,<4 bound resolves to whatever is newest at install time:

Install today	argcomplete resolved	fal --help
fal==1.79.0 on py3.9	3.7.1	crashes
fal==1.78.3 on py3.9 (predates the break by a month)	3.7.1	crashes
fal==1.79.0 on py3.10	3.7.1	ok

In CI, unit (py 3.8) and unit (py 3.9) went red on every PR that has run since the release — #1119, #1125, #1126 — each with 48 collection errors across tests/unit/cli/* and tests/unit/console/test_encoding.py. main was last green at 06:19 UTC, before the release, and goes red on its 05:30 UTC cron.

Upstream

Introduced by kislyuk/argcomplete#554 ("100% type coverage"), a typing sweep adding PEP 585/604 annotations with no from __future__ import annotations. It merged 49 seconds after 0d1cb9ad ("Drop EOL Pythons from CI") removed 3.8/3.9 from the matrix — those jobs had been failing on the PR. requires-python was never updated to match, which is what leaves pip installing it on 3.8/3.9.

Tracked at kislyuk/argcomplete#559; kislyuk/argcomplete#558 ("Require Python 3.10+") is open and would resolve it by formalizing the drop.

Changes

1. Exclude the bad version on Python < 3.10 — projects/fal/pyproject.toml

"argcomplete>=3.1.0,<4; python_version >= '3.10'",
"argcomplete>=3.1.0,!=3.7.1,<4; python_version < '3.10'",

Version-specific rather than a <3.7.1 ceiling, so it lapses cleanly when a fixed release ships and never holds 3.8/3.9 back further than it has to. Python 3.10+ keeps tracking latest.

2. Gate the PyPI release on a fresh unit-test run — release.yaml, fal-unit-tests.yml

fal 1.79.0 was published at 18:46 UTC from 1604f774, whose last unit run was green at 06:19 — 12.5 hours earlier, and 9 hours before argcomplete 3.7.1 existed. release.yaml runs build → pypi-publish and neither runs nor checks tests, so a release inherits whatever green happened to be on the commit, however old.

Checking the commit's stored status would not have helped here; it was green. Because the dependency bounds are open, the installed tree is a function of when the job runs rather than of the commit, so only re-resolving at release time surfaces it.

fal-unit-tests.yml gains a workflow_call trigger, and pypi-publish now requires it:

  unit-tests:
    if: ${{ needs.build.outputs.name == 'fal' }}
    needs: build
    uses: ./.github/workflows/fal-unit-tests.yml

  pypi-publish:
    needs: [build, unit-tests]
    if: >-
      ${{ !cancelled()
        && needs.build.result == 'success'
        && (needs['unit-tests'].result == 'success' || needs['unit-tests'].result == 'skipped') }}

The gate is scoped to the fal project. isolate_proto and fal_client releases skip it, and pypi-publish tolerates a skipped result so those are unaffected — without that, a skipped dependency would skip the publish too.

Trade-off worth naming: a required gate can block a release when something unrelated fails. The unit suite is the fastest reliable signal available here — e2e and integration are chronically red for unrelated credential reasons and are deliberately not part of the gate.

3. An escape hatch for urgent releases — release.yaml

A required gate needs a bypass, or the first urgent release fights it. skip_tests is a workflow_dispatch input defaulting to false:

gh workflow run release.yaml -f tag=fal_v1.79.1 -f skip_tests=true

It exists only on the manual path. A release: published event leaves inputs empty, so the automatic path stays gated with no way to bypass it — an emergency release has to be a deliberate dispatch, and the run records the actor and the input value.

One subtlety worth flagging for review, because it is invisible when wrong. The condition uses inputs.skip_tests, not github.event.inputs.skip_tests. The latter is always a string, and every non-empty string is truthy in an expression, so !github.event.inputs.skip_tests evaluates !"false" → false and would skip the tests on every dispatch — the gate silently off, looking fine. Measured on both forms:

Trigger	!inputs.skip_tests (used)	!github.event.inputs.skip_tests (trap)
skip_tests=false	true → tests run	false → tests skipped
skip_tests=true	false → skipped	false → skipped
push / release event	true → tests run	true → tests run

The forms agree everywhere except the most common dispatch case, which is what would have hidden it.

How to test

Reproduce the break, then confirm the pin:

uv venv /tmp/ac39 --python 3.9
uv pip install --python /tmp/ac39/bin/python "argcomplete==3.7.1"
/tmp/ac39/bin/python -c "import argcomplete"   # TypeError

uv pip install --python /tmp/ac39/bin/python -e "projects/fal[test]"
/tmp/ac39/bin/python -c "import fal.cli.parser"
/tmp/ac39/bin/python -m pytest projects/fal/tests/unit/cli projects/fal/tests/unit/console

Confirm a clean runtime install, the path a user takes:

uv venv /tmp/smoke39 --python 3.9
uv pip install --python /tmp/smoke39/bin/python ./projects/fal   # runtime deps only
/tmp/smoke39/bin/fal --help

CI signal to watch: unit (ubuntu-latest, py 3.8, pydantic==1.10.18) and unit (ubuntu-latest, py 3.9, pydantic==2.13.3) must go green. The release gate cannot run on a PR — it is exercised only by a release event — so it was validated statically, below.

Verified in this session:

Check	Result
import argcomplete on py3.9 with 3.7.1	TypeError: unsupported operand type(s) for | — reproduced
import argcomplete on py3.9 with 3.7.0	ok
Resolution on py3.9 after the pin	argcomplete 3.7.0
Resolution on py3.12 after the pin	argcomplete 3.7.1 — latest, unaffected
pytest tests/unit/cli tests/unit/console on py3.9	247 passed (was 48 collection errors)
Same, merged into #1126's head	248 passed, clean merge
Full tests/unit on py3.9	907 passed; 12 errors all in test_file_sync.py from absent local credentials (401), which CI supplies
Clean runtime install on py3.8 and py3.9, unconstrained	fal --help crashes
Clean runtime install on py3.8 and py3.9, with this branch	resolves 3.7.0, fal --help ok
Published fal==1.79.0 + argcomplete!=3.7.1 on py3.9	fal --help ok — an upstream yank alone would repair released versions
Wheel built from this branch — metadata	argcomplete!=3.7.1,<4,>=3.1.0; python_version < "3.10" present
That wheel installed fresh on py3.8 and py3.9	resolves argcomplete 3.7.0, imports ok, fal --help ok
actionlint on release.yaml and fal-unit-tests.yml	clean (the one repo-wide finding is a pre-existing set-output deprecation in container.yml)

Release gate, executed

The gate cannot run on a PR, so its job graph was reproduced exactly — same if expression, publish step replaced by an echo — and run on a throwaway branch, since deleted:

Scenario	unit-tests	pypi-publish	Expected
fal release, tests pass	success	ran	✅ publishes
fal release, tests fail	failure	skipped	✅ gate holds
isolate_proto release	skipped	ran	✅ unaffected
Real uses: ./.github/workflows/fal-unit-tests.yml	8/8 jobs success	—	✅ workflow_call is valid
Dispatch, skip_tests=false	success	ran	✅ default stays gated
Dispatch, skip_tests=true	skipped	ran	✅ bypass works
Push / no inputs (stands in for release: published)	success	ran	✅ automatic path gated

The third row is the one that would silently break other projects' releases if the condition were wrong; the fourth confirms the reusable-workflow call resolves; the last three cover the bypass, including that it cannot be reached from the automatic path.

Not verified: the py3.8 leg of the unit suite locally — no 3.8 interpreter with test extras to hand; CI covers it directly, and the py3.8 install path is verified above. The gate has not run against a real release event, which would require publishing; the simulation above covers its logic and the reusable call.

Follow-ups, not in this PR

• A scheduled canary against the published package. Nothing looks at PyPI, so an upstream break of an already-released version is invisible until someone reports it. Opening separately.
• release-container still only needs: build, so a container can ship from a build the gate would have blocked. Left alone here to keep this change to the PyPI path; worth extending.
• An upstream yank of argcomplete 3.7.1 would repair every already-published fal version with no release from us — worth requesting on kislyuk/argcomplete#559. This PR is the path that does not depend on upstream acting.
• Whether fal should keep supporting 3.8/3.9. Both are EOL and upstream argcomplete is dropping them. A product decision, separate from this fix.

Note

e2e and integration failures on this repo are a separate, pre-existing matter — they fail on main too, with Insufficient permissions from the CI service account, and have for 8+ days. Untouched here.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes release gating and install-time dependency resolution for all fal users on 3.8/3.9; incorrect workflow conditions could block publishes or skip tests on dispatch.

Overview
Pins argcomplete so Python 3.8/3.9 never resolve 3.7.1 (PEP 604 annotations break CLI import), while 3.10+ keep the existing upper bound.

Release automation now re-runs fal unit tests with fresh dependency resolution before PyPI publish and container push; fal-unit-tests.yml is reusable via workflow_call. Manual releases get an optional skip_tests bypass using inputs.skip_tests (not stringly github.event.inputs).

^{Reviewed by Cursor Bugbot for commit f5bc141. Bugbot is set up for automated code reviews on this repo. Configure here.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​argcomplete@​3.7.0

View full report

[jim-fal]

CI confirms it, and isolates it cleanly. Comparing this PR against the two other open PRs on the same base, at the same time:

PR	unit (py 3.8)	unit (py 3.9)	Other failures
#1127 (this)	✅ pass	✅ pass	16
#1119	❌ fail	❌ fail	16
#1126	❌ fail	❌ fail	16

The two unit jobs are the only difference. The remaining 16 are the identical set of e2e and integration jobs on all three, failing with UNAUTHENTICATED: Insufficient permissions — they fail on main too and are untouched by this PR.

unit on py 3.10 through 3.14 and windows-2022 stayed green throughout, so the marker does not disturb the versions that were already fine.

[claude]

LGTM — a minimal, well-verified dependency pin that unblocks CI.

Extended reasoning...

Overview

Single-line change to projects/fal/pyproject.toml: splits the argcomplete dependency constraint into two environment markers, adding !=3.7.1 for python_version < '3.10' while leaving 3.10+ tracking latest. No runtime/application code is touched.

Security risks

None. This is a version-exclusion pin on a build/lint-time CLI completion dependency, not a security-sensitive path (no auth, crypto, or permission logic involved).

Level of scrutiny

Low. This is a mechanical, reversible dependency fix responding to a concrete, reproduced upstream breakage (PEP 604 syntax incompatible with the package's own declared requires-python). The PR includes clear reproduction steps and verification output (247 previously-erroring tests now passing on py3.9), and a maintainer (jim-fal) independently confirmed via CI comparison against sibling PRs that the two unit jobs are the only jobs affected and now pass, with no regression on py3.10–3.14 or Windows.

Other factors

The scoped !=3.7.1 marker (rather than a blanket ceiling) is the right shape — it self-resolves once upstream ships a fix or yanks the bad release, and the inline comment documents the upstream issue for future readers. No outstanding review comments to address.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 02e0000. Configure here.}