feat: use python-discovery

This enables version ranges to be used.

Assisted-by: OpenCode:Kimi-K2.5
Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

.pre-commit-config.yaml

@@ -48,6 +48,7 @@ repos:
           - packaging
           - pbs_installer
           - pytest<9  # pytest 9 requires 3.10+
+          - python-discovery
           - importlib_metadata
           - importlib_resources
           - tomli

nox/virtualenv.py

@@ -34,6 +34,36 @@
 import nox.command
 from nox.logger import logger
 
+
+def _python_discovery_get_interpreter() -> Any:
+    """Lazy import of get_interpreter from python-discovery."""
+    import python_discovery  # noqa: PLC0415
+
+    return python_discovery.get_interpreter
+
+
+def _python_discovery_DiskCache() -> Any:
+    """Lazy import of DiskCache from python-discovery."""
+    import python_discovery  # noqa: PLC0415
+
+    return python_discovery.DiskCache
+
+
+def _get_python_discovery_cache() -> Any:
+    """Get or create the DiskCache for python-discovery.
+
+    Returns:
+        DiskCache instance or None if caching should not be used
+    """
+    cache_dir = Path.home() / ".cache" / "nox" / "python-discovery"
+    try:
+        disk_cache_cls = _python_discovery_DiskCache()
+        return disk_cache_cls(root=cache_dir)
+    except OSError:
+        # If cache directory can't be created, return None (no caching)
+        return None
+
+
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping, Sequence
 
@@ -111,11 +141,46 @@ def find_uv() -> tuple[bool, str, version.Version]:
     )
 
 
+def _is_version_range_spec(spec: str) -> bool:
+    """Check if the spec is a version range spec (e.g., '>=3.11,<3.13')."""
+    # Check for PEP 440 version comparison operators
+    return any(op in spec for op in [">=", ">", "<=", "<", "~=", "==", "!=", ","])
+
+
 def _find_python(interpreter: str, xy_ver: str) -> str | None:
-    """Find a python executable matching the requested interpreter"""
+    """Find a python executable matching the requested interpreter.
+
+    Uses traditional methods first for backwards compatibility, with python-discovery
+    as a fallback for advanced version specs or when traditional methods fail.
+    """
+    # For version range specs (e.g., ">=3.11,<3.13"), use python-discovery directly
+    if _is_version_range_spec(interpreter):
+        try:
+            cache = _get_python_discovery_cache()
+            get_interpreter = _python_discovery_get_interpreter()
+            result = get_interpreter(interpreter, cache=cache)
+            if result is not None:
+                return str(result.executable)
+        except (OSError, ValueError, RuntimeError):
+            # Fall back to traditional discovery on error
+            pass
+        return None
+
+    # Try traditional discovery first for backwards compatibility
     if shutil.which(interpreter):
         return interpreter
 
+    # Fall back to python-discovery for other interpreters that weren't found
+    try:
+        cache = _get_python_discovery_cache()
+        get_interpreter = _python_discovery_get_interpreter()
+        result = get_interpreter(interpreter, cache=cache)
+        if result is not None:
+            return str(result.executable)
+    except (OSError, ValueError, RuntimeError):
+        # Fall back to platform-specific discovery on error
+        pass
+
     # Windows only search for the executable
     if _PLATFORM.startswith("win"):
         # Allow versions of the form ``X.Y-32`` for Windows.
@@ -777,6 +842,14 @@ def _resolved_interpreter(self) -> str:
             t = match.group("t")
             cleaned_interpreter = f"python{xy_version}{t}"
 
+        # For version range specs (e.g., ">=3.11,<3.13"), check directly
+        # This enables new functionality for specifying version ranges
+        if _is_version_range_spec(self.interpreter) and (
+            resolved := _find_python(self.interpreter, xy_version)
+        ):
+            self._resolved = resolved
+            return self._resolved
+
         match self.download_python, self.venv_backend:
             # never -> check for interpreters
             case "never", _:

pyproject.toml

@@ -43,6 +43,7 @@ dependencies = [
   "dependency-groups>=1.1",
   "humanize>=4",
   "packaging>=22",
+  "python-discovery>=0.1",
   "tomli>=1.1; python_version<'3.11'",
   "virtualenv>=20.15",
 ]

tests/test_virtualenv.py

@@ -114,6 +114,19 @@ def special_which(name: str, path: Any = None) -> str | None:  # noqa: ARG001
 
         monkeypatch.setattr(shutil, "which", special_which)
 
+        # Also mock python-discovery's get_interpreter for backwards compatibility
+        # with tests that rely on the mocked shutil.which behavior
+        def mock_get_interpreter(*args: object, **kwargs: object) -> None:
+            # For tests, we want to respect who the traditional discovery would have found
+            # Since special_which returns None for unknown interpreters, we also return None
+            return None
+
+        monkeypatch.setattr(
+            nox.virtualenv,
+            "_python_discovery_get_interpreter",
+            lambda: mock_get_interpreter,
+        )
+
         def special_run(cmd: Any, *args: Any, **kwargs: Any) -> TextProcessResult:  # noqa: ARG001
             return TextProcessResult(sysexec_result)
 
@@ -1596,12 +1609,26 @@ def test_download_python_never_missing_interpreter(
     pbs_install_mock: mock.Mock,
     venv_backend: str,
     make_one: Callable[..., tuple[VirtualEnv, Path]],
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+    """Test that InterpreterNotFound is raised when interpreter is missing."""
+
+    def mock_get_interpreter(*args: object, **kwargs: object) -> None:
+        return None
+
+    # Mock at the nox module level to prevent python-discovery from finding
+    monkeypatch.setattr(
+        nox.virtualenv,
+        "_python_discovery_get_interpreter",
+        lambda: mock_get_interpreter,
+    )
+
     venv, _ = make_one(
         interpreter="python3.11",
         venv_backend=venv_backend,
         download_python="never",
     )
+
     with pytest.raises(nox.virtualenv.InterpreterNotFound):
         _ = venv._resolved_interpreter
 
@@ -1656,7 +1683,19 @@ def test_download_python_auto_missing_interpreter(
     pbs_install_mock: mock.Mock,
     venv_backend: str,
     make_one: Callable[..., tuple[VirtualEnv, Path]],
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+
+    # Mock python-discovery to return None (simulating missing interpreter)
+    def mock_get_interpreter(*args: object, **kwargs: object) -> None:
+        return None
+
+    monkeypatch.setattr(
+        nox.virtualenv,
+        "_python_discovery_get_interpreter",
+        lambda: mock_get_interpreter,
+    )
+
     venv, _ = make_one(
         interpreter="python3.11",
         venv_backend=venv_backend,
@@ -1688,14 +1727,26 @@ def test_download_python_auto_missing_interpreter(
     "nox.virtualenv.uv_install_python",
     return_value=True,
 )
-@mock.patch.object(shutil, "which", return_value="/usr/bin/python3.11")
+@mock.patch.object(shutil, "which", return_value=None)
 def test_download_python_always_preexisting_interpreter(
     which: mock.Mock,
     uv_install_mock: mock.Mock,
     pbs_install_mock: mock.Mock,
     venv_backend: str,
     make_one: Callable[..., tuple[VirtualEnv, Path]],
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+
+    # Mock python-discovery to return None (simulating missing interpreter)
+    def mock_get_interpreter(*args: object, **kwargs: object) -> None:
+        return None
+
+    monkeypatch.setattr(
+        nox.virtualenv,
+        "_python_discovery_get_interpreter",
+        lambda: mock_get_interpreter,
+    )
+
     venv, _ = make_one(
         interpreter="python3.11",
         venv_backend=venv_backend,
@@ -1728,17 +1779,27 @@ def test_download_python_failed_install(
     download_python: str,
     venv_backend: str,
     make_one: Callable[..., tuple[VirtualEnv, Path]],
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
+
+    # Mock python-discovery to return None (simulating missing interpreter)
+    def mock_get_interpreter(*args: object, **kwargs: object) -> None:
+        return None
+
+    monkeypatch.setattr(
+        nox.virtualenv,
+        "_python_discovery_get_interpreter",
+        lambda: mock_get_interpreter,
+    )
+    monkeypatch.setattr(shutil, "which", lambda _x: None)
+
     venv, _ = make_one(
         interpreter="python3.11",
         venv_backend=venv_backend,
         download_python=download_python,
     )
 
-    with (
-        mock.patch.object(shutil, "which", return_value=None) as _,
-        pytest.raises(nox.virtualenv.InterpreterNotFound),
-    ):
+    with pytest.raises(nox.virtualenv.InterpreterNotFound):
         _ = venv._resolved_interpreter
 
     if venv_backend == "uv":
@@ -1850,8 +1911,20 @@ def test_download_python_uv_unsupported_version(
     uv_install_mock: mock.Mock,
     download_python: str,
     make_one: Callable[..., tuple[VirtualEnv, Path]],
+    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     """Test we dont install for unsupported uv versions"""
+
+    # Mock python-discovery to return None (simulating missing interpreter)
+    def mock_get_interpreter(*args: object, **kwargs: object) -> None:
+        return None
+
+    monkeypatch.setattr(
+        nox.virtualenv,
+        "_python_discovery_get_interpreter",
+        lambda: mock_get_interpreter,
+    )
+
     venv, _ = make_one(
         interpreter="python3.11",
         venv_backend="uv",
@@ -1866,3 +1939,23 @@ def test_download_python_uv_unsupported_version(
         which.assert_not_called()
     else:  # auto
         which.assert_any_call("python3.11")
+
+
+@pytest.mark.parametrize(
+    ("spec", "is_version_range"),
+    [
+        (">=3.11,<3.13", True),
+        (">=3.9", True),
+        ("<3.14", True),
+        ("~=3.11", True),
+        ("==3.12.1", True),
+        ("!=3.11", True),
+        ("3.12", False),
+        ("python3.12", False),
+        ("pypy3.10", False),
+    ],
+)
+def test_is_version_range_spec(spec: str, is_version_range: bool) -> None:
+    """Test the _is_version_range_spec function correctly identifies version specs."""
+    result = nox.virtualenv._is_version_range_spec(spec)
+    assert result == is_version_range