|
| 1 | +"""The Python floor: the lowest version the suite actually runs on, kept honest in CI. |
| 2 | +
|
| 3 | +`requires-python` was `>=3.14.4` from the project's first day, which said "the interpreter I |
| 4 | +develop on" rather than "the interpreter the code needs" -- and Python 3.14 is new enough that |
| 5 | +many contributors do not have it, several distributions do not package it, and some CI images |
| 6 | +lag. A floor that bars contributors silently costs them: they try, fail to build, and leave |
| 7 | +without opening an issue (#283). |
| 8 | +
|
| 9 | +So the floor was measured, not guessed. The full suite was run at each step down: |
| 10 | +
|
| 11 | +- **3.13, 3.12, 3.11**: 2,788 passed / 1 skipped -- identical to 3.14, nothing requires it. |
| 12 | +- **3.10**: collection fails, `ImportError: cannot import name 'assert_never' from 'typing'` -- |
| 13 | + the one concrete binding constraint found. `assert_never` is 3.11+. |
| 14 | +
|
| 15 | +The decision: the floor is **3.11**, the lowest passing version; development stays pinned to |
| 16 | +3.14.4 via `.python-version`; CI runs the suite on 3.11 so the floor stays true instead of |
| 17 | +rotting back into an untested claim. These tests pin all three halves of that decision -- the |
| 18 | +declared floor in every distribution, the binding-feature evidence that justifies it, and the |
| 19 | +CI leg that verifies it -- because each is a way the decision can silently come undone: a |
| 20 | +seventh distribution added with a different floor, the `assert_never` imports disappearing |
| 21 | +(which means the floor COULD drop and the recorded reason is stale), or the CI matrix losing |
| 22 | +its floor leg. |
| 23 | +""" |
| 24 | + |
| 25 | +from __future__ import annotations |
| 26 | + |
| 27 | +import re |
| 28 | +import tomllib |
| 29 | +from pathlib import Path |
| 30 | + |
| 31 | +_ROOT = Path(__file__).resolve().parents[1] |
| 32 | + |
| 33 | +#: The floor, as decided in #283. One value in every distribution, like the version pins. |
| 34 | +_FLOOR = ">=3.11" |
| 35 | + |
| 36 | + |
| 37 | +def _pyprojects() -> dict[str, dict]: |
| 38 | + """distribution name -> parsed `pyproject.toml`, for the root and every workspace member.""" |
| 39 | + found = {} |
| 40 | + for path in [_ROOT / "pyproject.toml", *sorted((_ROOT / "packages").glob("*/pyproject.toml"))]: |
| 41 | + data = tomllib.loads(path.read_text()) |
| 42 | + found[data["project"]["name"]] = data |
| 43 | + return found |
| 44 | + |
| 45 | + |
| 46 | +def test_every_distribution_declares_the_same_floor(): |
| 47 | + """`requires-python = ">=3.11"` everywhere -- a mixed floor is a mixed install waiting. |
| 48 | +
|
| 49 | + The workspace is cut in one build; a member declaring a different floor than its siblings |
| 50 | + means an environment that satisfies one requirement and rejects another, which is the |
| 51 | + version-pin failure mode `test_packaging.py` guards, one field over. |
| 52 | + """ |
| 53 | + floors = {name: data["project"]["requires-python"] for name, data in _pyprojects().items()} |
| 54 | + wrong = {name: floor for name, floor in floors.items() if floor != _FLOOR} |
| 55 | + assert not wrong, ( |
| 56 | + f"these distributions declare a Python floor other than {_FLOOR!r}: {wrong}. The floor " |
| 57 | + "is one decision for the whole workspace (see tests/test_python_floor.py's docstring " |
| 58 | + "for the measured reasoning)" |
| 59 | + ) |
| 60 | + |
| 61 | + |
| 62 | +def test_the_binding_feature_that_sets_the_floor_still_exists(): |
| 63 | + """The floor's REASON must stay true: `assert_never` (3.11+) must still be imported. |
| 64 | +
|
| 65 | + 3.10 fails collection on exactly this import. If it ever disappears from the codebase, the |
| 66 | + floor could drop further and this test's recorded justification is stale -- re-measure |
| 67 | + downward rather than leaving a floor pinned to a feature nobody uses. |
| 68 | + """ |
| 69 | + importers: list[str] = [] |
| 70 | + for base in (_ROOT / "keel", _ROOT / "packages", _ROOT / "tests"): |
| 71 | + for path in base.rglob("*.py"): |
| 72 | + if re.search(r"import\s+.*\bassert_never\b", path.read_text()): |
| 73 | + importers.append(str(path.relative_to(_ROOT))) |
| 74 | + assert importers, ( |
| 75 | + "nothing imports `assert_never` any more -- the 3.11 floor's binding constraint is " |
| 76 | + "gone; re-run the suite on 3.10 and lower the floor if it now passes" |
| 77 | + ) |
| 78 | + |
| 79 | + |
| 80 | +def test_ci_runs_the_suite_on_the_floor_so_it_stays_true(): |
| 81 | + """The `test` job must have a 3.11 leg, or the floor is an untested claim. |
| 82 | +
|
| 83 | + Measured floors rot: a dependency or a line of code starts needing something newer and |
| 84 | + `>=3.11` becomes a lie that only manifests on a contributor's machine. The CI leg is what |
| 85 | + converts the floor from a declaration into an invariant. It lives in the `test` job's |
| 86 | + matrix on purpose -- a job of its own would report a status context nothing requires, |
| 87 | + which is exactly how #268's mypy gate came undone before it existed. |
| 88 | + """ |
| 89 | + ci = (_ROOT / ".github" / "workflows" / "ci.yml").read_text() |
| 90 | + assert "3.11" in ci, ( |
| 91 | + "ci.yml no longer runs on Python 3.11 -- the declared floor has lost its CI leg; " |
| 92 | + "restore the matrix entry or re-measure the floor and update it everywhere" |
| 93 | + ) |
| 94 | + |
| 95 | + |
| 96 | +def test_the_floor_is_stated_where_a_contributor_reads_it(): |
| 97 | + """README and CONTRIBUTING must say 3.11, so the floor is found in docs, not the resolver. |
| 98 | +
|
| 99 | + 'A contributor hitting the floor gets a clear message rather than a confusing resolver |
| 100 | + error' (#283) starts with the floor being low enough to be rare and visible enough to be |
| 101 | + self-diagnosing when hit. |
| 102 | + """ |
| 103 | + readme = (_ROOT / "README.md").read_text() |
| 104 | + contributing = (_ROOT / "CONTRIBUTING.md").read_text() |
| 105 | + assert "3.11" in readme, "the README's setup section must state the 3.11 floor" |
| 106 | + assert "3.11" in contributing, "CONTRIBUTING.md must state the 3.11 floor" |
0 commit comments