feat: support fallback for nox/mamba/conda

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

docs/usage.rst

@@ -163,6 +163,7 @@ Note that using this option does not change the backend for sessions where ``ven
    name from the install process like pip does if the name is omitted. Editable
    installs do not require a name.
 
+Backends that could be missing (``uv``, ``conda``, and ``mamba``) can have a fallback using ``|``, such as ``uv|virtualenv`` or ``mamba|conda``. This will use the first item that is available on the users system.
 
 .. _opt-force-venv-backend:
 

nox/sessions.py

@@ -760,15 +760,30 @@ def envdir(self) -> str:
     def _create_venv(self) -> None:
         reuse_existing = self.reuse_existing_venv()
 
-        backend = (
+        backends = (
             self.global_config.force_venv_backend
             or self.func.venv_backend
             or self.global_config.default_venv_backend
             or "virtualenv"
-        )
-
-        if backend not in nox.virtualenv.ALL_VENVS:
-            msg = f"Expected venv_backend one of {list(nox.virtualenv.ALL_VENVS)!r}, but got {backend!r}."
+        ).split("|")
+
+        # Support fallback backends
+        for bk in backends:
+            if bk not in nox.virtualenv.ALL_VENVS:
+                msg = f"Expected venv_backend one of {list(nox.virtualenv.ALL_VENVS)!r}, but got {bk!r}."
+                raise ValueError(msg)
+
+        for bk in backends[:-1]:
+            if bk not in nox.virtualenv.OPTIONAL_VENVS:
+                msg = f"Only optional backends ({list(nox.virtualenv.OPTIONAL_VENVS)!r}) may have a fallback, {bk!r} is not optional."
+                raise ValueError(msg)
+
+        for bk in backends:
+            if nox.virtualenv.OPTIONAL_VENVS.get(bk, True):
+                backend = bk
+                break
+        else:
+            msg = f"No backends present, looked for {backends!r}."
             raise ValueError(msg)
 
         if backend == "none" or self.func.python is False:

nox/virtualenv.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import abc
 import contextlib
 import functools
 import os
@@ -44,7 +45,7 @@ def __init__(self, interpreter: str) -> None:
         self.interpreter = interpreter
 
 
-class ProcessEnv:
+class ProcessEnv(abc.ABC):
     """An environment with a 'bin' directory and a set of 'env' vars."""
 
     location: str
@@ -85,8 +86,12 @@ def bin(self) -> str:
             raise ValueError("The environment does not have a bin directory.")
         return paths[0]
 
+    @abc.abstractmethod
     def create(self) -> bool:
-        raise NotImplementedError("ProcessEnv.create should be overwritten in subclass")
+        """Create a new environment.
+
+        Returns True if the environment is new, and False if it was reused.
+        """
 
 
 def locate_via_py(version: str) -> str | None:
@@ -170,6 +175,11 @@ def is_offline() -> bool:
         """As of now this is only used in conda_install"""
         return CondaEnv.is_offline()  # pragma: no cover
 
+    def create(self) -> bool:
+        """Does nothing, since this is an existing environment. Always returns
+        False since it's always reused."""
+        return False
+
 
 class CondaEnv(ProcessEnv):
     """Conda environment management class.
@@ -543,3 +553,12 @@ def create(self) -> bool:
     "uv": functools.partial(VirtualEnv, venv_backend="uv"),
     "none": PassthroughEnv,
 }
+
+# Any environment in this dict could be missing, and is only available if the
+# value is True. If an environment is always available, it should not be in this
+# dict. "virtualenv" is not considered optional since it's a dependency of nox.
+OPTIONAL_VENVS = {
+    "conda": shutil.which("conda") is not None,
+    "mamba": shutil.which("mamba") is not None,
+    "uv": shutil.which("uv") is not None,
+}

tests/test_sessions.py

@@ -309,7 +309,7 @@ def test_run_external_not_a_virtualenv(self):
         # Non-virtualenv sessions should always allow external programs.
         session, runner = self.make_session_and_runner()
 
-        runner.venv = nox.virtualenv.ProcessEnv()
+        runner.venv = nox.virtualenv.PassthroughEnv()
 
         with mock.patch("nox.command.run", autospec=True) as run:
             session.run(sys.executable, "--version")
@@ -402,7 +402,7 @@ def test_run_shutdown_process_timeouts(
     ):
         session, runner = self.make_session_and_runner()
 
-        runner.venv = nox.virtualenv.ProcessEnv()
+        runner.venv = nox.virtualenv.PassthroughEnv()
 
         subp_popen_instance = mock.Mock()
         subp_popen_instance.communicate.side_effect = KeyboardInterrupt()
@@ -963,6 +963,44 @@ def test__create_venv_unexpected_venv_backend(self):
         with pytest.raises(ValueError, match="venv_backend"):
             runner._create_venv()
 
+    @pytest.mark.parametrize(
+        "venv_backend",
+        ["uv|virtualenv", "conda|virtualenv", "mamba|conda|venv"],
+    )
+    def test_fallback_venv(self, venv_backend, monkeypatch):
+        runner = self.make_runner()
+        runner.func.venv_backend = venv_backend
+        monkeypatch.setattr(
+            nox.virtualenv,
+            "OPTIONAL_VENVS",
+            {"uv": False, "conda": False, "mamba": False},
+        )
+        with mock.patch("nox.virtualenv.VirtualEnv.create", autospec=True):
+            runner._create_venv()
+        assert runner.venv.venv_backend == venv_backend.split("|")[-1]
+
+    @pytest.mark.parametrize(
+        "venv_backend",
+        [
+            "uv|virtualenv|unknown",
+            "conda|unknown|virtualenv",
+            "virtualenv|venv",
+            "conda|mamba",
+        ],
+    )
+    def test_invalid_fallback_venv(self, venv_backend, monkeypatch):
+        runner = self.make_runner()
+        runner.func.venv_backend = venv_backend
+        monkeypatch.setattr(
+            nox.virtualenv,
+            "OPTIONAL_VENVS",
+            {"uv": False, "conda": False, "mamba": False},
+        )
+        with mock.patch(
+            "nox.virtualenv.VirtualEnv.create", autospec=True
+        ), pytest.raises(ValueError):
+            runner._create_venv()
+
     @pytest.mark.parametrize(
         ("reuse_venv", "reuse_venv_func", "should_reuse"),
         [

tests/test_virtualenv.py

@@ -113,24 +113,23 @@ def special_run(cmd, *args, **kwargs):
 
 
 def test_process_env_constructor():
-    penv = nox.virtualenv.ProcessEnv()
+    penv = nox.virtualenv.PassthroughEnv()
     assert not penv.bin_paths
     with pytest.raises(
         ValueError, match=r"^The environment does not have a bin directory\.$"
     ):
         print(penv.bin)
 
-    penv = nox.virtualenv.ProcessEnv(env={"SIGIL": "123"})
+    penv = nox.virtualenv.PassthroughEnv(env={"SIGIL": "123"})
     assert penv.env["SIGIL"] == "123"
 
-    penv = nox.virtualenv.ProcessEnv(bin_paths=["/bin"])
+    penv = nox.virtualenv.PassthroughEnv(bin_paths=["/bin"])
     assert penv.bin == "/bin"
 
 
 def test_process_env_create():
-    penv = nox.virtualenv.ProcessEnv()
-    with pytest.raises(NotImplementedError):
-        penv.create()
+    with pytest.raises(TypeError):
+        nox.virtualenv.ProcessEnv()
 
 
 def test_invalid_venv_create(make_one):