fix(ci): raise the declared Python floor to 3.11

[guill]

Stack of 6 — review bottom-up (this is 800)

1. fix(ci): raise the declared Python floor to 3.11 #800 — fix(ci): raise the Python floor to 3.11 — base main   ← this PR
2. feat(build): add packaging, sync and Builder client primitives #801 — feat(build): packaging, sync and Builder client primitives
3. feat(build)!: replace the legacy build and distribution surface #802 — feat(build)!: replace the legacy build and distribution surface (breaking)
4. feat(deploy): add the deployment control plane #803 — feat(deploy): the deployment control plane
5. feat(deploy): add the asset and job data-plane clients #804 — feat(deploy): the asset and job data-plane clients
6. feat(deploy): add comfy deploy run #805 — feat(deploy): comfy deploy run

Each PR is based on the branch below it, so its own diff is only its commit. Merge in order.

TL;DR: comfy_cli has never been importable on Python 3.10 — typing.assert_never (build_spec.py) and enum.StrEnum are 3.11 additions imported at module scope — so the declared >=3.10 floor and the 3.10 CI matrix have been describing a configuration that never worked. This raises the floor to 3.11 everywhere it is written down.

Bottom of a six-PR stack; nothing below it. Review from the bottom up.

What changed

• pyproject.toml: requires-python, the classifiers and ruff's target-version all move to 3.11.
• workflows: every job pinned to "follow the min version in pyproject.toml" moves with it, so the test job that runs on the floor is what keeps the floor honest.
• lockfiles (uv.lock, pylock.toml): re-resolved against the new floor.
• 3.10 compatibility shims: retargeting ruff to py311 makes it see the shims the new floor obsoletes. Adopts datetime.UTC, and drops the sys.version_info >= (3, 11) guard around -P so sys.path is now hardened unconditionally.

One deliberate omission: UP042 stays off. Switching the nine (str, Enum) Typer choice types to StrEnum changes str(OS.WINDOWS) from "OS.WINDOWS" to "windows" — that is user-visible output, not a lint fix.

Validation

• uv run --locked --extra dev pytest -q at this commit: 6073 passed, 38 skipped, 1 failed.
• The one failure is test_build.py::test_scan_custom_nodes_records_repo_and_ref, and it is pre-existing and environmental, not from this change. It reproduces identically on a clean origin/main checkout. Cause: a local url.git@github.com:.insteadOf https://github.com/ git rewrite on the dev machine — the fixture writes an https:// remote and reads back the git@ form, so the literal-URL assertion fails. CI runners carry no such rewrite.
• ruff check . / ruff format --diff . clean at CI's pin (0.15.15).

Contradicts: nothing.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5dffe5f1-39d0-4ce2-a486-87e0444d0c0d

📥 Commits

Reviewing files that changed from the base of the PR and between c1fa1f4 and dbf4429.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (24)

• .github/workflows/build-and-test.yml
• .github/workflows/publish_package.yml
• .github/workflows/pytest.yml
• .github/workflows/refresh-cql-catalogs.yml
• AGENTS.md
• CONTRIBUTING.md
• README.md
• comfy_cli/auth/store.py
• comfy_cli/cloud/command.py
• comfy_cli/command/jobs.py
• comfy_cli/command/launch.py
• comfy_cli/command/outdated.py
• comfy_cli/command/project.py
• comfy_cli/command/templates.py
• comfy_cli/download_state.py
• comfy_cli/jobs_state.py
• comfy_cli/knowledge.py
• comfy_cli/output/branding.py
• comfy_cli/project.py
• pylock.toml
• pyproject.toml
• tests/comfy_cli/command/test_logs.py
• tests/comfy_cli/command/test_model_download_background.py
• tests/comfy_cli/output/test_renderer.py

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The project now requires Python 3.11. CI workflows, documentation, metadata, and lock data reflect this requirement. Runtime timestamp handling uses datetime.UTC, and background refreshes always use Python’s -P flag. Related tests were updated.

Changes

Python 3.11 support contract

Layer / File(s)	Summary
Python version metadata and lint configuration pyproject.toml	The minimum Python version is 3.11. The Python 3.10 classifier was removed. Ruff targets py311 and ignores UP042.
Dependency lock data pylock.toml	The lock file now requires Python 3.11, removes Python 3.10 wheels and exceptiongroup, adds packages, and updates several package versions.
CI and setup documentation .github/workflows/*, AGENTS.md, CONTRIBUTING.md, README.md	CI setup steps and documented installation requirements now use Python 3.11.

Runtime modernization

Layer / File(s)	Summary
UTC timestamp handling comfy_cli/auth/store.py, comfy_cli/cloud/command.py, comfy_cli/command/*, comfy_cli/download_state.py, comfy_cli/jobs_state.py, comfy_cli/knowledge.py, comfy_cli/output/branding.py, comfy_cli/project.py	UTC timestamp creation and conversion now use the UTC constant instead of timezone.utc.
Background refresh invocation comfy_cli/command/templates.py	Gallery refresh subprocesses now always include Python’s -P flag.

Test alignment

Layer / File(s)	Summary
UTC-based timestamp assertions tests/comfy_cli/command/test_logs.py, tests/comfy_cli/command/test_model_download_background.py, tests/comfy_cli/output/test_renderer.py	Tests now construct timestamps with UTC and retain their existing expected values.

Suggested reviewers: mattmillerai

Merge Risk: ⚪ Minimal · up to dbf44

This PR raises the supported Python version and updates the related CI and metadata. No actionable merge-blocking risk remains at the current head after normal checks and review.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/03b-python-floor

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch stack/03b-python-floor

---

_{Comment @coderabbitai help to get the list of available commands.}

[guill]

Closing this in favour of making the new code 3.10-compatible instead.

The premise no longer holds. This PR argued that comfy_cli could not import on 3.10 at all, so the declared >=3.10 floor and the 3.10 CI matrix were describing a configuration that never worked. That was true at f027859, but #798 has since fixed it. I verified empirically against current main (c1fa1f4) on CPython 3.10.20:

• all 135 modules compile and import — zero failures
• no 3.11-only stdlib feature anywhere in comfy_cli/ or tests/
• the full suite passes: 6096 passed, 38 skipped

(The one failure in that run is test_scan_custom_nodes_records_repo_and_ref, caused by a local url.git@github.com:.insteadOf https://github.com/ rewrite on my machine — it reproduces on a clean main checkout and is absent on CI runners.)

So main is genuinely 3.10-clean today. Raising the floor would drop a working configuration rather than stop a lie, and that is a policy decision rather than the bug fix this PR was written as.

What happened instead. The rest of the stack (#801–#805) has been rebased onto c1fa1f4 and made 3.10-compatible in the commit that introduces each construct:

Construct	Fix	Where
typing.assert_never	→ typing_extensions (the pattern #798 established)	8 files across all five PRs
enum.StrEnum	→ (str, Enum), the existing house pattern	deploy_events.py (#804)
typing.NotRequired + TypedDict	→ typing_extensions (both, so key computation stays correct on 3.10)	test_deploy_run.py (#805)
datetime.UTC	→ timezone.utc	deploy_resolve.py (#803)

typing-extensions>=4.7 was already a declared runtime dependency, so nothing new is added.

Every commit in the stack now passes the full suite on both 3.10 and 3.11, and ruff check / ruff format --diff are clean at CI's pinned 0.15.15 with target-version = "py310".

The stack/03b-python-floor branch is left in place in case the team wants to revisit dropping 3.10 as a deliberate, standalone policy decision — that is a separate conversation from this stack, and #798 suggests the current preference is to keep 3.10 working.