killpy 0.19.2__tar.gz → 0.21.0__tar.gz

{killpy-0.19.2 → killpy-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.19.2
+Version: 0.21.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 🧹.
 Project-URL: Homepage, https://github.com/Tlaloc-Es/killpy
 Project-URL: Documentation, https://tlaloc-es.github.io/killpy/
@@ -224,6 +224,24 @@ killpy list --json                        # output as a JSON array
 killpy list --json-stream                 # stream as NDJSON — one line per env
 ```
 
+`--json` example output:
+
+```json
+[
+  {
+    "path": "projects/my-app/.venv",
+    "absolute_path": "/home/user/projects/my-app/.venv",
+    "name": "my-app/.venv",
+    "type": "venv",
+    "last_accessed": "2025-11-02T14:23:01+00:00",
+    "size_bytes": 54393984,
+    "size_human": "51.88 MB",
+    "managed_by": null,
+    "is_system_critical": false
+  }
+]
+```
+
 `--json-stream` is ideal for piping into `jq` or processing in scripts before the full scan completes:
 
 ```bash
@@ -252,6 +270,7 @@ ______________________________________________________________________
 killpy stats
 killpy stats --path ~/projects
 killpy stats --json
+killpy stats --history           # cumulative scan history
 ```
 
 Example output:
@@ -283,6 +302,98 @@ Removes `__pycache__` directories recursively under the target path.
 
 ______________________________________________________________________
 
+### `killpy doctor` — smart health report
+
+```
+Usage: killpy doctor [OPTIONS]
+
+Options:
+  --path DIRECTORY  Root directory to scan  [default: cwd]
+  --all             Show all environments grouped by category
+                    (HIGH / MEDIUM / LOW). Default shows only the top 5.
+  --json            Output as JSON.
+  --help            Show this message and exit.
+```
+
+`doctor` analyses every detected virtual environment in two phases:
+
+**Phase 1 — Scoring (for sorting only)**
+
+A numeric score between 0 and 1 is computed from four weighted signals:
+
+| Signal | Description |
+|--------|-------------|
+| **Size** | Larger environments score higher (sigmoid-normalised around 500 MB). |
+| **Age** | Days since last access, linear up to 365 days. |
+| **Orphan status** | No `pyproject.toml`, `requirements.txt`, or other project marker found nearby. |
+| **Git inactivity** | The associated git repository has no recent commits. |
+
+The score determines *ordering* within each category (highest score listed first). It does **not** determine the category itself.
+
+**Phase 2 — Rule-based classification**
+
+Category is assigned deterministically by applying the following rules in order:
+
+| Priority | Rule | Category |
+|----------|------|----------|
+| 1 | Orphan (`is_orphan=True`) **and** `age ≥ 180 days` | `HIGH` |
+| 2 | No project files **and** `age ≥ 365 days` | `HIGH` |
+| 3 | Active git repository **or** `age < 120 days` | `LOW` |
+| 4 | `age ≥ 120 days` | `MEDIUM` |
+| 5 | Fallback | `LOW` |
+
+Age and orphan status are the dominant signals. Size does not affect the category.
+
+| Category | Recommended action |
+|----------|--------------------|
+| `HIGH` | Delete — unused and orphaned |
+| `MEDIUM` | Review — possibly unused |
+| `LOW` | Keep — actively used / Keep |
+
+Examples:
+
+```bash
+killpy doctor                           # top 5 offenders in current directory
+killpy doctor --path ~                  # scan home folder
+killpy doctor --all                     # show all environments by category
+killpy doctor --json                    # machine-readable output
+killpy doctor --path ~/projects --all   # full report for a specific tree
+```
+
+Example output (default):
+
+```
+──────────── Environment Health Report ────────────
+Scanned: /home/user/projects
+Environments found: 18  |  Total size: 6.2 GB  |  Estimated wasted: 3.8 GB
+  HIGH (safe to delete): 5  MEDIUM (review): 7  LOW (keep): 6
+
+               Top 5 Offenders
+┌──────────────────────────┬────────┬───────────┬───────┬──────────┐
+│ Path                     │   Size │ Age (days)│ Score │ Category │
+├──────────────────────────┼────────┼───────────┼───────┼──────────┤
+│ ~/old-project/.venv      │ 850 MB │       312 │  0.94 │ HIGH     │
+│ ~/tutorial2023/.venv     │ 420 MB │       198 │  0.87 │ HIGH     │
+└──────────────────────────┴────────┴───────────┴───────┴──────────┘
+
+Recommendation: Run `killpy delete --older-than 180` to free up to 3.8 GB.
+(12 MEDIUM/LOW environment(s) hidden — run with --all to see them)
+```
+
+Use `--all` to see all three category tables at once:
+
+```bash
+killpy doctor --all
+```
+
+The JSON output is useful for scripting or auditing:
+
+```bash
+killpy doctor --json | jq '.suggestions[] | select(.category=="HIGH") | .env_path'
+```
+
+______________________________________________________________________
+
 ## killpy vs alternatives
 
 | Tool | venv | conda | poetry | pipx | pyenv | caches | artifacts | TUI | search | multi-select |
@@ -410,7 +521,7 @@ Keep your repo free of `__pycache__` on every commit:
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.16.0
+  rev: 0.21.0
   hooks:
     - id: killpy
       pass_filenames: false
@@ -437,6 +548,7 @@ ______________________________________________________________________
 - [ ] Windows support improvements (pyenv-win, conda on Windows PATH)
 - [ ] TUI: filter panel, live progress bar, confirmation dialog with total bytes before delete
 - [ ] Detect unused dependencies inside `pyproject.toml` / `requirements.txt`
+- [ ] Add environment reporting (Python version, installed packages, and versions) to better differentiate between virtual environments with different dependencies
 
 ______________________________________________________________________
 

{killpy-0.19.2 → killpy-0.21.0}/README.md

@@ -204,6 +204,24 @@ killpy list --json                        # output as a JSON array
 killpy list --json-stream                 # stream as NDJSON — one line per env
 ```
 
+`--json` example output:
+
+```json
+[
+  {
+    "path": "projects/my-app/.venv",
+    "absolute_path": "/home/user/projects/my-app/.venv",
+    "name": "my-app/.venv",
+    "type": "venv",
+    "last_accessed": "2025-11-02T14:23:01+00:00",
+    "size_bytes": 54393984,
+    "size_human": "51.88 MB",
+    "managed_by": null,
+    "is_system_critical": false
+  }
+]
+```
+
 `--json-stream` is ideal for piping into `jq` or processing in scripts before the full scan completes:
 
 ```bash
@@ -232,6 +250,7 @@ ______________________________________________________________________
 killpy stats
 killpy stats --path ~/projects
 killpy stats --json
+killpy stats --history           # cumulative scan history
 ```
 
 Example output:
@@ -263,6 +282,98 @@ Removes `__pycache__` directories recursively under the target path.
 
 ______________________________________________________________________
 
+### `killpy doctor` — smart health report
+
+```
+Usage: killpy doctor [OPTIONS]
+
+Options:
+  --path DIRECTORY  Root directory to scan  [default: cwd]
+  --all             Show all environments grouped by category
+                    (HIGH / MEDIUM / LOW). Default shows only the top 5.
+  --json            Output as JSON.
+  --help            Show this message and exit.
+```
+
+`doctor` analyses every detected virtual environment in two phases:
+
+**Phase 1 — Scoring (for sorting only)**
+
+A numeric score between 0 and 1 is computed from four weighted signals:
+
+| Signal | Description |
+|--------|-------------|
+| **Size** | Larger environments score higher (sigmoid-normalised around 500 MB). |
+| **Age** | Days since last access, linear up to 365 days. |
+| **Orphan status** | No `pyproject.toml`, `requirements.txt`, or other project marker found nearby. |
+| **Git inactivity** | The associated git repository has no recent commits. |
+
+The score determines *ordering* within each category (highest score listed first). It does **not** determine the category itself.
+
+**Phase 2 — Rule-based classification**
+
+Category is assigned deterministically by applying the following rules in order:
+
+| Priority | Rule | Category |
+|----------|------|----------|
+| 1 | Orphan (`is_orphan=True`) **and** `age ≥ 180 days` | `HIGH` |
+| 2 | No project files **and** `age ≥ 365 days` | `HIGH` |
+| 3 | Active git repository **or** `age < 120 days` | `LOW` |
+| 4 | `age ≥ 120 days` | `MEDIUM` |
+| 5 | Fallback | `LOW` |
+
+Age and orphan status are the dominant signals. Size does not affect the category.
+
+| Category | Recommended action |
+|----------|--------------------|
+| `HIGH` | Delete — unused and orphaned |
+| `MEDIUM` | Review — possibly unused |
+| `LOW` | Keep — actively used / Keep |
+
+Examples:
+
+```bash
+killpy doctor                           # top 5 offenders in current directory
+killpy doctor --path ~                  # scan home folder
+killpy doctor --all                     # show all environments by category
+killpy doctor --json                    # machine-readable output
+killpy doctor --path ~/projects --all   # full report for a specific tree
+```
+
+Example output (default):
+
+```
+──────────── Environment Health Report ────────────
+Scanned: /home/user/projects
+Environments found: 18  |  Total size: 6.2 GB  |  Estimated wasted: 3.8 GB
+  HIGH (safe to delete): 5  MEDIUM (review): 7  LOW (keep): 6
+
+               Top 5 Offenders
+┌──────────────────────────┬────────┬───────────┬───────┬──────────┐
+│ Path                     │   Size │ Age (days)│ Score │ Category │
+├──────────────────────────┼────────┼───────────┼───────┼──────────┤
+│ ~/old-project/.venv      │ 850 MB │       312 │  0.94 │ HIGH     │
+│ ~/tutorial2023/.venv     │ 420 MB │       198 │  0.87 │ HIGH     │
+└──────────────────────────┴────────┴───────────┴───────┴──────────┘
+
+Recommendation: Run `killpy delete --older-than 180` to free up to 3.8 GB.
+(12 MEDIUM/LOW environment(s) hidden — run with --all to see them)
+```
+
+Use `--all` to see all three category tables at once:
+
+```bash
+killpy doctor --all
+```
+
+The JSON output is useful for scripting or auditing:
+
+```bash
+killpy doctor --json | jq '.suggestions[] | select(.category=="HIGH") | .env_path'
+```
+
+______________________________________________________________________
+
 ## killpy vs alternatives
 
 | Tool | venv | conda | poetry | pipx | pyenv | caches | artifacts | TUI | search | multi-select |
@@ -390,7 +501,7 @@ Keep your repo free of `__pycache__` on every commit:
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.16.0
+  rev: 0.21.0
   hooks:
     - id: killpy
       pass_filenames: false
@@ -417,6 +528,7 @@ ______________________________________________________________________
 - [ ] Windows support improvements (pyenv-win, conda on Windows PATH)
 - [ ] TUI: filter panel, live progress bar, confirmation dialog with total bytes before delete
 - [ ] Detect unused dependencies inside `pyproject.toml` / `requirements.txt`
+- [ ] Add environment reporting (Python version, installed packages, and versions) to better differentiate between virtual environments with different dependencies
 
 ______________________________________________________________________
 

{killpy-0.19.2 → killpy-0.21.0}/killpy/__main__.py

@@ -9,9 +9,11 @@ from killpy.cleaner import Cleaner
 from killpy.cli import TableApp
 from killpy.commands.clean import clean
 from killpy.commands.delete import delete_cmd
+from killpy.commands.doctor import doctor_cmd
 from killpy.commands.list import list_cmd
 from killpy.commands.stats import stats_cmd
 from killpy.files import format_size
+from killpy.intelligence.tracker import UsageTracker
 from killpy.scanner import Scanner
 
 
@@ -63,6 +65,12 @@ def _run_delete_all(path: Path, excluded: set[str], yes: bool) -> None:
         f"freed [bold]{format_size(freed)}[/bold]."
     )
 
+    # Best-effort: record deletion in history.
+    try:
+        UsageTracker().record_deletion(freed)
+    except Exception:  # noqa: BLE001
+        pass
+
 
 @click.group(invoke_without_command=True)
 @click.option(
@@ -109,6 +117,7 @@ cli.add_command(clean)
 cli.add_command(list_cmd, name="list")
 cli.add_command(delete_cmd, name="delete")
 cli.add_command(stats_cmd, name="stats")
+cli.add_command(doctor_cmd, name="doctor")
 
 
 if __name__ == "__main__":

{killpy-0.19.2 → killpy-0.21.0}/killpy/cli.py

@@ -8,6 +8,7 @@ from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
 from typing import Any, TypedDict
 
+from rich.text import Text
 from textual.app import App, ComposeResult
 from textual.binding import Binding
 from textual.widgets import (
@@ -24,9 +25,23 @@ from textual.widgets import (
 from killpy.cleaner import Cleaner, CleanerError
 from killpy.cleaners import remove_pycache
 from killpy.files import format_size
+from killpy.intelligence import SuggestionEngine, score_all
 from killpy.models import Environment
 from killpy.scanner import Scanner
 
+_HEALTH_STYLES: dict[str, tuple[str, str]] = {
+    "HIGH": ("HIGH", "bold red"),
+    "MEDIUM": ("MED", "bold yellow"),
+    "LOW": ("LOW", "bold green"),
+}
+
+
+def _health_text(category: str) -> Text | str:
+    if category in _HEALTH_STYLES:
+        label, style = _HEALTH_STYLES[category]
+        return Text(label, style=style)
+    return ""
+
 
 def is_venv_tab(func):
     def wrapper(self, *args, **kwargs):
@@ -68,6 +83,7 @@ class VenvRow(TypedDict):
     last_modified: str
     size: int
     size_human: str
+    health: str
     status: str
     environment: Environment
 
@@ -87,6 +103,7 @@ class TableApp(App):
         "Last Modified",
         "Size",
         "Size (Human Readable)",
+        "Health",
         "Status",
     ]
     PIPX_HEADERS = ["Package", "Size", "Size (Human Readable)", "Status"]
@@ -95,7 +112,8 @@ class TableApp(App):
     VENV_COL_LAST_MODIFIED = 2
     VENV_COL_SIZE = 3
     VENV_COL_SIZE_HUMAN = 4
-    VENV_COL_STATUS = 5
+    VENV_COL_HEALTH = 5
+    VENV_COL_STATUS = 6
 
     PIPX_COL_PACKAGE = 0
     PIPX_COL_SIZE = 1
@@ -125,6 +143,7 @@ class TableApp(App):
         self._venv_display_indices: list[int] = []
         self._multi_select_mode: bool = False
         self._selected_venv_indices: set[int] = set()
+        self._health_by_path: dict[str, str] = {}
         self.cleaner = Cleaner()
         self.scanner = Scanner(
             types={
@@ -315,6 +334,7 @@ class TableApp(App):
                 "last_modified": environment.last_accessed_str,
                 "size": environment.size_bytes,
                 "size_human": environment.size_human,
+                "health": self._health_by_path.get(str(environment.path), ""),
                 "status": "",
                 "environment": environment,
             }
@@ -332,6 +352,7 @@ class TableApp(App):
             row["last_modified"],
             row["size"],
             row["size_human"],
+            _health_text(row["health"]),
             row["status"],
         )
 
@@ -373,6 +394,7 @@ class TableApp(App):
                 row["last_modified"],
                 row["size"],
                 row["size_human"],
+                _health_text(row["health"]),
                 self._compute_row_status(i, row),
             )
 
@@ -453,6 +475,11 @@ class TableApp(App):
             self.venv_rows.sort(
                 key=lambda row: row["size_human"].lower(), reverse=reverse
             )
+        elif column_index == self.VENV_COL_HEALTH:
+            _order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2, "": 3}
+            self.venv_rows.sort(
+                key=lambda row: _order.get(row["health"], 3), reverse=reverse
+            )
         elif column_index == self.VENV_COL_STATUS:
             self.venv_rows.sort(key=lambda row: row["status"].lower(), reverse=reverse)
         else:
@@ -545,6 +572,21 @@ class TableApp(App):
         status_label.update(
             f"Found {venv_count} virtual environments and {pipx_count} pipx packages"
         )
+        await self._compute_health_scores()
+
+    async def _compute_health_scores(self) -> None:
+        """Score venv environments and populate the Health column."""
+        if not self.venv_rows:
+            return
+        envs = [row["environment"] for row in self.venv_rows]
+        scored = await asyncio.to_thread(lambda: score_all(envs, run_git=False))
+        engine = SuggestionEngine()
+        suggestions = engine.classify_all(scored)
+        for suggestion in suggestions:
+            self._health_by_path[str(suggestion.env_path)] = suggestion.category
+        for row in self.venv_rows:
+            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)
@@ -612,11 +654,12 @@ class TableApp(App):
                 return
             elif current_status == EnvStatus.MARKED_TO_DELETE.value:
                 row["status"] = ""
-                table.update_cell_at((cursor_cell.row, 5), "")
+                table.update_cell_at((cursor_cell.row, self.VENV_COL_STATUS), "")
             else:
                 row["status"] = EnvStatus.MARKED_TO_DELETE.value
                 table.update_cell_at(
-                    (cursor_cell.row, 5), EnvStatus.MARKED_TO_DELETE.value
+                    (cursor_cell.row, self.VENV_COL_STATUS),
+                    EnvStatus.MARKED_TO_DELETE.value,
                 )
 
     @is_venv_tab
@@ -633,7 +676,10 @@ class TableApp(App):
             if self.delete_environment(row["environment"]):
                 self.bytes_release += int(row["size"])
                 row["status"] = EnvStatus.DELETED.value
-                table.update_cell_at((cursor_cell.row, 5), EnvStatus.DELETED.value)
+                table.update_cell_at(
+                    (cursor_cell.row, self.VENV_COL_STATUS),
+                    EnvStatus.DELETED.value,
+                )
                 self.query_one("#status-label", Label).update(
                     f"{format_size(self.bytes_release)} deleted"
                 )
@@ -773,7 +819,8 @@ class TableApp(App):
             self._selected_venv_indices.add(data_index)
         self._update_multi_select_label()
         table.update_cell_at(
-            (cursor_cell.row, 5), self._compute_row_status(data_index, row)
+            (cursor_cell.row, self.VENV_COL_STATUS),
+            self._compute_row_status(data_index, row),
         )
 
     @is_venv_tab

{killpy-0.19.2 → killpy-0.21.0}/killpy/commands/delete.py

@@ -11,6 +11,7 @@ from rich.console import Console
 
 from killpy.cleaner import Cleaner, CleanerError
 from killpy.files import format_size
+from killpy.intelligence.tracker import UsageTracker
 from killpy.models import Environment
 from killpy.scanner import Scanner
 
@@ -29,9 +30,7 @@ def _filter_envs(
 
     if older_than is not None:
         cutoff = now - timedelta(days=older_than)
-        result = [
-            e for e in result if e.last_accessed < cutoff
-        ]
+        result = [e for e in result if e.last_accessed < cutoff]
 
     return result
 
@@ -135,5 +134,11 @@ def delete_cmd(
         + (f" — [red]{errors} error(s)[/red]" if errors else "")
     )
 
+    # Best-effort: record deletion in history.
+    try:
+        UsageTracker().record_deletion(freed)
+    except Exception:  # noqa: BLE001
+        pass
+
     if errors:
         sys.exit(1)