feat: downgrade Python baseline to 3.13 for PaddleOCR compatibility
Tests / Test passed: 789

paddlepaddle has no Python 3.14 (cp314) wheel on PyPI, so host-agent
deployments on 3.14 can never install it, causing OCR to fail at
runtime with RuntimeError. Pin the workspace to Python 3.13 across
all pyproject.toml files, the Docker base image, and the Jenkins CI
image; regenerate uv.lock against 3.13.

Also fixes a pre-existing Python-2-style `except X, Y:` syntax error
(invalid in all Python 3.x) in runtime/task.py and
packages/cloud-platform/cloud/{sql_repository,internal_api/api}.py,
introduced in 22d37ca9 and unrelated to this change's scope, which
blocked the full test suite from collecting on any interpreter
version.

openspec change: downgrade-python-3-13-paddleocr
This commit is contained in:
2026-07-14 18:05:49 +08:00
parent ecb1dba9ff
commit 25ebc10a8a
16 changed files with 645 additions and 792 deletions
@@ -0,0 +1,36 @@
## 1. Update Python version pins
- [x] 1.1 Update `requires-python` in root `pyproject.toml` from `>=3.14` to `>=3.13,<3.14`
- [x] 1.2 Update `requires-python` in `apps/device-host-agent/pyproject.toml` to `>=3.13,<3.14`
- [x] 1.3 Update `requires-python` in `apps/cloud-api/pyproject.toml` to `>=3.13,<3.14`
- [x] 1.4 Update `requires-python` in `packages/cloud-platform/pyproject.toml` to `>=3.13,<3.14`
## 2. Update container/CI base images
- [x] 2.1 Update `Dockerfile:26` base image from `astral-sh/uv:python3.14-bookworm-slim` to `astral-sh/uv:python3.13-bookworm-slim`
- [x] 2.2 Update `Jenkinsfile:58` image reference from `astral-sh/uv:python3.14-bookworm-slim` to `astral-sh/uv:python3.13-bookworm-slim`
- [x] 2.3 Grep the repo for any other `python3.14`/`3.14` references tied to the toolchain (excluding this change's own `openspec/changes/` artifacts and historical `openspec/changes/archive/` records) and update or confirm each is out of scope
## 3. Regenerate the lockfile and provision the environment
- [x] 3.1 `uv python install 3.13`
- [x] 3.2 `uv lock` to regenerate `uv.lock` against Python 3.13; confirm the resolution completes without conflict errors
- [x] 3.3 `uv sync --locked --all-packages` to provision a fresh `.venv`; confirm it uses the 3.13 interpreter (`uv run --package device-agent-runtime python --version`)
- [x] 3.4 Confirm `paddlepaddle` is now installable against the regenerated lock/environment (`uv pip install paddlepaddle` succeeds and `python -c "import paddle"` works) — manual, not added to `pyproject.toml`/`uv.lock`, per design.md Non-Goals
## 4. Verify no Python-3.14-only usage breaks under 3.13
- [x] 4.1 Run the full non-integration suite against the 3.13 environment: `uv run --all-packages pytest -m "not integration"`; fix any failures caused by the interpreter downgrade (none expected per design.md D4) — 543 passed. Note: collection was initially blocked by pre-existing Python-2-style `except X, Y:` syntax errors (7 occurrences across `runtime/task.py`, `packages/cloud-platform/cloud/sql_repository.py`, `packages/cloud-platform/cloud/internal_api/api.py`), introduced by commit `22d37ca9` (2026-07-13) unrelated to this change's scope. Fixed as a drive-by (parenthesized the tuples) per user direction, since they blocked verification on any Python version.
- [x] 4.2 Run `uv run --all-packages python -m compileall .` (or equivalent) across the workspace to catch any syntax-level incompatibility beyond what pytest collection would exercise — clean, no errors (scoped to project source dirs, excluding `.venv`)
- [x] 4.3 Ruff check/format on any files touched by this change — `uvx ruff check` all checks passed; `uvx ruff format --check` 3 files already formatted (ruff isn't a project dependency, run ephemerally via `uvx`)
## 5. Update documentation
- [x] 5.1 Update `docs/MACOS_IPHONE_SETUP.md` §4.2 to reflect the Python 3.13 baseline and remove/replace the now-obsolete "do not downgrade to 3.13 ad hoc" warning (lines ~156-158) with guidance that 3.13 is now the supported version
- [x] 5.2 Sweep `docs/MACOS_IPHONE_SETUP.md` and any other docs for stray `3.14` references introduced when the project originally targeted 3.14, and correct them to `3.13` — only remaining `3.14` mentions are the intentional upper-bound pin and the paddlepaddle-wheel-availability explanation
## 6. Final validation
- [x] 6.1 `git diff --check` (no whitespace errors) across all changed files — clean
- [x] 6.2 `openspec validate downgrade-python-3-13-paddleocr --strict` — valid
- [x] 6.3 Confirm all four `pyproject.toml` files and `Dockerfile`/`Jenkinsfile` agree on the same Python version, and `uv.lock` is committed alongside them — all agree on 3.13