Add option to use temporary venv to Pip (#20)

Until now the `Pip` build environment only supported a pre-existing python venv which would be the same for all versions of the docs. This is certainly not intended. This is now fixed by introducing the `temporary` keyword. When specified a new python venv will be created for each version in a subdirectory of the temporary build directory.

* README.md : Add example.
* sphinx_polyversion/pyvenv.py (Pip): Implement new `temporary` keyword.
* tests/test_pyvenv.py : Test new behaviour.

Author: vpratz

README.md

@@ -186,7 +186,10 @@ ENVIRONMENT = {
     None: Poetry.factory(args="--sync".split()),  # first version
     "v1.5.7": Poetry.factory(args="--only sphinx --sync".split()),
     "v1.8.2": Poetry.factory(args="--only dev --sync".split(), env={"MY_VAR": "value"}),
+    # use a pre-existing environment at the location ./.venv
     "v3.0.0": Pip.factory(venv=Path(".venv"), args="-e . -r requirements.txt".split()),
+    # dynamically create an environment in the temporary build directory
+    "v4.*.*": Pip.factory(venv=Path(".venv"), args="-e . -r requirements.txt".split(), creator=VenvWrapper(), temporary=True),
 }
 
 # ...

sphinx_polyversion/pyvenv.py

@@ -412,6 +412,10 @@ class Pip(VirtualPythonEnvironment):
         The cmd arguments to pass to `pip install`.
     creator : Callable[[Path], Any] | None, optional
         A callable for creating the venv, by default None
+    temporary   : bool, optional
+        A flag to specify whether the environment should be created in the
+        temporary directory, by default False. If this is True, `creator`
+        must not be None and `venv` will be treated relative to `path`.
     env  : dict[str, str], optional
         A dictionary of environment variables which are overridden in the
         virtual environment, by default None
@@ -426,6 +430,7 @@ def __init__(
         *,
         args: Iterable[str],
         creator: Callable[[Path], Any] | None = None,
+        temporary: bool = False,
         env: dict[str, str] | None = None,
     ):
         """
@@ -443,11 +448,29 @@ def __init__(
             The cmd arguments to pass to `pip install`.
         creator : Callable[[Path], Any], optional
             A callable for creating the venv, by default None
+        temporary   : bool, optional
+            A flag to specify whether the environment should be created in the
+            temporary directory, by default False. If this is True, `creator`
+            must not be None and `venv` will be treated relative to `path`.
         env  : dict[str, str], optional
             A dictionary of environment variables which are overridden in the
             virtual environment, by default None
 
+        Raises
+        ------
+        ValueError
+            If `temporary` is enabled but no valid creator is provided.
+
         """
+        if temporary:
+            if creator is None:
+                raise ValueError(
+                    "Cannot create temporary virtual environment when creator is None.\n"
+                    "Please set creator to enable temporary virtual environments, or "
+                    "set temporary to False to use a pre-existing local environment "
+                    f"at path '{venv}'."
+                )
+            venv = path / venv
         super().__init__(path, name, venv, creator=creator, env=env)
         self.args = args
 

tests/test_pyvenv.py

@@ -127,6 +127,122 @@ async def test_run_with_env_variables(self, tmp_path: Path):
 class TestPip:
     """Test the `Pip` class."""
 
+    @pytest.mark.asyncio
+    @pytest.mark.asyncio
+    async def test_creation_with_venv(self, tmp_path: Path):
+        """Test the `create_venv` method with a `VenvWrapper`."""
+        location = tmp_path / "venv"
+        env = Pip(
+            tmp_path,
+            "main",
+            location,
+            args=["tomli"],
+            creator=VenvWrapper(),
+            temporary=False,
+        )
+
+        await env.create_venv()
+        assert (location / "bin" / "python").exists()
+
+    @pytest.mark.asyncio
+    async def test_creation_without_creator(self, tmp_path: Path):
+        """Test the `create_venv` method without any creator."""
+        location = tmp_path / "venv"
+        env = Pip(tmp_path, "main", location, args=["tomli"], temporary=False)
+
+        await env.create_venv()
+        assert not (location / "bin" / "python").exists()
+
+    @pytest.mark.asyncio
+    async def test_run_without_creator(self, tmp_path: Path):
+        """Test running a command in an existing venv."""
+        location = tmp_path / "venv"
+
+        # create env
+        await VenvWrapper([])(location)
+
+        async with Pip(
+            tmp_path, "main", location, args=["tomli"], temporary=False
+        ) as env:
+            out, err, rc = await env.run(
+                "python",
+                "-c",
+                "import sys; print(sys.prefix)",
+                stdout=asyncio.subprocess.PIPE,
+            )
+            assert rc == 0
+            assert str(location) == out.strip()
+
+    @pytest.mark.asyncio
+    async def test_run_with_creator(self, tmp_path: Path):
+        """Test running a command in a new venv."""
+        location = tmp_path / "venv"
+
+        async with Pip(
+            tmp_path,
+            "main",
+            location,
+            args=["tomli"],
+            creator=VenvWrapper(),
+            temporary=False,
+        ) as env:
+            out, err, rc = await env.run(
+                "python",
+                "-c",
+                "import sys; print(sys.prefix)",
+                stdout=asyncio.subprocess.PIPE,
+            )
+            assert rc == 0
+            assert str(location) == out.strip()
+
+    @pytest.mark.asyncio
+    async def test_creation_with_venv_temporary(self, tmp_path: Path):
+        """Test the `create_venv` method with a `VenvWrapper`."""
+        location = "tmpvenv"
+        env = Pip(
+            tmp_path,
+            "main",
+            location,
+            args=["tomli"],
+            creator=VenvWrapper(),
+            temporary=True,
+        )
+
+        await env.create_venv()
+        assert (tmp_path / location / "bin" / "python").exists()
+
+    @pytest.mark.asyncio
+    async def test_creation_without_creator_temporary(self, tmp_path: Path):
+        """Test the `create_venv` method without any creator."""
+        location = "tmpvenv"
+        with pytest.raises(
+            ValueError,
+            match="Cannot create temporary virtual environment when creator is None",
+        ):
+            Pip(tmp_path, "main", location, args=["tomli"], temporary=True)
+
+    @pytest.mark.asyncio
+    async def test_run_with_creator_temporary(self, tmp_path: Path):
+        """Test running a command in a new venv."""
+        location = "tmpvenv"
+
+        async with Pip(
+            tmp_path,
+            "main",
+            location,
+            args=["tomli"],
+            creator=VenvWrapper(),
+            temporary=True,
+        ) as env:
+            out, err, rc = await env.run(
+                "python",
+                "-c",
+                "import sys; print(sys.prefix)",
+                stdout=asyncio.subprocess.PIPE,
+            )
+            assert rc == 0
+            assert str(tmp_path / location) == out.strip()
+
     @pytest.mark.asyncio
     async def test_install_into_existing_venv(self, tmp_path: Path):
         """Test installing a package into an existing venv."""