Debian Codegraph @

python/tests/vetox.py

raw
1 # SPDX-FileCopyrightText: Peter Pentchev <[email protected]>
2 # SPDX-License-Identifier: BSD-2-Clause
3 """Create a virtual environment, install Tox, run it."""
4
5 from __future__ import annotations
6
7 import argparse
8 import configparser
9 import dataclasses
10 import functools
11 import logging
12 import os
13 import pathlib
14 import re
15 import shlex
16 import subprocess
17 import sys
18 import tempfile
19 import typing
20 import venv
21
22
23 if typing.TYPE_CHECKING:
24 from collections.abc import Callable
25 from typing import Final
26
27
28 VERSION: Final = "0.1.4"
29 """The vetox library version."""
30
31
32 TOX_MIN_VERSION: Final = "4.1"
33 """The minimum version of Tox needed to run our tests."""
34
35 # Is this too strict? No, for our purposes it is not.
36 RE_FROZEN_LINE: Final = re.compile(
37 r"^ (?P<name> [A-Za-z][A-Za-z0-9_.-]+ ) == (?P<version> [0-9A-Za-z_.-]+ ) $",
38 re.X,
39 )
40 """Match a line in the output of `pip freeze`."""
41
42
43 @dataclasses.dataclass(frozen=True)
44 class Config:
45 """Runtime configuration for the venv-tox tool."""
46
47 conf: pathlib.Path
48 """The path to the `tox.ini` file to use."""
49
50 env: dict[str, str]
51 """The cleaned-up environment variables to pass to child processes."""
52
53 log: logging.Logger
54 """The logger to send diagnostic, informational, warning, and error messages to."""
55
56 tempd: pathlib.Path
57 """The temporary directory to operate in."""
58
59 tox_req: str | None
60 """The PEP508 version requirements for Tox itself if specified."""
61
62 tox_uv: bool
63 """Install `tox-uv` ito the virtual environment."""
64
65 uv: bool
66 """Use `uv` to create the ephemeral Tox environment."""
67
68
69 # Shamelessly stolen from the logging-std module
70 @functools.lru_cache
71 def build_logger() -> logging.Logger:
72 """Build a logger object, send info messages to stdout, everything else to stderr."""
73 logger: Final = logging.getLogger("vetox")
74 logger.setLevel(logging.DEBUG)
75 logger.propagate = False
76
77 h_out: Final = logging.StreamHandler(sys.stdout)
78 h_out.setLevel(logging.INFO)
79 h_out.addFilter(lambda rec: rec.levelno == logging.INFO)
80 logger.addHandler(h_out)
81
82 h_err: Final = logging.StreamHandler(sys.stderr)
83 h_err.setLevel(logging.INFO)
84 h_err.addFilter(lambda rec: rec.levelno != logging.INFO)
85 logger.addHandler(h_err)
86
87 return logger
88
89
90 def clean_env() -> dict[str, str]:
91 """Clean up any variables related to the current virtual environment."""
92 return {
93 name: value
94 for name, value in os.environ.items()
95 if not name.startswith(("PYTEST", "PYTHON", "TOX", "VIRTUAL_ENV"))
96 }
97
98
99 def parse_frozen(contents: str) -> dict[str, str]:
100 """Parse the output of `pip freeze` into a name-to-version dict."""
101
102 def parse_single(line: str) -> tuple[str, str]:
103 """Parse a single line."""
104 pkg: Final = RE_FROZEN_LINE.match(line)
105 if not pkg:
106 sys.exit(f"Unexpected `pip freeze` output line: {line!r}")
107 return pkg.group("name"), pkg.group("version")
108
109 return dict(parse_single(line) for line in contents.splitlines())
110
111
112 def create_and_update_uv_venv(cfg: Config, penv: pathlib.Path) -> pathlib.Path:
113 """Use `uv` to create a virtual environment."""
114 cfg.log.info("About to create the %(penv)s virtual environment using uv", {"penv": penv})
115 subprocess.check_call(["uv", "venv", "-p", sys.executable, "--", penv], env=cfg.env)
116 return penv
117
118
119 def create_and_update_venv(cfg: Config) -> pathlib.Path:
120 """Create a virtual environment, update all the packages within."""
121 penv: pathlib.Path = cfg.tempd / "venv"
122 if cfg.uv:
123 return create_and_update_uv_venv(cfg, penv)
124
125 cfg.log.info("About to create the %(penv)s virtual environment", {"penv": penv})
126 if sys.version_info >= (3, 9):
127 cfg.log.info("- using venv.create(upgrade_deps) directly")
128 venv.create(penv, with_pip=True, upgrade_deps=True)
129 return penv
130
131 cfg.log.info("- no venv.create(upgrade_deps)")
132 venv.create(penv, with_pip=True)
133
134 cfg.log.info("- obtaining the list of packages in the virtual environment")
135 contents: Final = subprocess.check_output(
136 [penv / "bin/python3", "-m", "pip", "freeze", "--all"],
137 encoding="UTF-8",
138 env=cfg.env,
139 )
140 names: Final = sorted(parse_frozen(contents))
141 cfg.log.info(
142 "- upgrading the %(names)s package%(plu)s in the virtual environment",
143 {"names": ", ".join(names), "plu": "" if len(names) == 1 else "s"},
144 )
145 subprocess.check_call(
146 [penv / "bin/python3", "-m", "pip", "install", "-U", "--", *names],
147 env=cfg.env,
148 )
149 return penv
150
151
152 @functools.lru_cache
153 def get_tox_min_version(conf: pathlib.Path) -> str:
154 """Look for a minimum Tox version in the tox.ini file, fall back to TOX_MIN_VERSION."""
155 cfgp: Final = configparser.ConfigParser(interpolation=None)
156 with conf.open(encoding="UTF-8") as tox_ini:
157 cfgp.read_file(tox_ini)
158
159 return cfgp["tox"].get("min_version", cfgp["tox"].get("minversion", TOX_MIN_VERSION))
160
161
162 def install_tox(cfg: Config, penv: pathlib.Path) -> None:
163 """Install Tox into the virtual environment."""
164 if cfg.tox_req is not None:
165 tox_req = f"tox {cfg.tox_req}"
166 else:
167 minver: Final = get_tox_min_version(cfg.conf)
168 tox_req = f"tox >= {minver}"
169
170 tox_uv: Final = ["tox-uv"] if cfg.tox_uv else []
171
172 cfg.log.info(
173 "Installing Tox %(tox_req)s%(tox_uv)s",
174 {"tox_req": tox_req, "tox_uv": " and tox-uv" if cfg.tox_uv else ""},
175 )
176 if cfg.uv:
177 subprocess.check_call(
178 ["env", f"VIRTUAL_ENV={penv}", "uv", "pip", "install", tox_req, *tox_uv],
179 env=cfg.env,
180 )
181 else:
182 subprocess.check_call(
183 [penv / "bin/python3", "-m", "pip", "install", tox_req, *tox_uv],
184 env=cfg.env,
185 )
186
187
188 def get_tox_cmdline(
189 cfg: Config,
190 penv: pathlib.Path,
191 *,
192 parallel: bool = True,
193 args: list[str],
194 ) -> list[pathlib.Path | str]:
195 """Get the Tox command with arguments."""
196 penv_py3: Final = penv / "bin/python3"
197
198 def get_run_command() -> list[str]:
199 """Get the appropriate command to run Tox in parallel or not."""
200 if not parallel:
201 return ["run"]
202
203 vers: Final = subprocess.check_output(
204 [penv_py3, "-m", "tox", "--version"],
205 encoding="UTF-8",
206 env=cfg.env,
207 )
208 if vers.startswith("3"):
209 return ["run", "-p", "all"]
210
211 return ["run-parallel"]
212
213 cfg.log.info(
214 "Running Tox%(parallel)s with %(args)s",
215 {
216 "parallel": " in parallel" if parallel else "",
217 "args": ("additional arguments: " + shlex.join(args))
218 if args
219 else "no additional arguments",
220 },
221 )
222 run_cmd: Final = get_run_command()
223 return [penv_py3, "-m", "tox", "-c", cfg.conf, *run_cmd, *args]
224
225
226 def run_tox(cfg: Config, penv: pathlib.Path, *, parallel: bool = True, args: list[str]) -> None:
227 """Run Tox from the virtual environment."""
228 subprocess.check_call(get_tox_cmdline(cfg, penv, parallel=parallel, args=args), env=cfg.env)
229
230
231 def run(cfg_no_tempd: Config, *, parallel: bool, args: list[str]) -> None:
232 """Create the virtual environment, install Tox, run it."""
233 with tempfile.TemporaryDirectory() as tempd_obj:
234 cfg: Final = dataclasses.replace(cfg_no_tempd, tempd=pathlib.Path(tempd_obj))
235 penv: Final = create_and_update_venv(cfg)
236 install_tox(cfg, penv)
237 run_tox(cfg, penv, parallel=parallel, args=args)
238
239
240 def cmd_run(cfg_no_tempd: Config, args: list[str]) -> None:
241 """Run the Tox tests sequentially."""
242 run(cfg_no_tempd, parallel=False, args=args)
243
244
245 def cmd_run_parallel(cfg_no_tempd: Config, args: list[str]) -> None:
246 """Run the Tox tests in parallel."""
247 run(cfg_no_tempd, parallel=True, args=args)
248
249
250 def cmd_features(_cfg_no_tempd: Config, _args: list[str]) -> None:
251 """Display the list of features supported by the program."""
252 print(f"Features: vetox={VERSION} tox=0.1 tox-parallel=0.1 tox-uv=0.1 uv=0.1")
253
254
255 def cmd_version(_cfg_no_tempd: Config, _args: list[str]) -> None:
256 """Display the vetox version."""
257 print(f"vetox {VERSION}")
258
259
260 def parse_args() -> tuple[Config, Callable[[Config, list[str]], None], list[str]]:
261 """Parse the command-line arguments."""
262 parser: Final = argparse.ArgumentParser(prog="vetox")
263 parser.add_argument(
264 "-c",
265 "--conf",
266 type=pathlib.Path,
267 default=pathlib.Path.cwd() / "tox.ini",
268 help="The path to the tox.ini file",
269 )
270
271 subp: Final = parser.add_subparsers()
272 p_run: Final = subp.add_parser("run", help="Run tests sequentially")
273 p_run.add_argument(
274 "-t",
275 "--tox-req",
276 type=str,
277 help="specify the PEP508 version requirement for Tox itself",
278 )
279 p_run.add_argument(
280 "--tox-uv",
281 action="store_true",
282 help="Install `tox-uv` into the virtual environment",
283 )
284 p_run.add_argument(
285 "--uv",
286 action="store_true",
287 help="Use `uv` to create the ephemeral virtual environment",
288 )
289 p_run.add_argument("args", type=str, nargs="*", help="Additional arguments to pass to Tox")
290 p_run.set_defaults(func=cmd_run)
291
292 p_run_p: Final = subp.add_parser("run-parallel", help="Run tests in parallel")
293 p_run_p.add_argument(
294 "-t",
295 "--tox-req",
296 type=str,
297 help="specify the PEP508 version requirement for Tox itself",
298 )
299 p_run_p.add_argument(
300 "--tox-uv",
301 action="store_true",
302 help="Install `tox-uv` into the virtual environment",
303 )
304 p_run_p.add_argument(
305 "--uv",
306 action="store_true",
307 help="Use `uv` to create the ephemeral virtual environment",
308 )
309 p_run_p.add_argument("args", type=str, nargs="*", help="Additional arguments to pass to Tox")
310 p_run_p.set_defaults(func=cmd_run_parallel)
311
312 p_features: Final = subp.add_parser("features", help="Display the supported program features")
313 p_features.set_defaults(func=cmd_features)
314
315 p_version: Final = subp.add_parser("version", help="Display the vetox version")
316 p_version.set_defaults(func=cmd_version)
317
318 args: Final = parser.parse_args()
319
320 func: Final[Callable[[Config, list[str]], None] | None] = getattr(args, "func", None)
321 if func is None:
322 sys.exit("No subcommand specified; use `--help` for a list")
323
324 # Things would be a bit simpler with `click`, but we don't want any dependencies
325 return (
326 Config(
327 conf=args.conf,
328 env=clean_env(),
329 log=build_logger(),
330 tempd=pathlib.Path("/nonexistent"),
331 tox_req=getattr(args, "tox_req", False), # type: ignore[arg-type]
332 tox_uv=getattr(args, "tox_uv", False),
333 uv=getattr(args, "uv", False),
334 ),
335 func,
336 getattr(args, "args", []),
337 )
338
339
340 def main() -> None:
341 """Parse command-line arguments, create a virtual environment, run Tox."""
342 cfg_no_tempd, func, args = parse_args()
343 func(cfg_no_tempd, args)
344
345
346 if __name__ == "__main__":
347 main()