Updating Python Support

Updating Python Support

Change the supported Python range without erasing useful history or leaving the site, package metadata, CI, and tests disagreeing about what is supported.

Establish the Transition

1. Identify the version being dropped, the version being added, or both.
2. Verify against official Python sources that:
   • a dropped version has reached its official EOL date; and
   • an added version has reached its official final release date.
3. Do not add alpha, beta, or release-candidate versions. Do not drop a version before EOL.
4. Find the latest patch release for the new oldest and newest supported minor versions. CI pins exact patch releases, not minor-only versions.
5. Record the old and new inclusive support ranges before editing. Use these as the audit criteria throughout the change.

Prefer python.org release and lifecycle pages, the released version's official "What's New" document, and the matching released CPython branch. Do not use CPython main as evidence for a final release.

Update Package and Tool Metadata

Edit pyproject.toml as one coherent source-of-support change:

• Raise project.requires-python when the minimum supported version changes.
• Remove the dropped Programming Language :: Python :: 3.x classifier.
• Add the new final version's classifier.
• Keep the classifiers continuous across the supported range.
• Raise Ruff's target-version when it names the dropped minimum version.

Search for other tool-specific minimum or target versions before assuming these are the only settings. Regenerate uv.lock with uv lock; never hand-edit its requires-python value or dependency markers. Review dependency resolution and conditional markers introduced or removed by the new range.

Update Public API Manifests

Keep scripts/api_manifests/python-<major>.<minor>.json aligned with the supported minor versions:

• Delete the corresponding manifest when dropping a version.
• Add a manifest when adding a version. Follow the inventory download and generation workflow in scripts/api_manifests/README.md, using the matching interpreter and the official documentation for the final release. Generate the file with scripts/build_api_manifest.py; do not copy another version's manifest or invent entries manually.
• Update the supported-version list in that README and any manifest tests that enumerate the supported versions.

Review the generated diff and run tests/test_api_manifest.py and tests/test_audit_public_api.py. Confirm the audit loads the matching manifest on both new support boundaries; a missing manifest leaves classification pending and does not establish zero API gaps. Keep historical documentation pages even when their version's audit manifest is removed.

Update CI Boundary Versions

In .github/workflows/deploy.yml, keep the timing matrix on exactly the oldest and newest supported minor lines, each pinned to its latest patch release.

• Replace the old lower boundary when support is dropped.
• Replace the old upper boundary when support is added.
• Preserve fail-fast: false and the patched-Python enforcement.
• Re-read nearby comments and version-specific skip logic. Update comments that describe the support boundaries, but retain historical examples that remain true.
• Confirm every pinned patch includes any security or correctness fix that the tests require. The latest patch should satisfy this; verify rather than infer.

Audit Every Version Reference

Search the repository for both old boundary versions and the new version before editing. Use exact forms broad enough to find prose, config, paths, and symbols, for example:

rg -n '3\.10|3\.14|py310|py314|3\.10[–-]3\.14' \
  --glob '!uv.lock' --glob '!site/**' --glob '!.venv/**'

Adapt the numbers and search separately when a combined expression would hide results. Inspect every match; never bulk-replace version numbers.

Update a match when it expresses the current supported set or a support boundary, including:

• site introductions, support badges, metadata, and docs/llms.txt;
• English and translated landing pages;
• CI matrices, tool targets, test matrices, skip conditions, and comments that promise coverage of the oldest or newest supported version;
• version overview tables, EOL status, quick links, recommendations, and other text that claims which versions this project currently supports.

Retain a match when it is a historical or feature boundary that remains true, including:

• "added in Python 3.x", "removed in Python 3.x", or a PEP's release;
• an algorithm or behavior that changed at a named version;
• historical version guides and factual compatibility notes;
• ordinary numeric example data such as the float 3.14.

The search is an investigation list, not an edit list. Explain any ambiguous match by what it means, not merely by whether it contains the old number.

Reconcile Documentation When Dropping a Version

Do not remove documentation pages for the dropped version or for modules that the dropped version contained. Version guides remain useful historical docs.

Re-evaluate version-gated statements in builtin and module pages. If the dropped line was the only supported version with old behavior or without a feature, update current tables, examples, recommendations, and tests to describe the new supported range. Keep concise historical notes when they explain when a feature was added or removed; do not preserve obsolete branches as though users still need to target them.

Examples of changes to investigate:

• a table with separate behavior for the dropped minimum and all newer lines;
• a workaround needed only before a feature available throughout the new range;
• a module or API removed in one of the still-supported versions;
• a test whose skip or expected result existed only for the dropped line.

Document a Newly Supported Version

Read the final release's official "What's New", deprecated/removed modules, and library changes. Build an inventory of changes that affect this repository:

• new builtins, standard-library modules, classes, methods, and operations;
• removed APIs or modules;
• changed behavior, laziness, allocation, caching, or complexity;
• performance changes only when they alter an asymptotic bound or a practical recommendation, not merely a measured constant factor.

For each relevant item:

1. Update the owning builtin or module page and its claim tests.
2. Add a missing module page only when the new final release introduces a relevant module; load documenting-complexity-modules for that work.
3. Load testing-complexity-claims for every added or changed complexity or behavioral claim.
4. Add docs/versions/py3xx.md for the new final release and integrate it into docs/versions/index.md, mkdocs.yml, and docs/llms.txt.
5. Update support-range landing-page text in every existing locale. Missing translations of a new page may continue to fall back to English.

Do not turn "What's New" into a generic release summary. Include only changes that help readers understand operation cost, availability, or the choice between APIs, and verify each claim against the released interpreter and source.

Preserve Translation and Audit Integrity

English is the source of truth. For every edited English page with an existing translation:

1. Faithfully mirror the content change in each translation.

2. Keep fenced code byte-for-byte identical to English.

3. Preserve heading levels, table shape, and link targets.

4. Update hashes only after content matches:

   uv run python scripts/validate_translations.py --update-hashes <locale>
   

Never hand-edit source_sha. If a faithful translation cannot be made, leave it explicitly stale rather than certifying incorrect content.

When adding documentation pages, run make audit to print live coverage without writing files. Update the newest-version coverage check in CI alongside the supported range, and run tests/test_documentation_coverage.py on that exact patch release. Preserve historical navigation targets when modules are removed.

Verify Both Support Boundaries

Ordinary work runs the pinned interpreter and leaves the matrix to CI. A change to the supported range is the exception: the pins themselves are what is under test, so both new boundaries are installed and run here.

Install and test the exact oldest and newest patch releases selected for CI. Keep temporary environments outside the worktree and run sequentially so timing tests do not compete for CPU:

UV_PROJECT_ENVIRONMENT=/tmp/python-oldest uv run --python <oldest-patch> --frozen \
  pytest -m 'not timing'
UV_PROJECT_ENVIRONMENT=/tmp/python-oldest uv run --python <oldest-patch> --frozen \
  pytest -m timing
UV_PROJECT_ENVIRONMENT=/tmp/python-newest uv run --python <newest-patch> --frozen \
  pytest -m 'not timing'
UV_PROJECT_ENVIRONMENT=/tmp/python-newest uv run --python <newest-patch> --frozen \
  pytest -m timing

Run edited documentation code blocks on both boundaries when availability or behavior differs by version. Confirm version-specific tests execute rather than silently skip on the boundary they are meant to cover.

Finish with make check. Then inspect the final diff and repeat the version searches to confirm that:

• metadata, lockfile, CI, tests, site text, and navigation agree;
• API manifests exist for exactly the supported minor versions, with dropped versions removed and newly supported versions generated from official inventories;
• no current support statement still names the old range;
• no historical fact or documentation page was removed merely because a version reached EOL;
• new-version documentation is evidence-backed and scoped to relevant changes;
• translated pages are current or honestly marked stale; and
• no temporary environments or generated files remain in the worktree.