Coverage for packages/workshop/src/livery/workshop/_pythons.py: 97%

Measured by coverage.py 7.16.2 on CPython 3.14 while the suites of tests, packages/workshop, packages/extensions/ty, packages/extensions/ruff, packages/extensions/python, packages/extensions/pytest, packages/extensions/pyrefly, packages/extensions/nanobind, packages/extensions/mypy, packages/extensions/mkdocstrings, packages/extensions/lfs, packages/extensions/docs, packages/extensions/cpp, packages/extensions/coverage, packages/extensions/conan, packages/extensions/cmake, packages/extensions/claude, packages/extensions/clang-tidy, packages/extensions/clang-format, packages/extensions/changelog, packages/extensions/basedpyright ran.

1"""Python version facts, derived from the workspace, never asked.
2
3The floor comes from the root ``pyproject.toml``'s ``requires-python``
4bound; the newest supported minor is the workshop's own declaration.
5The CI matrix is the pair, so a new Python reaches every instance
6through a wheel bump, never an instance edit.
7"""
8
9from __future__ import annotations(empty)
10
11import re(empty)
12import sys(empty)
13import tomllib(empty)
14from pathlib import Path(empty)
15
16from livery.footman import fail, prog(empty)
17from livery.workshop._contract import load_contract(empty)
18
19
20def scripts_dir(venv: Path) -> Path:(empty)
21 """Name *venv*'s executables directory: ``Scripts`` on Windows, ``bin`` elsewhere.
22
23 The running platform decides: a venv is used on the machine that
24 made it. Nothing is read from the disk, so the venv may not exist
25 yet.
26
27 Args:
28 venv: The venv's directory.
29
30 Returns:
31 The directory its interpreter and its console scripts are in.
32 """
33 return venv / ("Scripts" if sys.platform == "win32" else "bin")
34
35
36def venv_python(venv: Path) -> Path:(empty)
37 """Name *venv*'s interpreter on this platform.
38
39 ``python.exe`` in [livery.workshop.scripts_dir][] on Windows, and
40 ``python`` there elsewhere. Nothing is read from the disk, so the
41 venv may not exist yet.
42
43 Args:
44 venv: The venv's directory.
45
46 Returns:
47 The interpreter's path.
48 """
49 return scripts_dir(venv) / ("python.exe" if sys.platform == "win32" else "python")
50
51
52def runner_script(venv: Path) -> Path:(empty)
53 """The console script in *venv* of the runner this process runs as.
54
55 Named as the running brand names its runner, with ``.exe`` on
56 Windows, so a branded runner hands work to itself in another
57 environment.
58 """
59 name = prog()
60 return scripts_dir(venv) / (f"{name}.exe" if sys.platform == "win32" else name)
61
62
63#: The oldest Python a workspace being born supports; the floor once
64#: its ``pyproject.toml`` exists and declares one.
65FLOOR_DEFAULT = "3.11"(empty)
66
67#: The newest minor the workshop tests against. Raising it widens
68#: every instance's CI matrix on its next wheel bump.
69NEWEST_SUPPORTED = "3.14"(empty)
70
71
72def python_floor(root: Path) -> str:(empty)
73 """The workspace's Python floor.
74
75 The lower bound of the root ``pyproject.toml``'s
76 ``requires-python``;
77 livery.workshop._pythons.FLOOR_DEFAULT when the file or the
78 bound is absent, which is what a workspace being born looks
79 like.
80 """
81 pyproject = root / "pyproject.toml"
82 if not pyproject.is_file():
83 return FLOOR_DEFAULT
84 data = tomllib.loads(pyproject.read_text("utf-8"))
85 spec = str(data.get("project", {}).get("requires-python", ""))
86 match = re.search(r">=\s*(\d+\.\d+)", spec)
87 return match.group(1) if match else FLOOR_DEFAULT
88
89
90def _minor(version: str) -> tuple[int, int]:(empty)
91 major, _, minor = version.partition(".")
92 return int(major), int(minor)
93
94
95#: The contract key that overrides the derived matrix, born kebab-case.
96PYTHONS_KEY = "python-versions"(empty)
97
98_VERSION_RE = re.compile(r"^\d+\.\d+t?$")(empty)
99
100
101def declared_pythons(root: Path) -> list[str] | None:(empty)
102 """The contract's ``[ci] python-versions``, or ``None`` when undeclared.
103
104 Refuses a declaration that is not a non-empty list of version
105 strings (``3.14``, or ``3.14t`` for a free-threaded build), naming
106 the key: an empty list would emit a matrix with no leg, and a
107 stray value would reach the runner as a python it cannot find.
108 """
109 contract = root / "workshop.toml"
110 if not contract.is_file():110 ↛ 111line 110 didn't jump to line 111 because the condition on line 110 was never true
111 return None
112 ci = load_contract(contract).get("ci") or {}
113 if PYTHONS_KEY not in ci:
114 return None
115 declared = ci[PYTHONS_KEY]
116 # The contract's judge holds it to a list of strings.
117 if not declared:
118 fail(f'[ci] {PYTHONS_KEY} must be a non-empty list of versions, like ["3.14"]')
119 for value in declared:
120 if not _VERSION_RE.match(value):
121 fail(
122 f"[ci] {PYTHONS_KEY} entry {value!r} is not a python version:"
123 ' spell the minor, like "3.14", or "3.14t" for a free-threaded build'
124 )
125 return [str(value) for value in declared]
126
127
128def gate_pythons(root: Path) -> list[str]:(empty)
129 """The Pythons the gate point's check legs run: the newest of a derived matrix.
130
131 The legs run in parallel, so a second Python adds runner minutes
132 and no wall time; the floor's leg runs at the nightly point, where
133 the whole matrix runs, and a floor-only failure reaches a person
134 the next morning. A declared ``[ci] python-versions`` runs at the
135 gate as declared: the contract chose.
136 """
137 declared = declared_pythons(root)
138 if declared is not None:
139 return declared
140 return python_matrix(root)[-1:]
141
142
143def python_matrix(root: Path) -> list[str]:(empty)
144 """The CI matrix: the contract's declaration, else the floor and the newest minor.
145
146 ``[ci] python-versions`` in the root's ``workshop.toml`` wins where
147 declared, so a development workspace runs one leg and a production
148 contract keeps the full pair. Without it the pair derives: the
149 lower bound of the root ``pyproject.toml``'s ``requires-python``,
150 and the newest minor the workshop tests against, so a new Python
151 reaches every instance through a wheel bump. Each entry is a
152 version such as ``3.14``, or ``3.14t`` for a free-threaded build: in
153 the declared order, or the floor first.
154
155 Raises:
156 Failed: naming the key, when ``[ci] python-versions`` is not a
157 non-empty list of such versions.
158 """
159 declared = declared_pythons(root)
160 if declared is not None:
161 return declared
162 floor = python_floor(root)
163 if _minor(floor) >= _minor(NEWEST_SUPPORTED):
164 return [floor]
165 return [floor, NEWEST_SUPPORTED]