|
| 1 | +"""PEP 723 inline script metadata support — shared logic for any venv backend.""" |
| 2 | + |
| 3 | +from __future__ import annotations |
| 4 | + |
| 5 | +import logging |
| 6 | +import re |
| 7 | +import sys |
| 8 | +from dataclasses import dataclass, field |
| 9 | +from typing import TYPE_CHECKING, Final, cast |
| 10 | + |
| 11 | +from packaging.specifiers import SpecifierSet |
| 12 | +from packaging.version import Version |
| 13 | + |
| 14 | +from tox.config.types import Command |
| 15 | +from tox.tox_env.errors import Fail |
| 16 | +from tox.tox_env.python.pip.req_file import PythonDeps |
| 17 | +from tox.tox_env.python.runner import add_skip_missing_interpreters_to_core, add_skip_missing_interpreters_to_env |
| 18 | +from tox.tox_env.runner import RunToxEnv |
| 19 | + |
| 20 | +from .api import Python |
| 21 | + |
| 22 | +if sys.version_info >= (3, 11): # pragma: >=3.11 cover |
| 23 | + import tomllib |
| 24 | +else: # pragma: <3.11 cover |
| 25 | + import tomli as tomllib |
| 26 | + |
| 27 | +if TYPE_CHECKING: |
| 28 | + from pathlib import Path |
| 29 | + |
| 30 | + from tox.config.main import Config |
| 31 | + from tox.config.of_type import ConfigDynamicDefinition |
| 32 | + from tox.tox_env.api import ToxEnvCreateArgs |
| 33 | + |
| 34 | +_SCRIPT_METADATA_RE: Final = re.compile( |
| 35 | + r""" |
| 36 | + (?m) |
| 37 | + ^[#][ ]///[ ](?P<type>[a-zA-Z0-9-]+)$ # opening: # /// <type> |
| 38 | + \s # blank line or whitespace |
| 39 | + (?P<content> # TOML content lines: |
| 40 | + (?:^[#](?:| .*)$\s)+ # each line starts with # (optionally followed by space + text) |
| 41 | + ) |
| 42 | + ^[#][ ]///$ # closing: # /// |
| 43 | + """, |
| 44 | + re.VERBOSE, |
| 45 | +) |
| 46 | + |
| 47 | + |
| 48 | +@dataclass(frozen=True) |
| 49 | +class ScriptMetadata: |
| 50 | + requires_python: str | None = None |
| 51 | + dependencies: list[str] = field(default_factory=list) |
| 52 | + |
| 53 | + |
| 54 | +class Pep723Mixin(Python, RunToxEnv): |
| 55 | + """Mixin providing PEP 723 script metadata support for any venv-backed runner. |
| 56 | +
|
| 57 | + Concrete runners compose this with a venv backend (VirtualEnv, UvVenv, etc.) and RunToxEnv. |
| 58 | +
|
| 59 | + """ |
| 60 | + |
| 61 | + _script_metadata: ScriptMetadata | None |
| 62 | + |
| 63 | + def __init__(self, create_args: ToxEnvCreateArgs) -> None: |
| 64 | + self._script_metadata = None |
| 65 | + super().__init__(create_args) |
| 66 | + |
| 67 | + def register_config(self) -> None: |
| 68 | + super().register_config() |
| 69 | + self.conf.add_config( |
| 70 | + keys=["script"], |
| 71 | + of_type=str, |
| 72 | + default="", |
| 73 | + desc="path to Python script with PEP 723 inline metadata (relative to tox_root)", |
| 74 | + ) |
| 75 | + |
| 76 | + def default_commands(conf: Config, env_name: str | None) -> list[Command]: # noqa: ARG001 |
| 77 | + if script := self.conf["script"]: |
| 78 | + tox_root: Path = self.core["tox_root"] |
| 79 | + args = ["python", str(tox_root / script)] |
| 80 | + if (pos_args := conf.pos_args(None)) is not None: |
| 81 | + args.extend(pos_args) |
| 82 | + return [Command(args)] |
| 83 | + return [] |
| 84 | + |
| 85 | + commands_def = cast("ConfigDynamicDefinition[list[Command]]", self.conf._defined["commands"]) # noqa: SLF001 |
| 86 | + commands_def.default = default_commands |
| 87 | + add_skip_missing_interpreters_to_core(self.core, self.options) |
| 88 | + add_skip_missing_interpreters_to_env(self.conf, self.core, self.options) |
| 89 | + |
| 90 | + def _base_python_default(self, conf: Config, env_name: str | None) -> list[str]: |
| 91 | + self._base_python_explicitly_set = False |
| 92 | + metadata = self._get_script_metadata() |
| 93 | + if metadata.requires_python and (python := _min_python_from_requires(metadata.requires_python)): |
| 94 | + return [python] |
| 95 | + return super()._base_python_default(conf, env_name) |
| 96 | + |
| 97 | + def _setup_env(self) -> None: |
| 98 | + super()._setup_env() |
| 99 | + if self._base_python_explicitly_set: |
| 100 | + msg = "cannot set base_python with virtualenv-pep-723 runner; use requires-python in the script" |
| 101 | + raise Fail(msg) |
| 102 | + if script := self.conf["script"]: |
| 103 | + tox_root: Path = self.core["tox_root"] |
| 104 | + if not (tox_root / script).is_file(): |
| 105 | + msg = f"script file not found: {tox_root / script}" |
| 106 | + raise Fail(msg) |
| 107 | + if getattr(self.options, "skip_env_install", False): |
| 108 | + logging.warning("skip installing dependencies") |
| 109 | + return |
| 110 | + metadata = self._get_script_metadata() |
| 111 | + if metadata.dependencies: |
| 112 | + root: Path = self.core["tox_root"] |
| 113 | + requirements = PythonDeps(metadata.dependencies, root) |
| 114 | + self._install(requirements, type(self).__name__, "deps") |
| 115 | + |
| 116 | + def _get_script_metadata(self) -> ScriptMetadata: |
| 117 | + if self._script_metadata is None: |
| 118 | + if not (script := self.conf["script"]): |
| 119 | + self._script_metadata = ScriptMetadata() |
| 120 | + return self._script_metadata |
| 121 | + tox_root: Path = self.core["tox_root"] |
| 122 | + full_path = tox_root / script |
| 123 | + if not full_path.is_file(): |
| 124 | + self._script_metadata = ScriptMetadata() |
| 125 | + return self._script_metadata |
| 126 | + self._script_metadata = _parse_script_metadata(full_path.read_text(encoding="utf-8")) |
| 127 | + return self._script_metadata |
| 128 | + |
| 129 | + |
| 130 | +def _parse_script_metadata(script: str) -> ScriptMetadata: |
| 131 | + blocks = [(m.group("type"), m.group("content")) for m in _SCRIPT_METADATA_RE.finditer(script)] |
| 132 | + script_blocks = [(t, c) for t, c in blocks if t == "script"] |
| 133 | + if len(script_blocks) > 1: |
| 134 | + msg = "multiple [script] metadata blocks found in script" |
| 135 | + raise ValueError(msg) |
| 136 | + if not script_blocks: |
| 137 | + return ScriptMetadata() |
| 138 | + content = script_blocks[0][1] |
| 139 | + stripped = "".join( |
| 140 | + line[2:] if len(line) > 1 and line[1] == " " else line[1:] for line in content.splitlines(keepends=True) |
| 141 | + ) |
| 142 | + metadata = tomllib.loads(stripped) |
| 143 | + return ScriptMetadata( |
| 144 | + requires_python=metadata.get("requires-python"), |
| 145 | + dependencies=metadata.get("dependencies", []), |
| 146 | + ) |
| 147 | + |
| 148 | + |
| 149 | +def _min_python_from_requires(requires_python: str) -> str | None: |
| 150 | + for spec in SpecifierSet(requires_python): |
| 151 | + if spec.operator in {">=", "~=", "=="}: |
| 152 | + version = Version(spec.version.replace(".*", "")) |
| 153 | + return f"python{version.major}.{version.minor}" |
| 154 | + return None |
| 155 | + |
| 156 | + |
| 157 | +__all__ = [ |
| 158 | + "Pep723Mixin", |
| 159 | + "ScriptMetadata", |
| 160 | +] |
0 commit comments