q792602257
25ebc10a8a
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
30 lines
3.6 KiB
Markdown
30 lines
3.6 KiB
Markdown
## Why
|
|
|
|
PaddlePaddle has not published a Python 3.14 (`cp314`) wheel on PyPI (confirmed against PyPI project page and `PaddlePaddle/PaddleOCR#17370`, upstream tracking issue, no ETA). `perception/ocr.py::PaddleOCREngine` requires `paddlepaddle` at runtime to actually run inference, and `paddleocr>=3.0.0` is a hard dependency in `pyproject.toml`. Because the workspace pins `requires-python = ">=3.14"`, any host running this project on Python 3.14 can install `paddleocr` (pure-Python wheel) but can never install `paddlepaddle` — OCR will always fail with `RuntimeError: Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed.` regardless of how the package is installed.
|
|
|
|
This has already caused a production task failure (`assignment ec036... attempt 1 on device-8967d09f0d5f4cf49f7361a9f0dcb0ce: failed`). `docs/MACOS_IPHONE_SETUP.md` already anticipated this class of problem and explicitly told operators not to downgrade to Python 3.13 ad hoc — it requires this to be done as a reviewed, workspace-wide compatibility change first. This proposal is that change.
|
|
|
|
## What Changes
|
|
|
|
- Lower the workspace's minimum/target Python version from `3.14` to `3.13` so `paddlepaddle` (and therefore working OCR) can actually be installed. **BREAKING**: any environment currently pinned to Python 3.14 must reinstall its toolchain with Python 3.13; `uv.lock` will be regenerated against the new interpreter and is not compatible with a 3.14-only environment.
|
|
- Update `requires-python` in all four workspace `pyproject.toml` files (root, `apps/device-host-agent`, `apps/cloud-api`, `packages/cloud-platform`) from `>=3.14` to `>=3.13,<3.14`.
|
|
- Update the Docker/CI base image from `astral-sh/uv:python3.14-bookworm-slim` to `astral-sh/uv:python3.13-bookworm-slim` in `Dockerfile` and `Jenkinsfile`.
|
|
- Regenerate `uv.lock` against Python 3.13, which is expected to newly resolve a `paddlepaddle` wheel as installable (it is not added as a declared dependency by this change — see Non-Goals in design.md).
|
|
- Audit the codebase for any Python-3.14-only syntax/stdlib usage that would break under 3.13, and fix or confirm none exists.
|
|
- Update `docs/MACOS_IPHONE_SETUP.md` to remove/replace the now-obsolete "do not downgrade to 3.13 ad hoc" warning with guidance matching the new baseline.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
- `python-runtime-baseline`: declares and enforces the workspace's supported Python interpreter version (3.13) consistently across all `pyproject.toml` files, `uv.lock`, the Docker image, and the CI pipeline.
|
|
|
|
### Modified Capabilities
|
|
(none — no *existing* capability's observable requirements change; `perception-provider` and `host-agent-protocol` behavior are unaffected, only the Python interpreter version and dependency resolution change)
|
|
|
|
## Impact
|
|
|
|
- **Affected files**: `pyproject.toml`, `apps/device-host-agent/pyproject.toml`, `apps/cloud-api/pyproject.toml`, `packages/cloud-platform/pyproject.toml`, `uv.lock`, `Dockerfile`, `Jenkinsfile`, `docs/MACOS_IPHONE_SETUP.md`.
|
|
- **Affected systems**: local dev environments, CI (Jenkins), production Docker images/deployment — all must move to Python 3.13.
|
|
- **Dependencies**: full `uv lock` re-resolution against 3.13; no dependency version pins in `pyproject.toml` are expected to need changes, but the lock will reflect whatever the resolver picks for 3.13.
|
|
- **Out of scope**: actually declaring `paddlepaddle` as a project dependency (remains a manual per-host install, per prior decision) and hardening `perception/ocr.py::run_ocr()` to catch `RuntimeError` (previously declined by the user as a separate concern).
|