| 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() |