feat(python): require Python 3.11 or newer #732

Context

Python 3.10 has an October 2026 end-of-life schedule. Current repository code emits an import-time FutureWarning on Python 3.10 announcing removal in the next minor release. This issue tracks that repository-specific minor release; it does not assume a shared release number for the original deprecation.

Acceptance Checklist

Metadata and tooling

• requires-python = ">=3.11,<3.15"; remove the 3.10 classifier
• Hatch default env python, mypy python_version, ruff target-version = "py311"
• Built wheel and sdist metadata declare a Requires-Python range semantically equivalent to >=3.11,<3.15; validate the supported range rather than serialized specifier order

Code

• Remove the Python-3.10-only import warning and retire or replace its obsolete warning tests; preserve unrelated warning and regression coverage
• Replace the obsolete warning contract with metadata/artifact regression coverage: a clean Python 3.10 environment rejects the newly built wheel because of Requires-Python, while Python 3.11 installs it and passes pip check plus an import or CLI smoke check
• Review newly applicable py311 Ruff findings; use only safe, behavior-preserving fixes. Behavioral changes require separate justification and regression coverage, not blanket autofixes:
  • timezone.utc → datetime.UTC (UP017, 3 sites)
  • Review WarningCode(str, Enum) (UP042) without assuming a formatting bug: the current class already defines __str__() returning self.value. StrEnum is optional simplification, not required for dropping 3.10. Preserve str(), f-string, JSON serialization, equality, and public warning-code values with regression coverage if converted; otherwise retain the implementation and document any lint exception.
  • _warnings.py docstring "3.10+" → 3.11+

CI

• Test matrix 3.11–3.14; minimum-dependency lane on 3.11
• Move the coverage / Codecov "canonical cell" from 3.10 to 3.11 (otherwise the coverage gate silently stops running)
• Lint/type-check, docs, publish and other fixed-interpreter jobs on 3.11
• Coverage cell condition 3.10 && af latest → 3.11
• e2e-azure.yml python_version input default and fallbacks → 3.12
• screenshots.yml, publish-pypi.yml off 3.10

Docs

• Remove the README deprecation notice; update badges in all 4 READMEs, SUPPORT.md, AGENTS.md, DESIGN.md, llms.txt, llms-full.txt and docs/ to 3.11+
• Keep historical CHANGELOG entries unchanged
• Remove the 3.10 column from the azure-functions × Python table in all 4 READMEs
• CONTRIBUTING.md (make install may select 3.10)
• 0.28.0 shipped as a minor while still supporting 3.10; this release fulfils the announced drop

Release

• Commit feat(python): require Python 3.11 or newer with a Release-As: 0.29.0 footer
• After publishing: on Python 3.10 an unpinned install resolves 0.28.0 and ==0.29.0 is rejected; on Python 3.11 0.29.0 installs, imports and passes pip check

Out of scope

• Raising azure-functions or other runtime dependency floors
• Optional modernization beyond the ruff py311 fixes
• tools/lint_hatch_matrix.py test fixtures that use "3.10" as sample data

Additional scope from comprehensive Python 3.11 audit

Checked candidates: asyncio.timeout/TimeoutError, TaskGroup, ExceptionGroup/except*/add_note, typing.Self, datetime.UTC, tomllib, hashlib.file_digest, StrEnum, Required/NotRequired, typing backports and version branches. Only the items below apply; the rest were verified absent or retained because they would change behaviour.

• UTC correction: Ruff reports 8 timezone.utc sites across 5 files (not 3); convert all

• Apply the UP037 fix in scripts/check_screenshots.py and use hashlib.file_digest in its single-file _image_hash()

• StrEnum: WarningCode (public; add regression tests for str(), f-string, JSON, equality and .value), example ReportFormat and test Color; verify schema/serialization output is unchanged

• publish-pypi.yml cookbook gate jobs still bootstrap with setup-python 3.10; move both to 3.11 (cookbook Hatch env is now 3.11, cookbook#300)

Release verification (0.29.0)

Implemented in #733 (independent review passed) and released via #734.

• Tag, GitHub Release and PyPI report 0.29.0 (Requires-Python >=3.11,<3.15, wheel + sdist); all publish gates incl. cookbook smokes and Azure certification passed.
• Python 3.10: unpinned install resolves 0.28.0; ==0.29.0 rejected by Requires-Python.
• Python 3.11: clean install with validation 0.14.0 and logging 0.14.0, pip check OK, no FutureWarning; generated spec validates with openapi-spec-validator; WarningCode str/f-string/JSON unchanged.
• A pre-existing route-documentation issue for the innermost decorator order was found during verification (same on 0.28.0) and filed separately.