killpy 0.25.0__tar.gz → 0.25.1__tar.gz

{killpy-0.25.0 → killpy-0.25.1}/PKG-INFO

@@ -1,17 +1,25 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.25.0
-Summary: List all .venv directories and Conda environments 🐍 on your system and check how much space they are using. You can then choose which ones to delete in order to free up space 🧹.
+Version: 0.25.1
+Summary: Find and delete unused Python environments (.venv, conda, poetry, pipenv, pipx, pyenv, uv) and caches to free disk space — from a fast terminal UI or a single CLI command.
 Project-URL: Homepage, https://github.com/Tlaloc-Es/killpy
 Project-URL: Documentation, https://tlaloc-es.github.io/killpy/
 Project-URL: Repository, https://github.com/Tlaloc-Es/killpy
 Project-URL: Bug Tracker, https://github.com/Tlaloc-Es/killpy/issues
+Keywords: venv,virtualenv,conda,poetry,pipenv,pipx,pyenv,uv,cleanup,disk-space,cache,cli,tui,textual,developer-tools
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.1.8
@@ -596,7 +604,7 @@ ______________________________________________________________________
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.24.1
+  rev: 0.25.1
   hooks:
     - id: killpy                  # remove __pycache__ on every commit
     - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
@@ -621,7 +629,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.25.0
+  rev: 0.25.1
   hooks:
     - id: killpy
 ```

{killpy-0.25.0 → killpy-0.25.1}/README.md

@@ -575,7 +575,7 @@ ______________________________________________________________________
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.24.1
+  rev: 0.25.1
   hooks:
     - id: killpy                  # remove __pycache__ on every commit
     - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
@@ -600,7 +600,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.25.0
+  rev: 0.25.1
   hooks:
     - id: killpy
 ```

{killpy-0.25.0 → killpy-0.25.1}/killpy/__main__.py

@@ -1,3 +1,7 @@
+"""killpy CLI entry point: the ``cli`` click group and its subcommands."""
+
+from __future__ import annotations
+
 import logging
 import sys
 from pathlib import Path
@@ -10,7 +14,7 @@ from rich.prompt import Confirm
 from killpy.cleaner import Cleaner, CleanerError
 from killpy.cli import TableApp
 from killpy.commands._utils import partition_in_use
-from killpy.commands.clean import clean
+from killpy.commands.clean import clean_cmd
 from killpy.commands.delete import delete_cmd
 from killpy.commands.doctor import doctor_cmd
 from killpy.commands.find import find_cmd
@@ -144,7 +148,7 @@ def cli(ctx, path: Path, exclude: str, delete_all: bool, yes: bool, force: bool)
             app.run()
 
 
-cli.add_command(clean)
+cli.add_command(clean_cmd, name="clean")
 cli.add_command(list_cmd, name="list")
 cli.add_command(delete_cmd, name="delete")
 cli.add_command(stats_cmd, name="stats")

{killpy-0.25.0 → killpy-0.25.1}/killpy/cleaners/__init__.py

@@ -1,3 +1,7 @@
+"""Stateless ``__pycache__`` removal helper used by ``killpy clean``."""
+
+from __future__ import annotations
+
 import os
 import shutil
 from pathlib import Path

{killpy-0.25.0 → killpy-0.25.1}/killpy/cli.py

@@ -1,3 +1,7 @@
+"""Interactive Textual TUI (``TableApp``) for browsing and deleting environments."""
+
+from __future__ import annotations
+
 import asyncio
 import re
 import subprocess
@@ -44,7 +48,7 @@ def _health_text(category: str) -> Text | str:
     return ""
 
 
-def is_venv_tab(func):
+def _is_venv_tab(func):
     def wrapper(self, *args, **kwargs):
         if self.query_one(TabbedContent).active == "venv-tab":
             return func(self, *args, **kwargs)
@@ -52,7 +56,7 @@ def is_venv_tab(func):
     return wrapper
 
 
-def is_pipx_tab(func):
+def _is_pipx_tab(func):
     def wrapper(self, *args, **kwargs):
         if self.query_one(TabbedContent).active == "pipx-tab":
             return func(self, *args, **kwargs)
@@ -60,7 +64,7 @@ def is_pipx_tab(func):
     return wrapper
 
 
-def shorten_path_for_table(path_value, max_parts: int = 2) -> str:
+def _shorten_path_for_table(path_value, max_parts: int = 2) -> str:
     path_text = str(path_value)
     if "/" not in path_text and "\\" not in path_text:
         return path_text
@@ -349,7 +353,7 @@ class TableApp(App):
             "type"
         ]
         table.add_row(
-            shorten_path_for_table(row["path"]),
+            _shorten_path_for_table(row["path"]),
             type_label,
             row["last_modified"],
             row["size"],
@@ -391,7 +395,7 @@ class TableApp(App):
                 "type"
             ]
             table.add_row(
-                shorten_path_for_table(row["path"]),
+                _shorten_path_for_table(row["path"]),
                 type_label,
                 row["last_modified"],
                 row["size"],
@@ -609,12 +613,16 @@ class TableApp(App):
             row["health"] = self._health_by_path.get(row["path"], "")
         self.render_venv_table()
 
-    async def action_clean_pycache(self):
-        total_freed_space = await asyncio.to_thread(remove_pycache, self.root_dir)
-        self.bytes_release += total_freed_space
+    def _show_bytes_released(self) -> None:
+        """Update the status label with the running total of freed space."""
         self.query_one("#status-label", Label).update(
             f"{format_size(self.bytes_release)} deleted"
         )
+
+    async def action_clean_pycache(self):
+        total_freed_space = await asyncio.to_thread(remove_pycache, self.root_dir)
+        self.bytes_release += total_freed_space
+        self._show_bytes_released()
         self.bell()
 
     def on_data_table_row_highlighted(self, event: DataTable.RowHighlighted) -> None:
@@ -633,7 +641,7 @@ class TableApp(App):
             _, row = resolved
             selected_path_label.update(f"Selected: {row['path']}")
 
-    @is_venv_tab
+    @_is_venv_tab
     def action_confirm_delete(self):
         freed_now = 0
         if self._multi_select_mode and self._selected_venv_paths:
@@ -662,12 +670,10 @@ class TableApp(App):
 
         self._record_deletion(freed_now)
         self.render_venv_table()
-        self.query_one("#status-label", Label).update(
-            f"{format_size(self.bytes_release)} deleted"
-        )
+        self._show_bytes_released()
         self.bell()
 
-    @is_venv_tab
+    @_is_venv_tab
     def action_mark_for_delete(self):
         table = self.query_one("#venv-table", DataTable)
 
@@ -690,7 +696,7 @@ class TableApp(App):
                     EnvStatus.MARKED_TO_DELETE.value,
                 )
 
-    @is_venv_tab
+    @_is_venv_tab
     def action_delete_now(self):
         table = self.query_one("#venv-table", DataTable)
         cursor_cell = table.cursor_coordinate
@@ -709,9 +715,7 @@ class TableApp(App):
                     (cursor_cell.row, self.VENV_COL_STATUS),
                     EnvStatus.DELETED.value,
                 )
-                self.query_one("#status-label", Label).update(
-                    f"{format_size(self.bytes_release)} deleted"
-                )
+                self._show_bytes_released()
         self.bell()
 
     def delete_environment(self, environment: Environment) -> bool:
@@ -729,7 +733,7 @@ class TableApp(App):
             self.query_one("#status-label", Label).update(str(error))
             return False
 
-    @is_pipx_tab
+    @_is_pipx_tab
     def action_uninstall_pipx(self):
         table = self.query_one("#pipx-table", DataTable)
         cursor_cell = table.cursor_coordinate
@@ -742,9 +746,7 @@ class TableApp(App):
                 table.update_cell_at((cursor_cell.row, 3), EnvStatus.DELETED.value)
                 self.bytes_release += int(row["size"])
                 self._record_deletion(int(row["size"]))
-                self.query_one("#status-label", Label).update(
-                    f"{format_size(self.bytes_release)} deleted"
-                )
+                self._show_bytes_released()
 
         self.bell()
 
@@ -772,7 +774,7 @@ class TableApp(App):
             tid = "#venv-table" if active == "venv-tab" else "#pipx-table"
             self.query_one(tid, DataTable).action_cursor_up()
 
-    @is_venv_tab
+    @_is_venv_tab
     def action_open_folder(self) -> None:
         """Open the parent directory of the selected environment in the OS file manager."""  # noqa: E501
         table = self.query_one("#venv-table", DataTable)
@@ -834,7 +836,7 @@ class TableApp(App):
         self._update_multi_select_label()
         self.render_venv_table()
 
-    @is_venv_tab
+    @_is_venv_tab
     def action_multi_select_toggle_row(self) -> None:
         """Toggle current row selection in multi-select mode (Space key)."""
         if not self._multi_select_mode:
@@ -859,7 +861,7 @@ class TableApp(App):
             self._compute_row_status(row),
         )
 
-    @is_venv_tab
+    @_is_venv_tab
     def action_multi_select_all(self) -> None:
         """Toggle select-all / deselect-all in multi-select mode (A key)."""
         if not self._multi_select_mode:

{killpy-0.25.0 → killpy-0.25.1}/killpy/commands/clean.py

@@ -1,3 +1,7 @@
+"""``killpy clean`` – remove ``__pycache__`` directories under a path."""
+
+from __future__ import annotations
+
 from pathlib import Path
 
 import click
@@ -6,14 +10,15 @@ from killpy.cleaners import remove_pycache
 from killpy.files import format_size
 
 
-@click.command()
+@click.command("clean")
 @click.option(
     "--path",
     default=Path.cwd,
     type=click.Path(path_type=Path, exists=True, file_okay=False, dir_okay=True),
     help="Path to the directory to clean",
 )
-def clean(path: Path):
+def clean_cmd(path: Path) -> None:
+    """Remove all ``__pycache__`` directories under PATH and report freed space."""
     click.echo(f"Cleaning {path}…")
     total_freed_space = remove_pycache(path)
     click.echo(f"{format_size(total_freed_space)} freed")

{killpy-0.25.0 → killpy-0.25.1}/killpy/commands/doctor.py

@@ -13,12 +13,13 @@ from rich.table import Table
 from killpy.detectors import ALL_DETECTORS
 from killpy.files import format_size
 from killpy.intelligence import SuggestionEngine, UsageTracker, score_all
-from killpy.models import Suggestion
+from killpy.models import ScoredEnvironment, Suggestion
 from killpy.scanner import Scanner
 
-# Environments smaller than this threshold are excluded from "wasted" totals.
+# HIGH-category environments below this size don't count toward "wasted" totals.
 _IMPACTFUL_SIZE_BYTES = 10 * 1024 * 1024  # 10 MB
-_SMALL_SIZE_BYTES = 1 * 1024 * 1024  # 1 MB (matches suggestions.py)
+# Environments below this size are reported as "ignored (too small to matter)".
+_SMALL_SIZE_BYTES = 1 * 1024 * 1024  # 1 MB
 
 _CATEGORY_STYLE = {
     "HIGH": "bold red",
@@ -78,7 +79,7 @@ def doctor_cmd(path: Path, as_json: bool, show_all: bool) -> None:
     suggestions = engine.classify_all(scored_envs)
 
     if as_json:
-        _output_json(suggestions, envs)
+        _output_json(suggestions, scored_envs)
         return
 
     _output_rich(console, suggestions, scored_envs, path, show_all=show_all)
@@ -89,39 +90,47 @@ def doctor_cmd(path: Path, as_json: bool, show_all: bool) -> None:
 # ---------------------------------------------------------------------------
 
 
-def _output_json(suggestions: list[Suggestion], envs) -> None:  # type: ignore[type-arg]
-    total_size = sum(e.size_bytes for e in envs)
-    env_by_path = {e.path: e for e in envs}
-    high = [s for s in suggestions if s.category == "HIGH"]
+def _summarise(
+    suggestions: list[Suggestion],
+    scored_envs: list[ScoredEnvironment],
+) -> tuple[int, int, dict[str, int]]:
+    """Return ``(total_size_bytes, wasted_bytes, category_counts)``.
+
+    *wasted* sums the sizes of HIGH-category environments at or above
+    :data:`_IMPACTFUL_SIZE_BYTES`; *category_counts* maps each category to the
+    number of suggestions in it.  Computed once and shared by both output paths.
+    """
+    total_size = sum(se.env.size_bytes for se in scored_envs)
+    high_paths = {s.env_path for s in suggestions if s.category == "HIGH"}
     wasted = sum(
-        env_by_path[s.env_path].size_bytes
-        for s in high
-        if s.env_path in env_by_path
-        and env_by_path[s.env_path].size_bytes >= _IMPACTFUL_SIZE_BYTES
+        se.env.size_bytes
+        for se in scored_envs
+        if se.env.path in high_paths and se.env.size_bytes >= _IMPACTFUL_SIZE_BYTES
+    )
+    counts = {
+        "HIGH": sum(1 for s in suggestions if s.category == "HIGH"),
+        "MEDIUM": sum(1 for s in suggestions if s.category == "MEDIUM"),
+        "LOW": sum(1 for s in suggestions if s.category == "LOW"),
+    }
+    return total_size, wasted, counts
+
+
+def _output_json(
+    suggestions: list[Suggestion], scored_envs: list[ScoredEnvironment]
+) -> None:
+    total_size, wasted, counts = _summarise(suggestions, scored_envs)
+    ignored_small = sum(
+        1 for se in scored_envs if se.env.size_bytes < _SMALL_SIZE_BYTES
     )
-    ignored_small = sum(1 for e in envs if e.size_bytes < _SMALL_SIZE_BYTES)
     data = {
-        "total_environments": len(envs),
+        "total_environments": len(scored_envs),
         "total_size_bytes": total_size,
         "total_size_human": format_size(total_size),
         "wasted_size_bytes": wasted,
         "wasted_size_human": format_size(wasted),
         "ignored_small_envs_count": ignored_small,
-        "counts": {
-            "HIGH": sum(1 for s in suggestions if s.category == "HIGH"),
-            "MEDIUM": sum(1 for s in suggestions if s.category == "MEDIUM"),
-            "LOW": sum(1 for s in suggestions if s.category == "LOW"),
-        },
-        "suggestions": [
-            {
-                "env_path": str(s.env_path),
-                "score": s.score,
-                "category": s.category,
-                "reasons": s.reasons,
-                "recommended_action": s.recommended_action,
-            }
-            for s in suggestions
-        ],
+        "counts": counts,
+        "suggestions": [s.to_dict() for s in suggestions],
     }
     click.echo(json.dumps(data, indent=2))
 
@@ -129,19 +138,12 @@ def _output_json(suggestions: list[Suggestion], envs) -> None:  # type: ignore[t
 def _output_rich(
     console: Console,
     suggestions: list[Suggestion],
-    scored_envs,  # type: ignore[type-arg]
+    scored_envs: list[ScoredEnvironment],
     path: Path,
     *,
     show_all: bool = False,
 ) -> None:
-    total_size = sum(se.env.size_bytes for se in scored_envs)
-    high_suggestions = [s for s in suggestions if s.category == "HIGH"]
-    high_paths = {s.env_path for s in high_suggestions}
-    wasted = sum(
-        se.env.size_bytes
-        for se in scored_envs
-        if se.env.path in high_paths and se.env.size_bytes >= _IMPACTFUL_SIZE_BYTES
-    )
+    total_size, wasted, counts = _summarise(suggestions, scored_envs)
 
     console.print()
     console.rule("[bold cyan]Environment Health Report[/bold cyan]")
@@ -153,11 +155,6 @@ def _output_rich(
     )
 
     # Category summary
-    counts = {
-        "HIGH": sum(1 for s in suggestions if s.category == "HIGH"),
-        "MEDIUM": sum(1 for s in suggestions if s.category == "MEDIUM"),
-        "LOW": sum(1 for s in suggestions if s.category == "LOW"),
-    }
     console.print(
         f"  [bold red]HIGH[/bold red] (safe to delete): {counts['HIGH']}  "
         f"[bold yellow]MEDIUM[/bold yellow] (review): {counts['MEDIUM']}  "

{killpy-0.25.0 → killpy-0.25.1}/killpy/commands/list.py

@@ -11,6 +11,7 @@ from rich.table import Table
 
 from killpy.commands._utils import filter_envs
 from killpy.files import format_size
+from killpy.models import Environment
 from killpy.scanner import Scanner
 
 
@@ -38,7 +39,7 @@ def _run_json_stream(
 
 def _scan_with_progress(
     scanner: Scanner, path: Path, quiet: bool, stderr_console: Console
-):
+) -> list[Environment]:
     if quiet:
         return scanner.scan(path)
 

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/artifacts.py

@@ -7,17 +7,19 @@ import os
 from datetime import datetime, timezone
 from pathlib import Path
 
-from killpy.detectors.base import AbstractDetector
+from killpy.detectors.base import (
+    ENV_INTERNAL_DIRS,
+    VCS_PRUNE_DIRS,
+    AbstractDetector,
+)
 from killpy.files import get_total_size
 from killpy.models import Environment
 
 logger = logging.getLogger(__name__)
 
-_PRUNED: frozenset[str] = frozenset({".git", ".hg", ".svn", "node_modules"})
-# Environment internals are not build artifacts: every installed package has
-# a ``site-packages/*.dist-info`` directory whose deletion corrupts the env.
-# Environments are VenvDetector territory.
-_ENV_DIRS: frozenset[str] = frozenset({".venv", "site-packages"})
+# Environment internals (``ENV_INTERNAL_DIRS``) are not build artifacts: every
+# installed package has a ``site-packages/*.dist-info`` directory whose
+# deletion corrupts the env.  Environments are VenvDetector territory.
 _EXACT_NAMES: frozenset[str] = frozenset({"dist", "build"})
 _SUFFIXES: tuple[str, ...] = (".egg-info", ".dist-info")
 
@@ -39,9 +41,7 @@ class ArtifactsDetector(AbstractDetector):
     """
 
     name = "artifacts"
-
-    def can_handle(self) -> bool:
-        return True  # pure filesystem walk
+    always_available = True  # pure filesystem walk
 
     def detect(self, path: Path) -> list[Environment]:
         envs: list[Environment] = []
@@ -52,7 +52,7 @@ class ArtifactsDetector(AbstractDetector):
                 continue
             pruned = set()
             for d in directories:
-                if d in _PRUNED or d in _ENV_DIRS:
+                if d in VCS_PRUNE_DIRS or d in ENV_INTERNAL_DIRS:
                     pruned.add(d)
                     continue
                 if _is_artifact_dir(d):

killpy-0.25.1/killpy/detectors/base.py

@@ -0,0 +1,101 @@
+"""Abstract base class for all killpy detectors."""
+
+from __future__ import annotations
+
+import shutil
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import ClassVar
+
+from killpy.models import Environment
+
+# Directory names shared by the filesystem-walking detectors.  Defined once
+# here so the prune policy has a single source of truth (see
+# ``dev-docs/CODING_CONVENTIONS.md`` §1).
+
+# Version-control and JS dependency directories: never worth descending into
+# when looking for Python environments/artifacts.
+VCS_PRUNE_DIRS: frozenset[str] = frozenset({".git", ".hg", ".svn", "node_modules"})
+
+# An environment's own internals: a ``.venv`` / ``site-packages`` tree belongs
+# to the environment that owns it, so cache/artifact detectors must not descend
+# into it and double-count (or wrongly offer to delete) its contents.
+ENV_INTERNAL_DIRS: frozenset[str] = frozenset({".venv", "site-packages"})
+
+
+class AbstractDetector(ABC):
+    """Common interface every detector must implement.
+
+    Concrete detectors live in this package (``killpy/detectors/``).  The
+    :class:`~killpy.scanner.Scanner` instantiates them and calls
+    :meth:`can_handle` before :meth:`detect`, so detectors that rely on
+    optional tools (conda, pipx …) are silently skipped when those tools
+    are not present.
+
+    Class attributes
+    ----------------
+    name : str
+        Short identifier used for logging, filtering and the ``--type``
+        CLI option.  Must be unique across all detectors.
+
+    can_handle() contract
+    ---------------------
+    :meth:`can_handle` is *not* overridden by concrete detectors.  Instead each
+    declares its applicability contract as data, and the base computes the
+    result — so the declared contract and the runtime behaviour can never
+    diverge.  A detector must declare exactly one of:
+
+    * ``always_available = True`` — pure filesystem walk (venv, tox, cache, artifacts).
+    * ``required_tool = "<cli>"`` — needs a CLI on ``PATH`` (conda, pipx).
+    * override :meth:`_candidate_dirs` — needs a global directory (poetry, pyenv).
+    * both ``required_tool`` and :meth:`_candidate_dirs` — tool *or* directory
+      (pipenv, hatch, uv).
+
+    ``tests/unit/test_detectors.py`` asserts every detector declares one.  For a
+    check the three knobs can't express, overriding :meth:`can_handle` is an
+    allowed, documented exception — see ``dev-docs/ADDING_A_DETECTOR.md``.
+    """
+
+    name: str = "base"
+
+    #: CLI executable that, if present on ``PATH``, enables this detector.
+    required_tool: ClassVar[str | None] = None
+    #: ``True`` for detectors that always apply (pure filesystem walks).
+    always_available: ClassVar[bool] = False
+
+    @abstractmethod
+    def detect(self, path: Path) -> list[Environment]:
+        """Scan *path* and return every matching :class:`~killpy.models.Environment`.
+
+        Implementations **must not raise** – on error they should log and
+        return an empty list so that other detectors are unaffected.
+
+        Parameters
+        ----------
+        path:
+            Root directory to scan.  Global-cache detectors (poetry, pipx …)
+            may ignore this argument; local detectors (venv, tox …) should
+            use it as the walk root.
+        """
+
+    def _candidate_dirs(self) -> tuple[Path, ...]:
+        """Directories whose existence makes this detector applicable.
+
+        Empty by default; directory- and hybrid-contract detectors override it.
+        Resolved at call time (not class-definition time) so patched path
+        helpers are honoured.
+        """
+        return ()
+
+    def can_handle(self) -> bool:
+        """Return ``True`` when this detector can find anything on this system.
+
+        Computed from the declared contract (see the class docstring); a
+        pre-flight gate that never raises and does no I/O beyond ``which()`` /
+        ``exists()``.  Do not override — declare the contract instead.
+        """
+        if self.always_available:
+            return True
+        if self.required_tool is not None and shutil.which(self.required_tool):
+            return True
+        return any(d.exists() for d in self._candidate_dirs())

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/cache.py

@@ -17,7 +17,11 @@ import platform
 from datetime import datetime, timezone
 from pathlib import Path
 
-from killpy.detectors.base import AbstractDetector
+from killpy.detectors.base import (
+    ENV_INTERNAL_DIRS,
+    VCS_PRUNE_DIRS,
+    AbstractDetector,
+)
 from killpy.files import get_total_size
 from killpy.models import Environment
 
@@ -31,13 +35,9 @@ _LOCAL_CACHE_DIRS: tuple[str, ...] = (
     ".ruff_cache",
 )
 
-# Directories to prune from the walk so we don't descend into them.
-_PRUNED: frozenset[str] = frozenset({".git", ".hg", ".svn", "node_modules"})
-
-# Caches inside an environment belong to the environment: VenvDetector
-# already reports the whole tree, so listing them separately double-counts
-# their size in stats/list totals.
-_ENV_DIRS: frozenset[str] = frozenset({".venv", "site-packages"})
+# Caches inside an environment (``ENV_INTERNAL_DIRS``) belong to the
+# environment: VenvDetector already reports the whole tree, so listing them
+# separately would double-count their size in stats/list totals.
 
 
 def _pip_cache_dir() -> Path:
@@ -71,9 +71,7 @@ class CacheDetector(AbstractDetector):
     """Detects local and global Python cache directories."""
 
     name = "cache"
-
-    def can_handle(self) -> bool:
-        return True
+    always_available = True  # pure filesystem walk
 
     def detect(self, path: Path) -> list[Environment]:
         envs: list[Environment] = []
@@ -95,10 +93,10 @@ class CacheDetector(AbstractDetector):
                 # Inside a virtual environment (whatever its name) — skip it.
                 directories[:] = []
                 continue
-            prune = set()
+            pruned = set()
             for d in directories:
-                if d in _PRUNED or d in _ENV_DIRS:
-                    prune.add(d)
+                if d in VCS_PRUNE_DIRS or d in ENV_INTERNAL_DIRS:
+                    pruned.add(d)
                     continue
                 if d in _LOCAL_CACHE_DIRS:
                     cache_path = Path(current_root) / d
@@ -107,8 +105,8 @@ class CacheDetector(AbstractDetector):
                         results.append(env)
                     except (FileNotFoundError, OSError) as exc:
                         logger.debug("Skipping %s: %s", cache_path, exc)
-                    prune.add(d)  # don't recurse inside cache dirs
-            directories[:] = [d for d in directories if d not in prune]
+                    pruned.add(d)  # don't recurse inside cache dirs
+            directories[:] = [d for d in directories if d not in pruned]
         return results
 
     def _scan_global(self, root: Path) -> list[Environment]:
@@ -141,13 +139,13 @@ class CacheDetector(AbstractDetector):
         return results
 
 
-def _make_cache_env(p: Path, tag: str) -> Environment:
-    stat = p.stat()
-    size = get_total_size(p)
+def _make_cache_env(cache_path: Path, tag: str) -> Environment:
+    stat = cache_path.stat()
+    size = get_total_size(cache_path)
     mtime = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
     return Environment(
-        path=p,
-        name=str(p),
+        path=cache_path,
+        name=str(cache_path),
         type=tag,
         last_accessed=mtime,
         size_bytes=size,

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/conda.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import logging
-import shutil
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
@@ -53,9 +52,7 @@ class CondaDetector(AbstractDetector):
     """
 
     name = "conda"
-
-    def can_handle(self) -> bool:
-        return shutil.which("conda") is not None
+    required_tool = "conda"  # needs the conda CLI on PATH
 
     def detect(self, path: Path) -> list[Environment]:  # noqa: ARG002
         try:

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/hatch.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import logging
 import os
 import platform
-import shutil
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -42,9 +41,11 @@ class HatchDetector(AbstractDetector):
     """
 
     name = "hatch"
+    required_tool = "hatch"  # tool-or-directory contract
 
-    def can_handle(self) -> bool:
-        return shutil.which("hatch") is not None or _hatch_envs_root().exists()
+    def _candidate_dirs(self) -> tuple[Path, ...]:
+        # ...or its global environments directory exists.
+        return (_hatch_envs_root(),)
 
     def detect(self, path: Path) -> list[Environment]:  # noqa: ARG002
         envs_root = _hatch_envs_root()

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/pipenv.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import logging
 import os
 import platform
-import shutil
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -35,9 +34,11 @@ class PipenvDetector(AbstractDetector):
     """
 
     name = "pipenv"
+    required_tool = "pipenv"  # tool-or-directory contract
 
-    def can_handle(self) -> bool:
-        return shutil.which("pipenv") is not None or _pipenv_venvs_root().exists()
+    def _candidate_dirs(self) -> tuple[Path, ...]:
+        # ...or its global virtualenvs directory exists.
+        return (_pipenv_venvs_root(),)
 
     def detect(self, path: Path) -> list[Environment]:  # noqa: ARG002
         venvs_root = _pipenv_venvs_root()

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/pipx.py

@@ -6,7 +6,6 @@ import json
 import logging
 import os
 import platform
-import shutil
 import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
@@ -82,9 +81,7 @@ class PipxDetector(AbstractDetector):
     """
 
     name = "pipx"
-
-    def can_handle(self) -> bool:
-        return shutil.which("pipx") is not None
+    required_tool = "pipx"  # needs the pipx CLI on PATH
 
     def detect(self, path: Path) -> list[Environment]:  # noqa: ARG002
         try:

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/poetry.py

@@ -46,8 +46,9 @@ class PoetryDetector(AbstractDetector):
 
     name = "poetry"
 
-    def can_handle(self) -> bool:
-        return _poetry_venvs_dir().exists()
+    def _candidate_dirs(self) -> tuple[Path, ...]:
+        # Contract: directory — applies only if Poetry's virtualenvs cache exists.
+        return (_poetry_venvs_dir(),)
 
     def detect(self, path: Path) -> list[Environment]:  # noqa: ARG002
         venvs_dir = _poetry_venvs_dir()

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/pyenv.py

@@ -42,8 +42,9 @@ class PyenvDetector(AbstractDetector):
 
     name = "pyenv"
 
-    def can_handle(self) -> bool:
-        return _pyenv_versions_root().exists()
+    def _candidate_dirs(self) -> tuple[Path, ...]:
+        # Contract: directory — applies only if pyenv's versions directory exists.
+        return (_pyenv_versions_root(),)
 
     def detect(self, path: Path) -> list[Environment]:  # noqa: ARG002
         versions_root = _pyenv_versions_root()

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/tox.py

@@ -7,29 +7,25 @@ import os
 from datetime import datetime, timezone
 from pathlib import Path
 
-from killpy.detectors.base import AbstractDetector
+from killpy.detectors.base import VCS_PRUNE_DIRS, AbstractDetector
 from killpy.files import get_total_size
 from killpy.models import Environment
 
 logger = logging.getLogger(__name__)
 
-_PRUNED: frozenset[str] = frozenset({".git", ".hg", ".svn", "node_modules"})
-
 
 class ToxDetector(AbstractDetector):
     """Detects ``.tox`` directories created by tox test automation."""
 
     name = "tox"
-
-    def can_handle(self) -> bool:
-        return True  # pure filesystem walk
+    always_available = True  # pure filesystem walk
 
     def detect(self, path: Path) -> list[Environment]:
         envs: list[Environment] = []
         for current_root, directories, _ in os.walk(path, topdown=True):
             pruned = set()
             for d in directories:
-                if d in _PRUNED:
+                if d in VCS_PRUNE_DIRS:
                     pruned.add(d)
                     continue
                 if d == ".tox":

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/uv.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import logging
 import os
-import shutil
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -52,13 +51,11 @@ class UvDetector(AbstractDetector):
     """
 
     name = "uv"
+    required_tool = "uv"  # tool-or-directory contract
 
-    def can_handle(self) -> bool:
-        return (
-            shutil.which("uv") is not None
-            or _uv_tools_dir().exists()
-            or _uv_python_dir().exists()
-        )
+    def _candidate_dirs(self) -> tuple[Path, ...]:
+        # ...or one of its tool/python data directories exists.
+        return (_uv_tools_dir(), _uv_python_dir())
 
     def detect(self, path: Path) -> list[Environment]:  # noqa: ARG002
         envs: list[Environment] = []

{killpy-0.25.0 → killpy-0.25.1}/killpy/detectors/venv.py

@@ -7,19 +7,18 @@ import os
 from datetime import datetime, timezone
 from pathlib import Path
 
-from killpy.detectors.base import AbstractDetector
+from killpy.detectors.base import VCS_PRUNE_DIRS, AbstractDetector
 from killpy.files import get_total_size
 from killpy.models import Environment
 
 logger = logging.getLogger(__name__)
 
-# Directory names that should never be walked into when scanning.
-_EXCLUDED_DIRS: frozenset[str] = frozenset(
+# Directory names that should never be walked into when looking for venvs.
+# Wider than ``VCS_PRUNE_DIRS`` (it also skips tox/nox/cache/build trees) but,
+# unlike the cache/artifact detectors, it must NOT exclude ``.venv`` /
+# ``site-packages`` — those are exactly what this detector is looking for.
+_EXCLUDED_DIRS: frozenset[str] = VCS_PRUNE_DIRS | frozenset(
     {
-        ".git",
-        ".hg",
-        ".svn",
-        "node_modules",
         ".tox",
         ".nox",
         ".mypy_cache",
@@ -57,12 +56,13 @@ class VenvDetector(AbstractDetector):
     """
 
     name = "venv"
-
-    def can_handle(self) -> bool:
-        # Always applicable – pure filesystem scan.
-        return True
+    always_available = True  # pure filesystem walk
 
     def detect(self, path: Path) -> list[Environment]:
+        # Inner dedup: the ".venv" scan and the pyvenv.cfg scan below can both
+        # reach the same directory (a ".venv" that also contains pyvenv.cfg).
+        # This local `seen` set collapses those; the Scanner deduplicates again
+        # across detectors, so both layers are intentional (see ARCH P5).
         seen: set[Path] = set()
         envs: list[Environment] = []
 

{killpy-0.25.0 → killpy-0.25.1}/killpy/files/__init__.py

@@ -1,3 +1,7 @@
+"""File-size helpers: recursive byte totals and human-readable formatting."""
+
+from __future__ import annotations
+
 import os
 from pathlib import Path
 
@@ -19,12 +23,13 @@ def get_total_size(path: Path) -> int:
     return total_size
 
 
-def format_size(size_in_bytes: int):
-    if size_in_bytes >= 1 << 30:
-        return f"{size_in_bytes / (1 << 30):.2f} GB"
-    elif size_in_bytes >= 1 << 20:
-        return f"{size_in_bytes / (1 << 20):.2f} MB"
-    elif size_in_bytes >= 1 << 10:
-        return f"{size_in_bytes / (1 << 10):.2f} KB"
+def format_size(size_bytes: int) -> str:
+    """Return *size_bytes* as a human-readable string (GB / MB / KB / bytes)."""
+    if size_bytes >= 1 << 30:
+        return f"{size_bytes / (1 << 30):.2f} GB"
+    elif size_bytes >= 1 << 20:
+        return f"{size_bytes / (1 << 20):.2f} MB"
+    elif size_bytes >= 1 << 10:
+        return f"{size_bytes / (1 << 10):.2f} KB"
     else:
-        return f"{size_in_bytes} bytes"
+        return f"{size_bytes} bytes"

{killpy-0.25.0 → killpy-0.25.1}/killpy/intelligence/git_analyzer.py

@@ -76,16 +76,22 @@ class GitAnalyzer:
             logger.debug("Could not parse git timestamp %r: %s", raw, exc)
             return None
 
+    @staticmethod
+    def _is_recent(commit: datetime | None, threshold_days: int) -> bool:
+        """Return ``True`` when *commit* is within *threshold_days* of now."""
+        if commit is None:
+            return False
+        age_days = (datetime.now(tz=timezone.utc) - commit).days
+        return age_days < threshold_days
+
     @staticmethod
     def is_active_repo(
         repo_root: Path, threshold_days: int = _ACTIVE_THRESHOLD_DAYS
     ) -> bool:
         """Return ``True`` when the repo had a commit within *threshold_days*."""
-        last = GitAnalyzer.get_last_commit(repo_root)
-        if last is None:
-            return False
-        age_days = (datetime.now(tz=timezone.utc) - last).days
-        return age_days < threshold_days
+        return GitAnalyzer._is_recent(
+            GitAnalyzer.get_last_commit(repo_root), threshold_days
+        )
 
     # ------------------------------------------------------------------ #
     #  Public orchestrator                                                 #
@@ -106,10 +112,7 @@ class GitAnalyzer:
             return GitInfo(is_git_repo=False, is_active=False)
 
         last_commit = GitAnalyzer.get_last_commit(repo_root)
-        is_active = False
-        if last_commit is not None:
-            age_days = (datetime.now(tz=timezone.utc) - last_commit).days
-            is_active = age_days < _ACTIVE_THRESHOLD_DAYS
+        is_active = GitAnalyzer._is_recent(last_commit, _ACTIVE_THRESHOLD_DAYS)
 
         return GitInfo(
             is_git_repo=True,

{killpy-0.25.0 → killpy-0.25.1}/killpy/models.py

@@ -27,9 +27,11 @@ class Environment:
         environments (conda, pipx) this is the physical venv directory used
         for size calculation and display.
     name:
-        Human-readable name.  For filesystem envs this defaults to the last
-        two parts of *path*; for named envs (conda, pipx) it is the package /
-        environment name.
+        Human-readable name.  Filesystem-walk detectors (venv, cache, tox,
+        artifacts) store the full path string; global/tool detectors store a
+        short identifier: the directory basename (poetry, pyenv, pipenv, uv),
+        the managing tool's env/package name (conda, pipx), or
+        ``"<project>/<env>"`` (hatch).
     type:
         Short detector tag, e.g. ``"venv"``, ``"pyvenv.cfg"``, ``"poetry"``,
         ``"conda"``, ``"pipx"``, ``"cache"``, ``"uv"``, ``"artifacts"``…
@@ -131,6 +133,16 @@ class Suggestion:
     reasons: list[str]
     recommended_action: str
 
+    def to_dict(self) -> dict:
+        """Return a JSON-serialisable representation."""
+        return {
+            "env_path": str(self.env_path),
+            "score": self.score,
+            "category": self.category,
+            "reasons": self.reasons,
+            "recommended_action": self.recommended_action,
+        }
+
 
 @dataclass
 class ScanRecord:

{killpy-0.25.0 → killpy-0.25.1}/killpy.egg-info/PKG-INFO

@@ -1,17 +1,25 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.25.0
-Summary: List all .venv directories and Conda environments 🐍 on your system and check how much space they are using. You can then choose which ones to delete in order to free up space 🧹.
+Version: 0.25.1
+Summary: Find and delete unused Python environments (.venv, conda, poetry, pipenv, pipx, pyenv, uv) and caches to free disk space — from a fast terminal UI or a single CLI command.
 Project-URL: Homepage, https://github.com/Tlaloc-Es/killpy
 Project-URL: Documentation, https://tlaloc-es.github.io/killpy/
 Project-URL: Repository, https://github.com/Tlaloc-Es/killpy
 Project-URL: Bug Tracker, https://github.com/Tlaloc-Es/killpy/issues
+Keywords: venv,virtualenv,conda,poetry,pipenv,pipx,pyenv,uv,cleanup,disk-space,cache,cli,tui,textual,developer-tools
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.1.8
@@ -596,7 +604,7 @@ ______________________________________________________________________
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.24.1
+  rev: 0.25.1
   hooks:
     - id: killpy                  # remove __pycache__ on every commit
     - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
@@ -621,7 +629,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.25.0
+  rev: 0.25.1
   hooks:
     - id: killpy
 ```

{killpy-0.25.0 → killpy-0.25.1}/pyproject.toml

@@ -1,15 +1,39 @@
 [project]
 name = "killpy"
-version = "0.25.0"
-description = "List all .venv directories and Conda environments 🐍 on your system and check how much space they are using. You can then choose which ones to delete in order to free up space 🧹."
+version = "0.25.1"
+description = "Find and delete unused Python environments (.venv, conda, poetry, pipenv, pipx, pyenv, uv) and caches to free disk space — from a fast terminal UI or a single CLI command."
 readme = "README.md"
+keywords = [
+    "venv",
+    "virtualenv",
+    "conda",
+    "poetry",
+    "pipenv",
+    "pipx",
+    "pyenv",
+    "uv",
+    "cleanup",
+    "disk-space",
+    "cache",
+    "cli",
+    "tui",
+    "textual",
+    "developer-tools",
+]
 classifiers = [
+    "Development Status :: 4 - Beta",
     "Environment :: Console",
+    "Environment :: Console :: Curses",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
     "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities",
 ]
 dependencies = [
     "click>=8.1.8",

killpy-0.25.0/killpy/detectors/base.py

@@ -1,53 +0,0 @@
-"""Abstract base class for all killpy detectors."""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from pathlib import Path
-
-from killpy.models import Environment
-
-
-class AbstractDetector(ABC):
-    """Common interface every detector must implement.
-
-    Concrete detectors live in this package (``killpy/detectors/``).  The
-    :class:`~killpy.scanner.Scanner` instantiates them and calls
-    :meth:`can_handle` before :meth:`detect`, so detectors that rely on
-    optional tools (conda, pipx …) are silently skipped when those tools
-    are not present.
-
-    Class attributes
-    ----------------
-    name : str
-        Short identifier used for logging, filtering and the ``--type``
-        CLI option.  Must be unique across all detectors.
-    """
-
-    name: str = "base"
-
-    @abstractmethod
-    def detect(self, path: Path) -> list[Environment]:
-        """Scan *path* and return every matching :class:`~killpy.models.Environment`.
-
-        Implementations **must not raise** – on error they should log and
-        return an empty list so that other detectors are unaffected.
-
-        Parameters
-        ----------
-        path:
-            Root directory to scan.  Global-cache detectors (poetry, pipx …)
-            may ignore this argument; local detectors (venv, tox …) should
-            use it as the walk root.
-        """
-
-    @abstractmethod
-    def can_handle(self) -> bool:
-        """Return ``True`` when this detector is usable in the current environment.
-
-        Examples of conditions to check:
-
-        * Required CLI tool is on ``PATH`` (conda, pipx …).
-        * Required cache directory exists (poetry, pipenv …).
-        * Always ``True`` for pure filesystem detectors (venv, cache …).
-        """