1"""Python version facts, derived from the workspace, never asked.
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"""
21 """Name *venv*'s executables directory: ``Scripts`` on Windows, ``bin`` elsewhere.
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.
27 Args:
28 venv: The venv's directory.
30 Returns:
31 The directory its interpreter and its console scripts are in.
32 """
33 return venv / ("Scripts" if sys.platform == "win32" else "bin")
37 """Name *venv*'s interpreter on this platform.
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.
43 Args:
44 venv: The venv's directory.
46 Returns:
47 The interpreter's path.
48 """
49 return scripts_dir(venv) / ("python.exe" if sys.platform == "win32" else "python")
53 """The console script in *venv* of the runner this process runs as.
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)
63#: The oldest Python a workspace being born supports; the floor once
64#: its ``pyproject.toml`` exists and declares one.
67#: The newest minor the workshop tests against. Raising it widens
68#: every instance's CI matrix on its next wheel bump.
73 """The workspace's Python floor.
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
91 major, _, minor = version.partition(".")
92 return int(major), int(minor)
95#: The contract key that overrides the derived matrix, born kebab-case.
102 """The contract's ``[ci] python-versions``, or ``None`` when undeclared.
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]
129 """The Pythons the gate point's check legs run: the newest of a derived matrix.
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:]
144 """The CI matrix: the contract's declaration, else the floor and the newest minor.
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.
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]