Add uv_resolution as testenv parameter (#39)

* Add uv_resolution as testenv parameter

uv supports defining a custom resolution strategy, defaulting to
'highest', and allowing 'lowest' or 'lowest-direct' at the time of
writing, which provides an alternative to package constraints enabling
lowest direct or transitive dependencies to be installed.

This change provides a new 'uv_resolution' configuration option for test
environments, which if defined will apply the '--resolution' option to
uv to enable this behavior.

Implements #28.

* Ensure call arguments match defined options for uv resolution

* Restrict uv resolution options to known values

uv currently supports "highest", "lowest", or "lowest-direct" as
resolution strategies, which we now validate.

* Document the new `uv_resolution` flag

* Use base type and post-process for uv_resolution

mypy expects the actual type for add_config, so we instead use
post-processing to validate the literal string against known options,
raising an error if otherwise.

* Test all valid and an invalid uv_resolution strategy

Author: Stealthii

README.md

@@ -28,3 +28,17 @@ python -m tox r -e py312 # will use uv
 This flag, set on a tox environment level, controls if the created virtual environment injects pip/setuptools/wheel into
 the created virtual environment or not. By default, is off. You will need to set this if you have a project that uses
 the old legacy editable mode, or your project does not support the `pyproject.toml` powered isolated build model.
+
+### uv_resolution
+
+This flag, set on a tox environment level, informs uv of the desired [resolution strategy]:
+
+- `highest` - (default) selects the highest version of a package that satisfies the constraints
+- `lowest` - install the **lowest** compatible versions for all dependencies, both **direct** and **transitive**
+- `lowest-direct` - opt for the **lowest** compatible versions for all **direct** dependencies, while using the
+  **latest** compatible versions for all **transitive** dependencies
+
+This is a uv specific feature that may be used as an alternative to frozen constraints for test environments, if the
+intention is to validate the lower bounds of your dependencies during test executions.
+
+[resolution strategy]: https://github.com/astral-sh/uv/blob/0.1.20/README.md#resolution-strategy

src/tox_uv/_installer.py

@@ -11,7 +11,7 @@
 from tox.config.of_type import ConfigDynamicDefinition
 from tox.config.types import Command
 from tox.execute.request import StdinSource
-from tox.tox_env.errors import Recreate
+from tox.tox_env.errors import Fail, Recreate
 from tox.tox_env.python.package import EditableLegacyPackage, EditablePackage, SdistPackage, WheelPackage
 from tox.tox_env.python.pip.pip_install import Pip
 from tox.tox_env.python.pip.req_file import PythonDeps
@@ -27,6 +27,21 @@ class UvInstaller(Pip):
 
     def _register_config(self) -> None:
         super()._register_config()
+
+        def uv_resolution_post_process(value: str) -> str:
+            valid_opts = {"highest", "lowest", "lowest-direct"}
+            if value and value not in valid_opts:
+                msg = f"Invalid value for uv_resolution: {value!r}. Valid options are: {', '.join(valid_opts)}."
+                raise Fail(msg)
+            return value
+
+        self._env.conf.add_config(
+            keys=["uv_resolution"],
+            of_type=str,
+            default="",
+            desc="Define the resolution strategy for uv",
+            post_process=uv_resolution_post_process,
+        )
         if self._with_list_deps:  # pragma: no branch
             conf = cast(ConfigDynamicDefinition[Command], self._env.conf._defined["list_dependencies_command"])  # noqa: SLF001
             conf.default = Command([self.uv, "--color", "never", "pip", "freeze"])
@@ -44,16 +59,22 @@ def default_install_command(self, conf: Config, env_name: str | None) -> Command
     def post_process_install_command(self, cmd: Command) -> Command:
         install_command = cmd.args
         pip_pre: bool = self._env.conf["pip_pre"]
+        uv_resolution: str = self._env.conf["uv_resolution"]
         try:
             opts_at = install_command.index("{opts}")
         except ValueError:
             if pip_pre:
                 install_command.extend(("--prerelease", "allow"))
+            if uv_resolution:
+                install_command.extend(("--resolution", uv_resolution))
         else:
             if pip_pre:
                 install_command[opts_at] = "--prerelease"
                 install_command.insert(opts_at + 1, "allow")
-            else:
+            if uv_resolution:
+                install_command[opts_at] = "--resolution"
+                install_command.insert(opts_at + 1, uv_resolution)
+            if not (pip_pre or uv_resolution):
                 install_command.pop(opts_at)
         return cmd
 

tests/test_tox_uv_installer.py

@@ -3,8 +3,9 @@
 import sys
 from typing import TYPE_CHECKING
 
+import pytest
+
 if TYPE_CHECKING:
-    import pytest
     from tox.pytest import ToxProjectCreator
 
 
@@ -60,3 +61,41 @@ def test_uv_install_without_pre_custom_install_cmd(tox_project: ToxProjectCreato
     })
     result = project.run("-vv")
     result.assert_success()
+
+
+@pytest.mark.parametrize("strategy", ["highest", "lowest", "lowest-direct"])
+def test_uv_install_with_resolution_strategy(tox_project: ToxProjectCreator, strategy: str) -> None:
+    project = tox_project({"tox.ini": f"[testenv]\ndeps = tomli>=2.0.1\npackage = skip\nuv_resolution = {strategy}"})
+    execute_calls = project.patch_execute(lambda r: 0 if "install" in r.run_id else None)
+
+    result = project.run("-vv")
+    result.assert_success()
+
+    assert execute_calls.call_args[0][3].cmd[2:] == ["install", "--resolution", strategy, "tomli>=2.0.1", "-v"]
+
+
+def test_uv_install_with_invalid_resolution_strategy(tox_project: ToxProjectCreator) -> None:
+    project = tox_project({"tox.ini": "[testenv]\ndeps = tomli>=2.0.1\npackage = skip\nuv_resolution = invalid"})
+
+    result = project.run("-vv")
+    result.assert_failed(code=1)
+
+    assert "Invalid value for uv_resolution: 'invalid'." in result.out
+
+
+def test_uv_install_with_resolution_strategy_custom_install_cmd(tox_project: ToxProjectCreator) -> None:
+    project = tox_project({
+        "tox.ini": """
+    [testenv]
+    deps = tomli>=2.0.1
+    package = skip
+    uv_resolution = lowest-direct
+    install_command = uv pip install {packages}
+    """
+    })
+    execute_calls = project.patch_execute(lambda r: 0 if "install" in r.run_id else None)
+
+    result = project.run("-vv")
+    result.assert_success()
+
+    assert execute_calls.call_args[0][3].cmd[2:] == ["install", "tomli>=2.0.1", "--resolution", "lowest-direct"]