DarkHelm.org/plex-playlist
Public Access
4
0
Fork 0
Code Issues 56 Pull Requests 1 Actions 9 Packages Projects 1 Releases Wiki Activity

TASK: Upgrade backend runtime and dependency constraints #10

New Issue
Open
opened 2026-05-15 17:32:19 -04:00 by darkhelm · 1 comment
darkhelm commented 2026-05-15 17:32:19 -04:00
Owner
Copy Link

Parent

#2

What to build

Update project to Python 3.14 syntax target and align FastAPI/SQLAlchemy/SQLModel versions with compatibility checks.

Acceptance criteria

  • Backend project metadata targets Python 3.14
  • Dependency versions are pinned/ranged for reproducibility
  • CI passes after upgrade

Blocked by

Notes

  • Python backend code must be fully typed and async-safe.
  • Any blocking work must be wrapped through thread/process execution paths as appropriate.
  • Must pass lint, format, typing, docstring, and test quality gates.
## Parent #2 ## What to build Update project to Python 3.14 syntax target and align FastAPI/SQLAlchemy/SQLModel versions with compatibility checks. ## Acceptance criteria - [ ] Backend project metadata targets Python 3.14 - [ ] Dependency versions are pinned/ranged for reproducibility - [ ] CI passes after upgrade ## Blocked by - #2 ## Notes - Python backend code must be fully typed and async-safe. - Any blocking work must be wrapped through thread/process execution paths as appropriate. - Must pass lint, format, typing, docstring, and test quality gates.
darkhelm added this to the v1 Dynamic Realtime Playlist milestone 2026-05-15 17:32:19 -04:00
darkhelm added the taskafkdevexbackend labels 2026-05-15 17:32:19 -04:00
darkhelm added this to the Main Project Board project 2026-05-15 17:51:06 -04:00
darkhelm removed this from the Main Project Board project 2026-05-15 17:53:46 -04:00
darkhelm modified the milestone from v1 Dynamic Realtime Playlist to E1 - Platform Baseline and Standards Upgrade 2026-05-15 17:58:01 -04:00
darkhelm commented 2026-05-15 18:26:22 -04:00
Author
Owner
Copy Link

Plan: Python 3.14 Backend Runtime Upgrade

Upgrade backend runtime/tooling targets to Python 3.14, move backend dependency declarations to exact pins for deterministic resolution, and validate CI/local quality gates still pass. Recommended approach: first align all Python-version declarations, then pin backend deps and regenerate lock, then run full verification matrix (lint/type/tests/container builds) before updating docs.

Steps

  1. Phase 1 - Baseline Alignment
  2. Confirm and document current mismatch points (backend runtime image 3.12, tool targets 3.13, project min >=3.13) and lock final target policy as: minimum Python >=3.14 and exact pins in backend metadata.
  3. Update backend Python target declarations to 3.14 in project metadata and tooling config (depends on step 1).
  4. Update backend runtime/container base versions to 3.14 where backend and CI images derive Python (parallel with step 3 when files are independent).
  5. Phase 2 - Dependency Constraint Hardening
  6. Convert backend direct dependencies and backend dev dependency group entries from ranged constraints to exact pins in pyproject (depends on step 3).
  7. Regenerate/re-resolve backend lock file using Python 3.14 interpreter and ensure lock captures compatible wheels/sdists for pinned versions (depends on step 6).
  8. Verify pinned versions satisfy FastAPI/SQLAlchemy/SQLModel compatibility intent; if SQLAlchemy/SQLModel are newly introduced for this task, add and pin both explicitly with compatible versions and update lock accordingly (depends on step 7).
  9. Phase 3 - CI/Gates Stabilization
  10. Validate local quality gates under Python 3.14: format, lint, strict type-checking, unit/integration tests, coverage, docstring/doctest checks (depends on step 7; some checks can run parallel once env is prepared).
  11. Validate container workflows: backend image build, CI base image build, multi-stage CI image build, and compose startup path for backend service (depends on step 4 and step 7).
  12. Update CI/workflow/runtime references that still assume older Python versions (depends on step 11).
  13. Phase 4 - Documentation and Completion
  14. Update developer and CI docs to reflect Python 3.14 baseline, exact pinning strategy, and lockfile update process (depends on step 12).
  15. Prepare completion notes mapping each acceptance criterion to concrete evidence (test outputs/build outputs/config diffs) (depends on step 14).

Relevant files

  • pyproject.toml - Primary source for requires-python, dependency constraints, tool targets (ruff), and task wiring.
  • pyrightconfig.json - Strict type-check Python target version.
  • uv.lock - Deterministic dependency resolution artifact to refresh after pinning.
  • Dockerfile.backend - Runtime Python base image for backend service.
  • Dockerfile.cicd-base - CI base Python installation target.
  • Dockerfile.cicd - Multi-stage CI image that consumes backend dependency setup.
  • cicd.yml - CI pipeline behavior and potential version assumptions.
  • compose.yml - Production compose backend build/runtime path verification.
  • compose.dev.yml - Dev compose backend runtime verification.
  • DEVELOPMENT.md - Developer setup/runtime requirements.
  • POE_TASK_REFERENCE.md - Quality gate command references that may need version language updates.
  • CICD_MULTI_STAGE_BUILD.md - CI build architecture and runtime assumptions.
  • CICD_TROUBLESHOOTING_GUIDE.md - Troubleshooting entries likely affected by runtime baseline change.

Verification

  1. Environment sanity: confirm interpreter and toolchain versions report Python 3.14 in backend and CI build contexts.
  2. Backend checks: run format check, lint, strict pyright, unit tests, integration tests, coverage threshold (>=95), and doctest/docstring gates.
  3. Dependency integrity: run dependency consistency checks and ensure lockfile is reproducible from pinned metadata.
  4. Container validation: build backend image and CI images, then run smoke startup for backend service via compose.
  5. CI confidence: execute or simulate the CI command sequence locally to reduce workflow breakage risk before merge.

Decisions

  • Confirmed with user: dependency policy is exact pins in backend metadata (==) plus lockfile.
  • Confirmed with user: Python support floor moves to >=3.14.
  • Included scope: backend runtime/tooling/dependency constraints, lock regeneration, CI/container compatibility checks, and docs updates tied to this upgrade.
  • Excluded scope: frontend runtime/dependency upgrades, unrelated refactors, and feature development beyond compatibility work.

Further Considerations

  1. SQLAlchemy/SQLModel are not currently declared in backend metadata; implementation should confirm whether this task introduces them now or only future-proofs compatibility language.
  2. If any pinned package lacks 3.14-compatible wheels, choose between pin adjustments or temporary source-build allowance in CI with explicit documentation.
  3. If CI base image provisioning source (deadsnakes/PPA) lags for 3.14 patch releases, consider a fallback strategy (official Python images) to avoid pipeline downtime.
## Plan: Python 3.14 Backend Runtime Upgrade Upgrade backend runtime/tooling targets to Python 3.14, move backend dependency declarations to exact pins for deterministic resolution, and validate CI/local quality gates still pass. Recommended approach: first align all Python-version declarations, then pin backend deps and regenerate lock, then run full verification matrix (lint/type/tests/container builds) before updating docs. **Steps** 1. Phase 1 - Baseline Alignment 2. Confirm and document current mismatch points (backend runtime image 3.12, tool targets 3.13, project min >=3.13) and lock final target policy as: minimum Python >=3.14 and exact pins in backend metadata. 3. Update backend Python target declarations to 3.14 in project metadata and tooling config (depends on step 1). 4. Update backend runtime/container base versions to 3.14 where backend and CI images derive Python (parallel with step 3 when files are independent). 5. Phase 2 - Dependency Constraint Hardening 6. Convert backend direct dependencies and backend dev dependency group entries from ranged constraints to exact pins in pyproject (depends on step 3). 7. Regenerate/re-resolve backend lock file using Python 3.14 interpreter and ensure lock captures compatible wheels/sdists for pinned versions (depends on step 6). 8. Verify pinned versions satisfy FastAPI/SQLAlchemy/SQLModel compatibility intent; if SQLAlchemy/SQLModel are newly introduced for this task, add and pin both explicitly with compatible versions and update lock accordingly (depends on step 7). 9. Phase 3 - CI/Gates Stabilization 10. Validate local quality gates under Python 3.14: format, lint, strict type-checking, unit/integration tests, coverage, docstring/doctest checks (depends on step 7; some checks can run parallel once env is prepared). 11. Validate container workflows: backend image build, CI base image build, multi-stage CI image build, and compose startup path for backend service (depends on step 4 and step 7). 12. Update CI/workflow/runtime references that still assume older Python versions (depends on step 11). 13. Phase 4 - Documentation and Completion 14. Update developer and CI docs to reflect Python 3.14 baseline, exact pinning strategy, and lockfile update process (depends on step 12). 15. Prepare completion notes mapping each acceptance criterion to concrete evidence (test outputs/build outputs/config diffs) (depends on step 14). **Relevant files** - pyproject.toml - Primary source for requires-python, dependency constraints, tool targets (ruff), and task wiring. - pyrightconfig.json - Strict type-check Python target version. - uv.lock - Deterministic dependency resolution artifact to refresh after pinning. - Dockerfile.backend - Runtime Python base image for backend service. - Dockerfile.cicd-base - CI base Python installation target. - Dockerfile.cicd - Multi-stage CI image that consumes backend dependency setup. - cicd.yml - CI pipeline behavior and potential version assumptions. - compose.yml - Production compose backend build/runtime path verification. - compose.dev.yml - Dev compose backend runtime verification. - DEVELOPMENT.md - Developer setup/runtime requirements. - POE_TASK_REFERENCE.md - Quality gate command references that may need version language updates. - CICD_MULTI_STAGE_BUILD.md - CI build architecture and runtime assumptions. - CICD_TROUBLESHOOTING_GUIDE.md - Troubleshooting entries likely affected by runtime baseline change. **Verification** 1. Environment sanity: confirm interpreter and toolchain versions report Python 3.14 in backend and CI build contexts. 2. Backend checks: run format check, lint, strict pyright, unit tests, integration tests, coverage threshold (>=95), and doctest/docstring gates. 3. Dependency integrity: run dependency consistency checks and ensure lockfile is reproducible from pinned metadata. 4. Container validation: build backend image and CI images, then run smoke startup for backend service via compose. 5. CI confidence: execute or simulate the CI command sequence locally to reduce workflow breakage risk before merge. **Decisions** - Confirmed with user: dependency policy is exact pins in backend metadata (==) plus lockfile. - Confirmed with user: Python support floor moves to >=3.14. - Included scope: backend runtime/tooling/dependency constraints, lock regeneration, CI/container compatibility checks, and docs updates tied to this upgrade. - Excluded scope: frontend runtime/dependency upgrades, unrelated refactors, and feature development beyond compatibility work. **Further Considerations** 1. SQLAlchemy/SQLModel are not currently declared in backend metadata; implementation should confirm whether this task introduces them now or only future-proofs compatibility language. 2. If any pinned package lacks 3.14-compatible wheels, choose between pin adjustments or temporary source-build allowance in CI with explicit documentation. 3. If CI base image provisioning source (deadsnakes/PPA) lags for 3.14 patch releases, consider a fallback strategy (official Python images) to avoid pipeline downtime.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
afk
Autonomous-friendly issue
 algorithm
Selection logic
 api
API contract
 backend
Backend related
 database
Database related
 devex
Developer experience
 docs
Documentation
 epic
Top-level planning item
 frontend
Frontend related
 hitl
Requires human-in-the-loop decision
 ingestion
Ingestion/sync
 ops
Operations
 performance
Performance
 realtime
Realtime/eventing
 release
Release readiness
 security
Security
 task
Implementation ticket
 testing
Testing
 ui
UI/UX
No Label afk backend devex task
Milestone
No items
No Milestone E1 - Platform Baseline and Standards Upgrade
Projects
Clear projects
No project
Assignees
Clear assignees
copilotcoder darkhelm renovate-bot repository-bot
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DarkHelm.org/plex-playlist#10
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?