Add interpreter command

changelog.d/1248.feature.md

@@ -0,0 +1 @@
+Add commands to list and prune standalone interpreters

src/pipx/commands/__init__.py

@@ -2,6 +2,7 @@
 from pipx.commands.environment import environment
 from pipx.commands.inject import inject
 from pipx.commands.install import install
+from pipx.commands.interpreter import list_interpreters, prune_interpreters
 from pipx.commands.list_packages import list_packages
 from pipx.commands.reinstall import reinstall, reinstall_all
 from pipx.commands.run import run
@@ -25,4 +26,6 @@
     "run_pip",
     "ensure_pipx_paths",
     "environment",
+    "list_interpreters",
+    "prune_interpreters",
 ]

src/pipx/commands/interpreter.py

@@ -0,0 +1,78 @@
+from pathlib import Path
+from typing import List
+
+from pipx import constants
+from pipx.pipx_metadata_file import PipxMetadata
+from pipx.util import rmdir
+from pipx.venv import Venv, VenvContainer
+
+
+def get_installed_standalone_interpreters() -> List[Path]:
+    return [python_dir for python_dir in constants.PIPX_STANDALONE_PYTHON_CACHEDIR.iterdir() if python_dir.is_dir()]
+
+
+def get_venvs_using_standalone_interpreter(venv_container: VenvContainer) -> List[Venv]:
+    venvs: list[Venv] = []
+    for venv_dir in venv_container.iter_venv_dirs():
+        venv = Venv(venv_dir)
+        if venv.pipx_metadata.source_interpreter:
+            venvs.append(venv)
+    return venvs
+
+
+def get_interpreter_users(interpreter: Path, venvs: List[Venv]) -> List[PipxMetadata]:
+    def is_paths_relative(path: Path, parent: Path):
+        # Can be replaced with path.is_relative_to() if support for python3.8 is dropped
+        try:
+            path.resolve().relative_to(parent.resolve())
+            return True
+        except ValueError:
+            return False
+
+    return [
+        venv.pipx_metadata
+        for venv in venvs
+        if venv.pipx_metadata.source_interpreter
+        and is_paths_relative(venv.pipx_metadata.source_interpreter, interpreter)
+    ]
+
+
+def list_interpreters(
+    venv_container: VenvContainer,
+):
+    interpreters = get_installed_standalone_interpreters()
+    venvs = get_venvs_using_standalone_interpreter(venv_container)
+    output: list[str] = []
+    output.append(f"Standalone interpreters are in {constants.PIPX_STANDALONE_PYTHON_CACHEDIR}")
+    for interpreter in interpreters:
+        output.append(f"Python {interpreter.name}")
+        used_in = get_interpreter_users(interpreter, venvs)
+        if used_in:
+            output.append("    Used in:")
+            for p in used_in:
+                output.append(f"     - {p.main_package.package} {p.main_package.package_version}")
+        else:
+            output.append("    Unused")
+
+    print("\n".join(output))
+    return constants.EXIT_CODE_OK
+
+
+def prune_interpreters(
+    venv_container: VenvContainer,
+):
+    interpreters = get_installed_standalone_interpreters()
+    venvs = get_venvs_using_standalone_interpreter(venv_container)
+    removed = []
+    for interpreter in interpreters:
+        if get_interpreter_users(interpreter, venvs):
+            continue
+        rmdir(interpreter, safe_rm=True)
+        removed.append(interpreter.name)
+    if removed:
+        print("Successfully removed:")
+        for interpreter_name in removed:
+            print(f" - Python {interpreter_name}")
+    else:
+        print("Nothing to remove")
+    return constants.EXIT_CODE_OK

src/pipx/main.py

@@ -288,6 +288,13 @@ def run_pipx_command(args: argparse.Namespace) -> ExitCode:  # noqa: C901
             args.short,
             args.skip_maintenance,
         )
+    elif args.command == "interpreter":
+        if args.interpreter_command == "list":
+            return commands.list_interpreters(venv_container)
+        elif args.interpreter_command == "prune":
+            return commands.prune_interpreters(venv_container)
+        else:
+            raise PipxError(f"Unknown interpreter command {args.interpreter_command}")
     elif args.command == "uninstall":
         return commands.uninstall(venv_dir, constants.LOCAL_BIN_DIR, constants.LOCAL_MAN_DIR, verbose)
     elif args.command == "uninstall-all":
@@ -588,6 +595,18 @@ def _add_list(subparsers: argparse._SubParsersAction, shared_parser: argparse.Ar
     g.add_argument("--skip-maintenance", action="store_true", help="Skip maintenance tasks.")
 
 
+def _add_interpreter(subparsers: argparse._SubParsersAction, shared_parser: argparse.ArgumentParser) -> None:
+    p: argparse.ArgumentParser = subparsers.add_parser(
+        "interpreter",
+        help="Interact with interpreters managed by pipx",
+        description="Interact with interpreters managed by pipx",
+        parents=[shared_parser],
+    )
+    s = p.add_subparsers(dest="interpreter_command")
+    s.add_parser("list", help="List available interpreters", description="List available interpreters")
+    s.add_parser("prune", help="Prune unused interpreters", description="Prune unused interpreters")
+
+
 def _add_run(subparsers: argparse._SubParsersAction, shared_parser: argparse.ArgumentParser) -> None:
     p = subparsers.add_parser(
         "run",
@@ -746,6 +765,7 @@ def get_command_parser() -> argparse.ArgumentParser:
     _add_reinstall(subparsers, completer_venvs.use, shared_parser)
     _add_reinstall_all(subparsers, shared_parser)
     _add_list(subparsers, shared_parser)
+    _add_interpreter(subparsers, shared_parser)
     _add_run(subparsers, shared_parser)
     _add_runpip(subparsers, completer_venvs.use, shared_parser)
     _add_ensurepath(subparsers, shared_parser)

src/pipx/standalone_python.py

@@ -13,8 +13,8 @@
 from typing import Any, Dict, List
 from urllib.request import urlopen
 
+from pipx import constants
 from pipx.animate import animate
-from pipx.constants import PIPX_STANDALONE_PYTHON_CACHEDIR, WINDOWS
 from pipx.util import PipxError
 
 logger = logging.getLogger(__name__)
@@ -58,8 +58,8 @@ def download_python_build_standalone(python_version: str):
     # we'll convert it to a bare version number
     python_version = re.sub(r"[c]?python", "", python_version)
 
-    install_dir = PIPX_STANDALONE_PYTHON_CACHEDIR / python_version
-    installed_python = install_dir / "python.exe" if WINDOWS else install_dir / "bin" / "python3"
+    install_dir = constants.PIPX_STANDALONE_PYTHON_CACHEDIR / python_version
+    installed_python = install_dir / "python.exe" if constants.WINDOWS else install_dir / "bin" / "python3"
 
     if installed_python.exists():
         return str(installed_python)
@@ -125,7 +125,7 @@ def _unpack(full_version, download_link, archive: Path, download_dir: Path):
 def get_or_update_index():
     """Get or update the index of available python builds from
     the python-build-standalone repository."""
-    index_file = PIPX_STANDALONE_PYTHON_CACHEDIR / "index.json"
+    index_file = constants.PIPX_STANDALONE_PYTHON_CACHEDIR / "index.json"
     if index_file.exists():
         index = json.loads(index_file.read_text())
         # update index after 30 days

tests/conftest.py

@@ -76,6 +76,7 @@ def pipx_temp_env_helper(pipx_shared_dir, tmp_path, monkeypatch, request, utils_
     monkeypatch.setattr(constants, "PIPX_HOME", home_dir)
     monkeypatch.setattr(constants, "LOCAL_BIN_DIR", bin_dir)
     monkeypatch.setattr(constants, "LOCAL_MAN_DIR", man_dir)
+    monkeypatch.setattr(constants, "PIPX_STANDALONE_PYTHON_CACHEDIR", home_dir / "py")
     monkeypatch.setattr(constants, "PIPX_LOCAL_VENVS", home_dir / "venvs")
     monkeypatch.setattr(constants, "PIPX_VENV_CACHEDIR", home_dir / ".cache")
     monkeypatch.setattr(constants, "PIPX_LOG_DIR", home_dir / "logs")

tests/test_standalone_interpreter.py

@@ -0,0 +1,108 @@
+import shutil
+import sys
+
+from helpers import (
+    run_pipx_cli,
+)
+from package_info import PKG
+
+MAJOR_PYTHON_VERSION = sys.version_info.major
+# Minor version 3.8 is not supported for fetching standalone versions
+MINOR_PYTHON_VERSION = sys.version_info.minor if sys.version_info.minor != 8 else 9
+TARGET_PYTHON_VERSION = f"{MAJOR_PYTHON_VERSION}.{MINOR_PYTHON_VERSION}"
+
+original_which = shutil.which
+
+
+def mock_which(name):
+    if name == TARGET_PYTHON_VERSION:
+        return None
+    return original_which(name)
+
+
+def test_list_no_standalone_interpreters(pipx_temp_env, monkeypatch, capsys):
+    assert not run_pipx_cli(["interpreter", "list"])
+
+    captured = capsys.readouterr()
+    assert "Standalone interpreters" in captured.out
+    assert len(captured.out.splitlines()) == 1
+
+
+def test_list_used_standalone_interpreters(pipx_temp_env, monkeypatch, mocked_github_api, capsys):
+    monkeypatch.setattr(shutil, "which", mock_which)
+
+    assert not run_pipx_cli(
+        [
+            "install",
+            "--fetch-missing-python",
+            "--python",
+            TARGET_PYTHON_VERSION,
+            PKG["pycowsay"]["spec"],
+        ]
+    )
+
+    capsys.readouterr()
+    assert not run_pipx_cli(["interpreter", "list"])
+
+    captured = capsys.readouterr()
+    assert TARGET_PYTHON_VERSION in captured.out
+    assert "pycowsay" in captured.out
+
+
+def test_list_unused_standalone_interpreters(pipx_temp_env, monkeypatch, mocked_github_api, capsys):
+    monkeypatch.setattr(shutil, "which", mock_which)
+
+    assert not run_pipx_cli(
+        [
+            "install",
+            "--fetch-missing-python",
+            "--python",
+            TARGET_PYTHON_VERSION,
+            PKG["pycowsay"]["spec"],
+        ]
+    )
+
+    assert not run_pipx_cli(["uninstall", "pycowsay"])
+    capsys.readouterr()
+    assert not run_pipx_cli(["interpreter", "list"])
+
+    captured = capsys.readouterr()
+    assert TARGET_PYTHON_VERSION in captured.out
+    assert "pycowsay" not in captured.out
+    assert "Unused" in captured.out
+
+
+def test_prune_unused_standalone_interpreters(pipx_temp_env, monkeypatch, mocked_github_api, capsys):
+    monkeypatch.setattr(shutil, "which", mock_which)
+
+    assert not run_pipx_cli(
+        [
+            "install",
+            "--fetch-missing-python",
+            "--python",
+            TARGET_PYTHON_VERSION,
+            PKG["pycowsay"]["spec"],
+        ]
+    )
+
+    capsys.readouterr()
+    assert not run_pipx_cli(["interpreter", "prune"])
+    captured = capsys.readouterr()
+    assert "Nothing to remove" in captured.out
+
+    assert not run_pipx_cli(["uninstall", "pycowsay"])
+    capsys.readouterr()
+
+    assert not run_pipx_cli(["interpreter", "prune"])
+    captured = capsys.readouterr()
+    assert "Successfully removed:" in captured.out
+    assert f"- Python {TARGET_PYTHON_VERSION}" in captured.out
+
+    assert not run_pipx_cli(["interpreter", "list"])
+    captured = capsys.readouterr()
+    assert "Standalone interpreters" in captured.out
+    assert len(captured.out.splitlines()) == 1
+
+    assert not run_pipx_cli(["interpreter", "prune"])
+    captured = capsys.readouterr()
+    assert "Nothing to remove" in captured.out