Make pip cache purge/pip cache remove delete additional unneeded files.

These commands now remove:
- wheel cache folders without `.whl` files.
- empty folders in the HTTP cache.
- `selfcheck.json`, which pip does not use anymore.

Author: duckinator

news/9058.feature.rst

@@ -0,0 +1,6 @@
+Make ``pip cache purge``/``pip cache remove`` delete additional unneeded files.
+
+These commands now remove:
+* wheel cache folders without ``.whl`` files.
+* empty folders in the HTTP cache.
+* some files created by old versions of pip, which aren't used anymore.

src/pip/_internal/commands/cache.py

@@ -189,7 +189,31 @@ def remove_cache_items(self, options: Values, args: list[str]) -> None:
             bytes_removed += os.stat(filename).st_size
             os.unlink(filename)
             logger.verbose("Removed %s", filename)
+
+        http_dirs = filesystem.subdirs_without_files(self._cache_dir(options, "http"))
+        wheel_dirs = filesystem.subdirs_without_wheels(
+            self._cache_dir(options, "wheels")
+        )
+        dirs = [*http_dirs, *wheel_dirs]
+
+        for subdir in dirs:
+            try:
+                for file in subdir.iterdir():
+                    file.unlink(missing_ok=True)
+                subdir.rmdir()
+            except FileNotFoundError:
+                # If the file is already gone, that's fine.
+                pass
+            logger.verbose("Removed %s", subdir)
+
+        # selfcheck.json is no longer used by pip.
+        selfcheck_json = self._cache_dir(options, "selfcheck.json")
+        if os.path.isfile(selfcheck_json):
+            os.remove(selfcheck_json)
+            logger.verbose("Removed legacy selfcheck.json file")
+
         logger.info("Files removed: %s (%s)", len(files), format_size(bytes_removed))
+        logger.info("Directories removed: %s", len(dirs))
 
     def purge_cache(self, options: Values, args: list[str]) -> None:
         if args:

src/pip/_internal/utils/filesystem.py

@@ -7,6 +7,7 @@
 import sys
 from collections.abc import Generator
 from contextlib import contextmanager
+from pathlib import Path
 from tempfile import NamedTemporaryFile
 from typing import Any, BinaryIO, cast
 
@@ -150,3 +151,71 @@ def directory_size(path: str) -> int | float:
 
 def format_directory_size(path: str) -> str:
     return format_size(directory_size(path))
+
+
+def subdirs_without_files(path: str) -> Generator[Path]:
+    """Yields every subdirectory of +path+ that has no files under it."""
+
+    def inner(path: Path, parents: list[Path]) -> Generator[Path]:
+        path_obj = Path(path)
+
+        if not path_obj.exists():
+            return
+
+        subdirs = []
+        for item in path_obj.iterdir():
+            if item.is_dir():
+                subdirs.append(item)
+            else:
+                # If we find a file, we want to preserve the whole subtree,
+                # so bail immediately.
+                return
+
+        # If we get to this point, we didn't find a file yet.
+
+        if parents is None:
+            parents = []
+        else:
+            parents += [path_obj]
+
+        if subdirs:
+            for subdir in subdirs:
+                yield from inner(subdir, parents)
+        else:
+            yield from parents
+
+    yield from sorted(set(inner(Path(path), [])), reverse=True)
+
+
+def subdirs_without_wheels(path: str) -> Generator[Path]:
+    """Yields every subdirectory of +path+ that has no .whl files under it."""
+
+    def inner(path: str | Path, parents: list[Path]) -> Generator[Path]:
+        path_obj = Path(path)
+
+        if not path_obj.exists():
+            return
+
+        subdirs = []
+        for item in path_obj.iterdir():
+            if item.is_dir():
+                subdirs.append(item)
+            elif item.name.endswith(".whl"):
+                # If we found a wheel, we want to preserve this whole subtree,
+                # so we bail immediately and don't return any results.
+                return
+
+        # If we get to this point, we didn't find a wheel yet.
+
+        if parents is None:
+            parents = []
+        else:
+            parents += [path_obj]
+
+        if subdirs:
+            for subdir in subdirs:
+                yield from inner(subdir, parents)
+        else:
+            yield from parents
+
+    yield from sorted(set(inner(path, [])), reverse=True)

tests/functional/test_cache.py

@@ -256,7 +256,7 @@ def test_cache_purge_with_empty_cache(script: PipTestEnvironment) -> None:
     and exit without an error code."""
     result = script.pip("cache", "purge", allow_stderr_warning=True)
     assert result.stderr == "WARNING: No matching packages\n"
-    assert result.stdout == "Files removed: 0 (0 bytes)\n"
+    assert result.stdout == "Files removed: 0 (0 bytes)\nDirectories removed: 0\n"
 
 
 @pytest.mark.usefixtures("populate_wheel_cache")
@@ -265,7 +265,7 @@ def test_cache_remove_with_bad_pattern(script: PipTestEnvironment) -> None:
     and exit without an error code."""
     result = script.pip("cache", "remove", "aaa", allow_stderr_warning=True)
     assert result.stderr == 'WARNING: No matching packages for pattern "aaa"\n'
-    assert result.stdout == "Files removed: 0 (0 bytes)\n"
+    assert result.stdout == "Files removed: 0 (0 bytes)\nDirectories removed: 0\n"
 
 
 def test_cache_list_too_many_args(script: PipTestEnvironment) -> None: