fix: download upper-bound-only Python ranges (#1148)

* fix: install the highest allowed version for upper-bound-only ranges

An upper-bound-only range such as "<3.14" had no installable floor, so
--download-python could not help. Pick the highest X.Y below the
tightest upper bound, and step down past "!=" exclusions.

Assisted-by: ClaudeCode:claude-fable-5

* fix: never pick a minor whose patch releases can exceed an upper bound

An install target "X.Y" resolves to the latest X.Y patch release, so
bounds like "<3.14.4" or "<=3.14" could install an interpreter outside
the range once a newer patch exists (and discovery, which matches with
strict PEP 440 semantics, would then never find it). Always step down to
the minor below the bound, which every patch release satisfies.

Assisted-by: ClaudeCode:claude-fable-5

* refactor: simplify upper-bound target resolution

Return (major, minor) tuples from _highest_under_upper_bound instead of
strings the caller re-parses, and derive the free-threaded "t" suffix
once up front. Also fixes two edge cases: mixed specs like <3.13,<3.14t
no longer drop the "t", and clauses packaging cannot parse (<3.14,<3.12.)
return None instead of raising InvalidSpecifier.

Assisted-by: ClaudeCode:claude-fable-5

Author: henryiii

docs/config.rst

@@ -159,7 +159,7 @@ Nox will use the first installed interpreter that satisfies it:
     Range specifiers are only supported on the ``venv``, ``virtualenv``, and ``uv``
     backends, not on conda backends.
 
-If the specified python interpreter is not found, Nox can automatically download it when ``--download-python`` is set to ``auto`` (the default) or ``always``. ``never`` avoids the download. This requires the ``[pbs]`` extra when not using uv as a backend. When a range is given, the floor of its lowest bound is downloaded (``>=3.14`` downloads ``3.14``); a range with no lower bound (such as ``<3.14``) cannot be downloaded.
+If the specified python interpreter is not found, Nox can automatically download it when ``--download-python`` is set to ``auto`` (the default) or ``always``. ``never`` avoids the download. This requires the ``[pbs]`` extra when not using uv as a backend. When a range is given, the floor of its lowest bound is downloaded (``>=3.14`` downloads ``3.14``). A range with only upper bounds downloads the highest minor version that the range fully allows (``<3.14`` downloads ``3.13``, ``<=3.14.4`` downloads ``3.13``, ``<3.14,!=3.13.*`` downloads ``3.12``). A range with no usable bound (such as ``!=3.12``) cannot be downloaded.
 
 When collecting your sessions, Nox will create a separate session for each interpreter. You can see these sessions when running ``nox --list``. For example this Noxfile:
 

nox/virtualenv.py

@@ -40,7 +40,7 @@
 from socket import gethostbyname
 from typing import TYPE_CHECKING, Any, Literal
 
-from packaging import version
+from packaging import specifiers, version
 
 import nox
 import nox.command
@@ -190,27 +190,84 @@ def _find_python(interpreter: str) -> str | None:
     return info.executable if info is not None else None
 
 
+def _highest_under_upper_bound(
+    operator: str, version_str: str
+) -> tuple[int, int] | None:
+    """Return the highest ``(major, minor)`` fully below a ``<``/``<=`` clause.
+
+    Installers resolve ``X.Y`` to its latest patch release, so the pick must
+    allow *every* ``X.Y`` patch; that is always the minor below the bound's:
+    ``<3.12`` -> ``3.11``, ``<=3.12`` -> ``3.11``, ``<3.12.4`` -> ``3.11``
+    (``3.12`` would install a patch that may exceed ``3.12.4``). Returns
+    ``None`` for other operators or when no minor version can be picked
+    (``<4``, ``<3.0``).
+    """
+    if operator not in {"<", "<="}:
+        return None
+    try:
+        release = version.Version(version_str).release
+    except version.InvalidVersion:
+        return None
+    if len(release) < 2:
+        return None
+    major, minor = release[0], release[1] - 1
+    if minor < 0:
+        return None
+    return major, minor
+
+
 def _concrete_install_target(interpreter: str) -> str | None:
     """Return a concrete version to hand to an installer, or ``None``.
 
     Non-range specs (names, concrete versions, paths) are returned unchanged.
     For a PEP 440 range (``>=3.14``) the floor of the first lower-bound clause
-    is returned (``3.14``) so a concrete interpreter can be downloaded. A
-    non-CPython implementation prefix is preserved (``pypy>=3.10`` -> ``pypy3.10``)
-    so the right flavor is installed; the floor already carries any free-threaded
-    ``t`` suffix. Upper-bound-only (``<3.14``) or ``!=`` ranges have no
-    installable floor and return ``None``.
+    is returned (``3.14``) so a concrete interpreter can be downloaded. Without
+    a lower bound, the highest version under the tightest upper bound that the
+    other clauses allow is used instead (``<3.12`` -> ``3.11``,
+    ``<3.14,!=3.13.*`` -> ``3.12``). A non-CPython implementation prefix is
+    preserved (``pypy>=3.10`` -> ``pypy3.10``) so the right flavor is installed;
+    the version already carries any free-threaded ``t`` suffix. Ranges with no
+    usable bound (``!=3.12``, ``<4``) return ``None``.
     """
     from python_discovery import PythonSpec  # noqa: PLC0415
 
     spec = PythonSpec.from_string_spec(interpreter)
     if spec.version_specifier is None:
         return interpreter
+    impl = spec.implementation
+    prefix = impl if impl and impl != "cpython" else ""
     for specifier in spec.version_specifier.specifiers:
         if specifier.operator in {">=", "==", "~=", ">"}:
-            impl = spec.implementation
-            prefix = impl if impl and impl != "cpython" else ""
             return f"{prefix}{specifier.version_str}"
+
+    # python-discovery's specifiers don't understand the free-threaded "t"
+    # suffix, so strip it up front and do the version arithmetic with packaging.
+    suffix = (
+        "t"
+        if any(s.version_str.endswith("t") for s in spec.version_specifier.specifiers)
+        else ""
+    )
+    clauses = [
+        (s.operator, s.version_str.removesuffix("t"))
+        for s in spec.version_specifier.specifiers
+    ]
+    candidates = [
+        candidate
+        for op, ver in clauses
+        if (candidate := _highest_under_upper_bound(op, ver)) is not None
+    ]
+    if not candidates:
+        return None
+    try:
+        allowed = specifiers.SpecifierSet(",".join(f"{op}{ver}" for op, ver in clauses))
+    except specifiers.InvalidSpecifier:
+        return None
+    # The tightest upper bound wins, but another clause (an "!=") can exclude
+    # the pick, so step down through the minors until one clears the whole set.
+    major, top_minor = min(candidates)
+    for minor in range(top_minor, -1, -1):
+        if allowed.contains(f"{major}.{minor}"):
+            return f"{prefix}{major}.{minor}{suffix}"
     return None
 
 
@@ -865,9 +922,10 @@ def _resolved_interpreter(self) -> str:
     def _install_python(self, interpreter: str) -> str | None:
         """Install the requested interpreter for this backend, if possible.
 
-        For a version range the floor is installed (e.g. ``>=3.14`` -> ``3.14``);
-        ranges with no installable floor return ``None``. Returns the resolved
-        interpreter on success, or ``None`` on failure.
+        For a version range a concrete version is installed (e.g. ``>=3.14`` ->
+        ``3.14``, ``<3.12`` -> ``3.11``); ranges with no usable bound return
+        ``None``. Returns the resolved interpreter on success, or ``None`` on
+        failure.
         """
         target = _concrete_install_target(interpreter)
         if target is None:

tests/test_virtualenv.py

@@ -1307,7 +1307,25 @@ def boom(*args: object, **kwargs: object) -> NoReturn:
         ("pypy>=3.10", "pypy3.10"),
         ("cpython>=3.12", "3.12"),
         (">=3.13t", "3.13t"),
-        ("<3.14", None),
+        ("<3.14", "3.13"),
+        ("<=3.14", "3.13"),
+        ("<3.14.4", "3.13"),
+        ("<=3.14.4", "3.13"),
+        ("<3.14.0", "3.13"),
+        ("<3.14t", "3.13t"),
+        ("pypy<3.11", "pypy3.10"),
+        ("<3.14,<3.12", "3.11"),
+        ("<3.12,!=3.11.*", "3.10"),
+        ("<3.14,!=3.13.*", "3.12"),
+        ("<3.14,!=3.13.*,!=3.12.*", "3.11"),
+        ("<3.14t,!=3.13.*", "3.12t"),
+        ("<3.13,<3.14t", "3.12t"),
+        ("<3.1,!=3.0.*", None),
+        # python-discovery's permissive grammar accepts these; packaging can't.
+        ("<3.12.", None),
+        ("<3.14,<3.12.", None),
+        ("<4", None),
+        ("<3.0", None),
         ("!=3.12", None),
     ],
 )
@@ -1816,19 +1834,43 @@ def test_download_python_range_installs_floor(
 
 
 @pytest.mark.parametrize("download_python", ["always", "auto"])
-@mock.patch("nox.virtualenv.pbs_install_python")
-@mock.patch("nox.virtualenv.uv_install_python")
+@mock.patch(
+    "nox.virtualenv.pbs_install_python",
+    return_value="/.local/share/nox/cpython@3.13.0/bin/python3.13",
+)
+@mock.patch("nox.virtualenv.uv_install_python", return_value=True)
 def test_download_python_range_without_floor(
     uv_install_mock: mock.Mock,
     pbs_install_mock: mock.Mock,
     download_python: str,
     make_one: Callable[..., tuple[VirtualEnv, Path]],
     patch_discover: Callable[[str | None], list[str]],
 ) -> None:
-    # An upper-bound-only range has no installable floor: never install, error.
+    # An upper-bound-only range installs the highest version it allows.
     patch_discover(None)
     venv, _ = make_one(interpreter="<3.14", download_python=download_python)
 
+    assert (
+        venv._resolved_interpreter == "/.local/share/nox/cpython@3.13.0/bin/python3.13"
+    )
+    pbs_install_mock.assert_called_once_with("python3.13")
+    uv_install_mock.assert_not_called()
+
+
+@pytest.mark.parametrize("download_python", ["always", "auto"])
+@mock.patch("nox.virtualenv.pbs_install_python")
+@mock.patch("nox.virtualenv.uv_install_python")
+def test_download_python_range_without_bounds(
+    uv_install_mock: mock.Mock,
+    pbs_install_mock: mock.Mock,
+    download_python: str,
+    make_one: Callable[..., tuple[VirtualEnv, Path]],
+    patch_discover: Callable[[str | None], list[str]],
+) -> None:
+    # An exclusion-only range has no version to install: never install, error.
+    patch_discover(None)
+    venv, _ = make_one(interpreter="!=3.14", download_python=download_python)
+
     with pytest.raises(nox.virtualenv.InterpreterNotFound):
         _ = venv._resolved_interpreter