CI/docs Python modernization with explicit 3.8 compatibility split

[lmeyerov]

Summary

Modernize CI/docs Python interpreter choices while preserving library backward compatibility.

Policy (explicit)

• PyGraphistry runtime backward compatibility SHOULD remain Python 3.8+ for now.
• CI SHOULD keep explicit compatibility testing across the known-supported matrix (currently 3.8 .. 3.14, where working).
• CI jobs that are primarily operational/build/docs/tooling lanes should avoid EOL interpreters and move to maintained versions (prefer newer where feasible).

Why

• Python 3.8 is EOL, so non-compat lanes pinned to 3.8 create avoidable infra risk.
• We still need confidence in older-runtime compatibility for users.
• Splitting compatibility lanes from operational lanes gives both safety and forward motion.

Scope for this issue

1. Inventory and classify Python-version usage across CI/docs/packaging as:
   • compatibility lanes (must include old+new supported versions),
   • operational lanes (prefer maintained/current interpreters),
   • policy declarations (python_requires, docs claims, tooling targets).
2. Land narrow, reviewable PRs that modernize operational lanes first.
3. Keep compatibility lanes broad and explicit.
4. Re-check assumptions periodically, since what works on latest Python can improve over time.

Current progress

• PR ci: remove unnecessary Python setup from test-readme #1111 removed unnecessary Python setup from test-readme.
• PR ci: move test-build lane from Python 3.8 to 3.14 #1112 moves test-build from fixed Python 3.8 to Python 3.10 while keeping explicit 3.8 compatibility lanes elsewhere.

Proposed phased approach

Phase A: Operational lane modernization (no support-floor change)

• Move fixed operational/build/docs lanes off EOL interpreters.
• Prefer 3.10+ (or newer) for non-compat jobs.
• Keep diffs small and behavior-focused.

Phase B: Compatibility matrix stewardship

• Preserve and regularly validate compatibility lanes across declared range (3.8 .. 3.14, where known working).
• Add/adjust matrix entries as real compatibility evolves.

Phase C: Future policy bump (optional, separate decision)

• If/when support floor is raised, coordinate updates across:
  • python_requires, classifiers, docs claims,
  • tooling targets (pyproject),
  • lockfile generator + CI matrices.

Deliverables

• Tracked mapping of lane type -> Python-version intent.
• Sequence of PRs modernizing operational lanes.
• Clear distinction between compatibility testing and operational execution lanes.

Related

• ci: port ReadTheDocs build to uv lockfile #1074 (RTD lockfile work)
• ci: remove unnecessary Python setup from test-readme #1111
• ci: move test-build lane from Python 3.8 to 3.14 #1112

[lmeyerov]

Investigation update + first increment landed as PR #1112.

Inventory summary (source-of-truth files)

• Packaging policy still declares 3.8 floor:
  • setup.py: python_requires='>=3.8'
  • pyproject.toml: target-version = "py38"
• Docs still claim Python 3.8+:
  • docs/source/install/quick.rst
  • docs/source/cheatsheet.md
• CI still has intentional 3.8 matrix lanes for compatibility testing.
• Lockfile generator is coupled to those lanes (bin/generate-lockfiles.sh includes 3.8 in ALL_VERSIONS and profile mins).

Immediate low-risk increment

• PR ci: move test-build lane from Python 3.8 to 3.14 #1112 updates only test-build:
  • runner 3.8 -> 3.10
  • lockfile build-py3.8.lock -> build-py3.10.lock
• Rationale: test-build is packaging validation and does not need to be anchored to the EOL interpreter when explicit 3.8 compatibility lanes remain elsewhere.

Proposed phased direction

• Track A (no support-floor change): remove unnecessary fixed 3.8 pins while keeping explicit 3.8 compatibility matrices.
• Track B (explicit support-floor bump): separate policy decision + coordinated updates across packaging/docs/CI/lockfile generation.

[lmeyerov]

Update: investigated prior CI timing references and completed a concrete 3.14 trial for test-build.

Prior references

• ci: cache generate-lockfiles to skip ~47s on unchanged deps (#1076) #1083: lockfile-cache optimization data (generate-lockfiles cold ~26s, hit ~6s).
• ci: speed up job matrix (issue #1082) #1084: broad matrix optimization and successful py3.14 usage in multiple lanes.

New trial result (PR #1112)

• Moved test-build to setup-python 3.14 + build-py3.14.lock.
• Full CI is green after correcting an initial wiring mistake.

Observed test-build timing:

• prior 3.10 run: ~14s / 18s
• corrected 3.14 run: ~19s / 20s

Interpretation:

• 3.14 is slightly slower for this specific lane, but stable and green.
• The speed delta is small, so policy preference (operational lanes on maintained/latest Python) can reasonably take precedence over a few seconds.

This keeps compatibility policy intact (3.8+ runtime support + explicit 3.8 compatibility lanes), while modernizing a non-compat operational lane.