demo-oidc/docs/superpowers/plans/2026-07-08-python-3.14-deps-update.md

Python 3.14 + Dependency Update Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Update the project to run on Python 3.14 with up-to-date dependencies, removing the unused python-jose.

Architecture: Pure config/dependency bump. No application code changes. Verification is by running the existing test suite under a fresh Python 3.14 venv with the bumped dependencies, plus a Docker build.

Tech Stack: Python 3.14, FastAPI, uvicorn, pyjwt, requests, cryptography, pytest, Docker (alpine).

Global Constraints

• Python target: 3.14 (local interpreter at /opt/homebrew/bin/python3.14, version 3.14.6)
• Version specifier style: >= lower-bound floors (no exact pinning)
• Drop python-jose entirely (unused, unmaintained)
• No changes to main.py, generate_favicon.py, templates, or the code//source/ duplicate dirs
• Keep alpine base image, multi-stage build, non-root user, healthcheck, and existing CMD in Dockerfile

---

Task 1: Bump dependencies, fix Dockerfile, add .python-version

Files:

• Modify: requirements.txt
• Modify: requirements-test.txt
• Modify: Dockerfile (lines 2 and 32)
• Create: .python-version

Interfaces:

• Consumes: nothing (first task)

• Produces: a Python 3.14-compatible dependency set and Docker image

• Step 1: Replace requirements.txt contents

fastapi>=0.115.0
uvicorn>=0.30.0
pyjwt>=2.9.0
requests>=2.32.0
cryptography>=44.0.0

• Step 2: Replace requirements-test.txt contents

pytest>=8.3.0
pytest-cov>=5.0.0
coverage>=7.4.0
httpx>=0.27.0
asgi_lifespan>=2.0.0

• Step 3: Edit Dockerfile line 2 — bump base image

Change:

FROM python:3.9-alpine AS python-base

To:

FROM python:3.14-alpine AS python-base

• Step 4: Edit Dockerfile line 32 — fix hardcoded site-packages path

Change:

COPY --from=builder /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages

To:

COPY --from=builder /usr/local/lib/python3.14/site-packages /usr/local/lib/python3.14/site-packages

• Step 5: Create .python-version

Contents:

3.14

• Step 6: Recreate venv and install deps

Run:

rm -rf venv
python3.14 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt -r requirements-test.txt

Expected: exit 0, no errors. cryptography should install (wheel preferred; build deps present in Dockerfile for the container case).

• Step 7: Run the test suite

Run: ./run_tests.sh Expected: all tests pass, exit 0, coverage report generated in htmlcov/. No new failures vs. baseline.

• Step 8: Verify Docker build (if Docker is available)

Run: docker build -t oidc-validator . Expected: exit 0. (If Docker is not running/installed, note this and skip — it is not a blocker for the local change.)

• Step 9: Commit

git add requirements.txt requirements-test.txt Dockerfile .python-version
git commit -m "build: bump to Python 3.14 and update dependencies"