# Copyright Kevin Deldycke <[email protected]> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
"""Build `uv` and `uvx` command lines, and run them.
The leaf of the dependency package: it imports nothing else from it, so the
tool runner and the docs builder reach the builders without loading the lock
and report machinery. The lock views live in {mod}`repomatic.deps.lockfile`,
the cooldown lifecycle in {mod}`repomatic.deps.cooldown`.
"""
from __future__ import annotations
import logging
import subprocess
TYPE_CHECKING = False
if TYPE_CHECKING:
from collections.abc import Mapping, Sequence
from pathlib import Path
[docs]
def uv_cmd(
subcommand: str,
*,
frozen: bool = False,
no_project: bool = False,
exclude_newer: str | None = None,
) -> list[str]:
"""Build a `uv <subcommand>` command prefix with standard flags.
Always includes `--no-progress`. Adds `--frozen` when requested
(appropriate for `run`, `export`, `sync`, never for `lock`). Adds
`--no-project` to skip project discovery entirely, and `--exclude-newer`
to gate a resolution by a cooldown, mirroring {func}`uvx_cmd`.
:param subcommand: The `uv` subcommand.
:param frozen: Add `--frozen`.
:param no_project: Add `--no-project`.
:param exclude_newer: The `--exclude-newer` value, in any form uv accepts.
Omitted when empty.
"""
cmd = ["uv", "--no-progress", subcommand]
if frozen:
cmd.append("--frozen")
if no_project:
cmd.append("--no-project")
if exclude_newer:
cmd += ["--exclude-newer", exclude_newer]
return cmd
[docs]
def uvx_cmd(exclude_newer: str | None = None) -> list[str]:
"""Build a `uvx` command prefix with standard flags.
When *exclude_newer* is set (a `YYYY-MM-DD` date), adds `--exclude-newer` so
the isolated resolution honors the `minimum-release-age` cooldown, gating the
tool's transitive dependencies by upload date.
"""
cmd = ["uvx", "--no-progress"]
if exclude_newer:
cmd += ["--exclude-newer", exclude_newer]
return cmd
[docs]
def uv_lock_command(
*extra: str,
exclude_newer: str = "",
exclude_newer_packages: Mapping[str, str] | None = None,
) -> list[str]:
"""Build a `uv lock` argv carrying a cooldown window.
The one builder behind every re-lock this package runs with a window
(`sync-uv-lock`, the dep-sources swap, `audit --fix`, the held-back probe),
so none of them can forget the explicit `--exclude-newer` that keeps CI's
ambient `UV_EXCLUDE_NEWER` from retiming the lock: see
{attr}`repomatic.deps.cooldown.UvSettings.window`. {func}`relock` alone
runs a plain `uv lock`.
:param extra: Extra `uv lock` arguments (`--upgrade`,
`--upgrade-package`, ...), placed before the cooldown flags.
:param exclude_newer: The window, in any form uv accepts. Empty leaves the
flag off.
:param exclude_newer_packages: Package name to its own window, for this run
only. A flag on the command line beats the `pyproject.toml` entry of
the same package.
:return: The argv to run, with `cwd` set to the project directory.
"""
cmd = [*uv_cmd("lock"), *extra]
for name, value in sorted((exclude_newer_packages or {}).items()):
cmd += ["--exclude-newer-package", f"{name}={value}"]
if exclude_newer:
cmd += ["--exclude-newer", exclude_newer]
return cmd
[docs]
class UvError(subprocess.CalledProcessError):
"""A `uv` command that exited non-zero, carrying what it printed on stderr."""
def __str__(self) -> str:
detail = str(self.stderr or "").strip()
return f"{super().__str__()}\n{detail}" if detail else super().__str__()
[docs]
def run_uv(
cmd: Sequence[str], *, cwd: Path | None = None, check: bool = True
) -> subprocess.CompletedProcess[str]:
"""Run a `uv` command and capture its output.
The one runner behind every `uv` call of this package. The output is
captured, never streamed: a resolution summary printed while a progress
trail is on screen lands on the trail's own row. The decoding is pinned to
UTF-8, since an SBOM carries package descriptions and author names that
the platform default cannot always decode.
:param cmd: The argv, from one of the builders above.
:param cwd: The directory to run in. Defaults to the working directory.
:param check: Raise on a non-zero exit.
:return: The completed process, `stdout` and `stderr` as text.
:raises UvError: When the command fails and *check* is set. Its message
carries the command's stderr. Also when the command cannot start, with
no `uv` on `PATH` or no *cwd*, whatever *check*: the exit status is
then 127, the one a shell gives a command it cannot find.
"""
logging.debug(f"Running {' '.join(cmd)}" + (f" in {cwd}." if cwd else "."))
try:
result = subprocess.run(
list(cmd), capture_output=True, encoding="UTF-8", check=False, cwd=cwd
)
except FileNotFoundError as error:
raise UvError(127, cmd, "", str(error)) from error
if check and result.returncode:
raise UvError(result.returncode, cmd, result.stdout, result.stderr)
return result
[docs]
def relock() -> None:
"""Refresh `uv.lock` after a version bump, and nothing else in it.
A plain `uv lock`, on purpose. `bump-my-version` rewrites the project's
version in `pyproject.toml` but not in `uv.lock`, and a bump committed
without the re-lock leaves the project ahead of its own lock entry: the
next `uv run --frozen` then reinstalls the project, and two nested syncs of
a release build can delete a console script the other one is running, a
sharing violation on Windows.
`uv lock --upgrade` would re-resolve every dependency instead. With a
`"0 day"` `exclude-newer-package` bypass in place, it fast-forwards that
dependency across a release still inside its cooldown, on an unreviewed
bump pull request. `uv sync` would leave the lock in a state the
`sync-uv-lock` job rewrites into a redundant follow-up pull request.
Dependency upgrades stay the job of `sync-uv-lock`, in their own pull
request.
:raises UvError: When uv cannot lock the project.
"""
cmd = uv_cmd("lock")
logging.info(f"Running: {' '.join(cmd)}")
run_uv(cmd)