[NRT-873] Build the vendored bundle from uv.lock and guard Python 3.9 support

[RisingOrange]

Related issues

• NRT-873
• Follow-up to fix: Pin asgiref and urllib3 to versions that still support Python 3.9 #1359, the emergency hotfix that pinned asgiref<3.12

Proposed changes

scripts/build.py re-resolved the bundle group from pyproject.toml on every build. It never read uv.lock, and it evaluated markers against the build machine's Python (3.13) rather than the oldest interpreter the add-on has to run on — so any transitive that dropped Python 3.9 reached users unnoticed, which is what happened when asgiref 3.12 was released.

Anki bundles its own CPython. Official builds moved to 3.13 in 25.07, but the builds before that ship 3.9, and with a declared minimum Anki of 2.1.56 the add-on still has to run there. Roughly a quarter of active users are on an Anki predating 25.07.

The fix makes the break impossible rather than merely detected. The bundle now installs from the lockfile, in two layers, each with the oldest Python that can reach it: the bundle group with 3.9, bundle_modern (protobuf-py, which has required 3.10 since its first release) with 3.10. uv refuses a distribution declaring a newer floor, so the build fails instead of the add-on. They are separate dependency groups, so routing never reads markers.

Resolution only sees declared floors, so detection still covers the rest — an undeclared floor, a requirement a false marker dropped silently, a fault in assembling the archive — across the build, the packaged archive, and an import inside a real Anki on 3.9.

The build

• From uv.lock, not re-resolved. uv export --locked --only-group <group> into uv pip install --no-deps. --locked also fails the build when the lockfile is out of step with pyproject.toml instead of quietly preferring one. Side effect: mashumaro is now pinned to the revision the lock recorded rather than tracking the fork's mutable master.
• Every exported requirement must arrive. A requirement whose marker is false for the building interpreter or platform installs nothing and reports nothing, so its absence is the only signal there is. The build compares the export against the finished bundle's dist-info — catching a distribution that never arrived, not one whose files a prune removed.
• Compiled extensions must be audited. abi3 fixes only the interpreter axis — protobuf-py-ext's wheel is cp310-abi3-manylinux_2_17_x86_64, unloadable on Windows, macOS or ARM. So what earns a place is the package falling back without it: protobuf-py catches the failed import (kept), nothing imports playhouse (its 2 MB dropped). Anything else fails the build.
• Nothing survives a previous build. ankihub/lib is cleared and the previous .ankiaddon deleted — uv pip install --target and zip both update in place, so unvendored packages were surviving into local artifacts.
• media_import installs with 3.9 too. Its requirements come from the submodule's own requirements.txt, not uv.lock, and were installed with whatever Python ran the build — outside every check, all of which were scoped to ankihub/lib. One pinned pure-Python package today, so nothing shipped was broken.

What gets checked

scripts/check_addon_import.py imports the built add-on the way Anki does — aqt.addons first, then ankihub.entry_point — and asserts where each vendored top-level package resolved from. The list comes from the bundle directory, and each assertion's direction follows from whether Anki had already imported that name, so on 2.1.56 certifi, typing_extensions and urllib3 must resolve outside the bundle and everything else inside it. It then renders a template through the add-on's own render_template_from_string(), covering packages nothing imports directly, such as sqlparse. It also parses every .py in the bundle under 3.9, reaching files nothing pulls in. Point it at a bundle carrying asgiref 3.12.1 and it reproduces the reported ImportError. It runs in the CI 3.9 lane, the only place with an Anki-on-3.9 environment.

scripts/release.sh adds three cheap checks over the extracted .ankiaddon: required members present, parses under 3.9, and the 3.10-only layer imports under 3.10. These live there because every workflow producing an artifact runs that script, so one added later inherits them — previously only the GitHub release was covered, not the copy users install from AnkiWeb. build.py is invoked as uv run --locked here and in setup-addon, since a plain sync or run re-locks a stale lockfile, after which build.py's own uv export --locked is satisfied by what it just wrote.

Why not the test suite. It runs the add-on on 3.9, but pytest plugins and factory-boy import django, asgiref and urllib3 from the dev environment before import ankihub prepends the bundle, so the bundled copies are shadowed and never exercised — that lane vendored the broken asgiref==3.12.1 and went green. Reordering conftest.py fixes it, but the guarantee would then be an import order the import sorter is free to undo, failing silently.

Smaller changes

• Cap urllib3 in bundle. Not the Python floor the layers enforce — urllib3 2.x still supports 3.9 — but sentry-sdk 1.6.0 predates urllib3 2.0's API changes, and only the dev group's cap held it at 1.x.
• Vendor tzdata unconditionally. Django declares it win32-only and the bundle is built on Linux, so the marker dropped it for exactly the users who need it. Latent until a template uses a date filter.
• Django 4.2.27 → 4.2.30, the final 4.2 security release. Re-locking also moved asgiref, django-cotton 2.5.1→2.7.2, certifi, sqlparse and typing-extensions — already what a fresh resolve produced, but the lock is authoritative for the artifact for the first time, so the uv.lock hunks are worth a look.
• Remove the sys.path entry for ankihub/lib/other — it has pointed at nothing since [INTP-141] Avoid comitting vendored dependencies #1176, while sitting ahead of the bundle.
• README and justfile gain --group bundle_modern, without which a 3.10+ dev environment has no protobuf-py and mypy fails on ankihub/proto/*.py.
• no_absolute_imports_from_ankihub skips scripts/ — the rule exists because Anki installs the add-on under its AnkiWeb id; build scripts are not shipped inside it.

How to reproduce

GOOGLE_API_KEY=dummy bash ./scripts/release.sh   # ends "... assembled, parses on Python 3.9, and its Python 3.10 layer loads"
xvfb-run -a uv run --exact --group aqt_legacy --python 3.9 python scripts/check_addon_import.py

The install-time refusal, which is what makes the original incident impossible:

uv pip install --python 3.9 --no-deps --target /tmp/x asgiref==3.12.1
# error: ... asgiref==3.12.1 depends on Python>=3.10 ... requirements are unsatisfiable

And detection, for a bundle that acquired a bad version some other way:

uv pip install --python 3.13 --no-deps --target ankihub/lib asgiref==3.12.1
xvfb-run -a uv run --exact --group aqt_legacy --python 3.9 python scripts/check_addon_import.py
# ImportError: cannot import name 'ParamSpec' from 'typing'

Also verified: the artifact holds 15 distributions (one more than before — tzdata) at 7.2 MB compressed; pytest ./tests/addon -m "not sequential and not performance" 731 passed; mypy clean on 118 files.

Verified by hand in Anki

The built artifact was installed and exercised in real Anki on three interpreters, since what changed is what the add-on ships:

• Anki 25.02.7 / Python 3.9.23 — the configuration this exists for. Loads; django, asgiref.sync, peewee, structlog, sentry_sdk resolve from the bundle, urllib3 from Anki's venv. Sync and deck install work, so peewee runs without the stripped C extensions. django-cotton renders end to end — component loader, attribute expressions, nested components — the extent of what 2.5.1 → 2.7.2 could have broken.
• Anki 25.09 / Python 3.13 / Linux — loads; urllib3 resolves from Anki's site-packages, so the shadowing contract holds in a real host; the abi3 extension loads.
• Anki 25.09 / Python 3.13 / macOS arm64 — same Linux-built artifact. dlopen fails on the foreign x86_64 ELF, protobuf-py suppresses that ImportError and falls back to pure Python; messages still round-trip — the last known limit's fallback working with the wrong OS and architecture at once.

Further comments

Known limits, so nobody assumes more coverage than exists:

• Prevention covers declared floors only. An undeclared one is caught by the 3.9 import check, or not at all.
• That check imports the add-on; it does not call entry_point.run(), which needs a running Anki, and it imports the package as ankihub rather than under its AnkiWeb id.
• It imports each package's top level, so a submodule is covered only if something reaches it. asgiref.sync — where the incident was — is covered because Django's template stack pulls it in, not because asgiref is vendored: import asgiref alone passes against a bundle carrying 3.12.1. The parse pass reaches every file but catches only syntax.
• release.sh's parse pass narrows the publish-path gap rather than closing it, for the same reason.
• The vendored protobuf extension is built for the build host; protobuf-py falls back where it cannot load, now confirmed on macOS arm64. Windows is untested, though it exercises the fallback more weakly — it ignores .so outright rather than attempting the load.

Known follow-ups, deliberately not here:

• The AnkiWeb and S3 upload workflows are workflow_dispatch and have no CI gate, so a dispatch can publish without the 3.9 lane ever running. create_release.yml has the gate mechanism to copy.
• Make that gate SHA-aware: create_release.yml checks the last CI run's conclusion but not its commit, so a push whose run has not been created yet slips through. Affects all regressions, not just 3.9 ones.
• Build isolation is not locked. peewee is an sdist, so the same uv.lock can yield a different wheel later via a different build backend.
• The Django render check renders plain HTML, so the cotton component loader — the novel vendored machinery — is not covered by it. It was verified by hand above.
• Audit or bump sentry-sdk 1.6.0 (June 2022). It declares no Requires-Python and is what makes urllib3 a dependency at all.
• certifi is still vendored though shadowed, for the same reason urllib3 is. A size cleanup, not a 3.9 fix.
• create_release.yml builds the artifact before committing and tagging the version bump. Left alone deliberately: reordering would leave a pushed tag for a release that never shipped whenever a check fails.