killpy 0.23.0__tar.gz → 0.24.1__tar.gz

{killpy-0.23.0 → killpy-0.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.23.0
+Version: 0.24.1
 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/
@@ -31,6 +31,8 @@ Find and delete old `.venv`, conda, poetry, pipenv, uv and more — safely, in s
 uvx killpy --path ~
 ```
 
+> ⭐ Featured in [awesome-python](https://github.com/vinta/awesome-python) — a curated list of the best Python tools
+
 [Documentation](https://tlaloc-es.github.io/killpy/)
 
 [![PyPI](https://img.shields.io/pypi/v/killpy.svg)](https://pypi.org/project/killpy/)
@@ -40,6 +42,7 @@ uvx killpy --path ~
 [![Coverage](https://codecov.io/gh/Tlaloc-Es/killpy/branch/master/graph/badge.svg)](https://codecov.io/gh/Tlaloc-Es/killpy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](<https://twitter.com/intent/tweet?text=%F0%9F%90%8D%20KillPy%20helps%20you%20reclaim%20disk%20space%20by%20detecting%20unused%20Python%20environments%20(.venv,%20poetry%20env,%20conda%20env)%20and%20pipx%20packages.%20Clean,%20organize%20and%20free%20up%20space%20effortlessly!%20%F0%9F%9A%80&url=https://github.com/Tlaloc-Es/KillPy>)
+[![Awesome Python](https://awesome.re/badge.svg)](https://github.com/vinta/awesome-python)
 
 ![killpy in action](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/show.gif)
 
@@ -47,6 +50,31 @@ uvx killpy --path ~
 
 ______________________________________________________________________
 
+## Table of Contents
+
+- [The Problem](#the-problem)
+  - [What killpy detects](#what-killpy-detects)
+- [Quickstart](#quickstart)
+- [Interactive TUI](#interactive-tui)
+  - [Keyboard shortcuts](#keyboard-shortcuts)
+  - [Search / filter](#search--filter)
+  - [Multi-select mode](#multi-select-mode)
+- [CLI reference](#cli-reference)
+  - [`killpy` — launch TUI or headless delete](#killpy--launch-tui-or-headless-delete)
+  - [`killpy list` — inspect environments](#killpy-list--inspect-environments)
+  - [`killpy delete` — remove environments](#killpy-delete--remove-environments)
+  - [`killpy stats` — disk usage summary](#killpy-stats--disk-usage-summary)
+  - [`killpy clean` — remove cache directories](#killpy-clean--remove-cache-directories)
+  - [`killpy doctor` — smart health report](#killpy-doctor--smart-health-report)
+- [killpy vs alternatives](#killpy-vs-alternatives)
+- [FAQ](#faq)
+- [Pre-commit hooks](#pre-commit-hooks)
+- [Safety](#safety)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+
+______________________________________________________________________
+
 ## The Problem
 
 If you have been writing Python for more than a year, your disk is probably full of environments you forgot about.
@@ -227,8 +255,11 @@ killpy list --type venv --type conda      # filter by type (repeatable)
 killpy list --older-than 90               # not accessed in the last 90 days
 killpy list --json                        # output as a JSON array
 killpy list --json-stream                 # stream as NDJSON — one line per env
+killpy list --quiet                       # suppress progress output (scripts/CI)
 ```
 
+While scanning, `killpy list` shows a live progress indicator on **stderr** so you can see which detector is running. Stdout receives only the final output (table, JSON, or NDJSON), so pipes and redirections are never polluted. Use `--quiet` / `-q` to silence the progress indicator entirely.
+
 `--json` example output:
 
 ```json
@@ -430,9 +461,12 @@ Deletes every `.venv` / `pyvenv.cfg` env not accessed in the last 90 days, witho
 **How do I use killpy in a CI pipeline or script?**
 
 ```bash
-# List as machine-readable JSON
+# List as machine-readable JSON (progress goes to stderr, JSON to stdout)
 killpy list --json
 
+# Suppress progress output entirely with --quiet / -q
+killpy list --json --quiet | jq '.[] | .size_human'
+
 # Stream results as NDJSON in real time
 killpy list --json-stream | jq '.size_bytes'
 
@@ -440,6 +474,8 @@ killpy list --json-stream | jq '.size_bytes'
 killpy --path ./build_artifacts --delete-all --yes
 ```
 
+Progress messages always go to **stderr**, so stdout is clean for piping even without `--quiet`. Use `-q` when you want no output at all on stderr.
+
 **How do I skip certain directories?**
 
 ```bash
@@ -551,7 +587,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.23.0
+  rev: 0.24.1
   hooks:
     - id: killpy
 ```

{killpy-0.23.0 → killpy-0.24.1}/README.md

@@ -10,6 +10,8 @@ Find and delete old `.venv`, conda, poetry, pipenv, uv and more — safely, in s
 uvx killpy --path ~
 ```
 
+> ⭐ Featured in [awesome-python](https://github.com/vinta/awesome-python) — a curated list of the best Python tools
+
 [Documentation](https://tlaloc-es.github.io/killpy/)
 
 [![PyPI](https://img.shields.io/pypi/v/killpy.svg)](https://pypi.org/project/killpy/)
@@ -19,6 +21,7 @@ uvx killpy --path ~
 [![Coverage](https://codecov.io/gh/Tlaloc-Es/killpy/branch/master/graph/badge.svg)](https://codecov.io/gh/Tlaloc-Es/killpy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](<https://twitter.com/intent/tweet?text=%F0%9F%90%8D%20KillPy%20helps%20you%20reclaim%20disk%20space%20by%20detecting%20unused%20Python%20environments%20(.venv,%20poetry%20env,%20conda%20env)%20and%20pipx%20packages.%20Clean,%20organize%20and%20free%20up%20space%20effortlessly!%20%F0%9F%9A%80&url=https://github.com/Tlaloc-Es/KillPy>)
+[![Awesome Python](https://awesome.re/badge.svg)](https://github.com/vinta/awesome-python)
 
 ![killpy in action](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/show.gif)
 
@@ -26,6 +29,31 @@ uvx killpy --path ~
 
 ______________________________________________________________________
 
+## Table of Contents
+
+- [The Problem](#the-problem)
+  - [What killpy detects](#what-killpy-detects)
+- [Quickstart](#quickstart)
+- [Interactive TUI](#interactive-tui)
+  - [Keyboard shortcuts](#keyboard-shortcuts)
+  - [Search / filter](#search--filter)
+  - [Multi-select mode](#multi-select-mode)
+- [CLI reference](#cli-reference)
+  - [`killpy` — launch TUI or headless delete](#killpy--launch-tui-or-headless-delete)
+  - [`killpy list` — inspect environments](#killpy-list--inspect-environments)
+  - [`killpy delete` — remove environments](#killpy-delete--remove-environments)
+  - [`killpy stats` — disk usage summary](#killpy-stats--disk-usage-summary)
+  - [`killpy clean` — remove cache directories](#killpy-clean--remove-cache-directories)
+  - [`killpy doctor` — smart health report](#killpy-doctor--smart-health-report)
+- [killpy vs alternatives](#killpy-vs-alternatives)
+- [FAQ](#faq)
+- [Pre-commit hooks](#pre-commit-hooks)
+- [Safety](#safety)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+
+______________________________________________________________________
+
 ## The Problem
 
 If you have been writing Python for more than a year, your disk is probably full of environments you forgot about.
@@ -206,8 +234,11 @@ killpy list --type venv --type conda      # filter by type (repeatable)
 killpy list --older-than 90               # not accessed in the last 90 days
 killpy list --json                        # output as a JSON array
 killpy list --json-stream                 # stream as NDJSON — one line per env
+killpy list --quiet                       # suppress progress output (scripts/CI)
 ```
 
+While scanning, `killpy list` shows a live progress indicator on **stderr** so you can see which detector is running. Stdout receives only the final output (table, JSON, or NDJSON), so pipes and redirections are never polluted. Use `--quiet` / `-q` to silence the progress indicator entirely.
+
 `--json` example output:
 
 ```json
@@ -409,9 +440,12 @@ Deletes every `.venv` / `pyvenv.cfg` env not accessed in the last 90 days, witho
 **How do I use killpy in a CI pipeline or script?**
 
 ```bash
-# List as machine-readable JSON
+# List as machine-readable JSON (progress goes to stderr, JSON to stdout)
 killpy list --json
 
+# Suppress progress output entirely with --quiet / -q
+killpy list --json --quiet | jq '.[] | .size_human'
+
 # Stream results as NDJSON in real time
 killpy list --json-stream | jq '.size_bytes'
 
@@ -419,6 +453,8 @@ killpy list --json-stream | jq '.size_bytes'
 killpy --path ./build_artifacts --delete-all --yes
 ```
 
+Progress messages always go to **stderr**, so stdout is clean for piping even without `--quiet`. Use `-q` when you want no output at all on stderr.
+
 **How do I skip certain directories?**
 
 ```bash
@@ -530,7 +566,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.23.0
+  rev: 0.24.1
   hooks:
     - id: killpy
 ```

{killpy-0.23.0 → killpy-0.24.1}/killpy/__main__.py

@@ -52,6 +52,14 @@ def _run_delete_all(path: Path, excluded: set[str], yes: bool) -> None:
             console.print("Aborted.")
             return
 
+    # Record this cleanup session up-front so `killpy stats --history` reflects
+    # it; record_deletion() below updates the same record with the freed bytes.
+    tracker = UsageTracker()
+    try:
+        tracker.record_scan_result(envs, path)
+    except Exception:  # noqa: BLE001
+        pass
+
     deleted = 0
     freed = 0
     for env in envs:
@@ -67,9 +75,9 @@ 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.
+    # Best-effort: update the history record created above with freed bytes.
     try:
-        UsageTracker().record_deletion(freed)
+        tracker.record_deletion(freed)
     except Exception:  # noqa: BLE001
         pass
 

{killpy-0.23.0 → killpy-0.24.1}/killpy/cli.py

@@ -11,6 +11,7 @@ from typing import Any, TypedDict
 from rich.text import Text
 from textual.app import App, ComposeResult
 from textual.binding import Binding
+from textual.coordinate import Coordinate
 from textual.widgets import (
     DataTable,
     Footer,
@@ -25,7 +26,7 @@ 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.intelligence import SuggestionEngine, UsageTracker, score_all
 from killpy.models import Environment
 from killpy.scanner import Scanner
 
@@ -142,9 +143,10 @@ class TableApp(App):
         self._filter_query: str = ""
         self._venv_display_indices: list[int] = []
         self._multi_select_mode: bool = False
-        self._selected_venv_indices: set[int] = set()
+        self._selected_venv_paths: set[str] = set()
         self._health_by_path: dict[str, str] = {}
         self.cleaner = Cleaner()
+        self.tracker = UsageTracker()
         self.scanner = Scanner(
             types={
                 "venv",
@@ -395,7 +397,7 @@ class TableApp(App):
                 row["size"],
                 row["size_human"],
                 _health_text(row["health"]),
-                self._compute_row_status(i, row),
+                self._compute_row_status(row),
             )
 
     def render_pipx_table(self) -> None:
@@ -416,18 +418,18 @@ class TableApp(App):
             return data_index, self.venv_rows[data_index]
         return None
 
-    def _compute_row_status(self, data_index: int, row: VenvRow) -> str:
+    def _compute_row_status(self, row: VenvRow) -> str:
         """Return the status string to display, taking multi-select into account."""
         if row["status"] == EnvStatus.DELETED.value:
             return EnvStatus.DELETED.value
-        if self._multi_select_mode and data_index in self._selected_venv_indices:
+        if self._multi_select_mode and row["path"] in self._selected_venv_paths:
             return "\u25cf SELECTED"
         return row["status"]
 
     def _update_multi_select_label(self) -> None:
         label = self.query_one("#multi-select-label", Label)
         if self._multi_select_mode:
-            n = len(self._selected_venv_indices)
+            n = len(self._selected_venv_paths)
             label.add_class("visible")
             label.update(
                 f"[bold yellow]Multi-select[/bold yellow] — "
@@ -572,8 +574,27 @@ class TableApp(App):
         status_label.update(
             f"Found {venv_count} virtual environments and {pipx_count} pipx packages"
         )
+        self._record_scan()
         await self._compute_health_scores()
 
+    def _record_scan(self) -> None:
+        """Persist this scan session so ``killpy stats --history`` reflects it."""
+        try:
+            envs = [row["environment"] for row in self.venv_rows]
+            envs += [row["environment"] for row in self.pipx_rows]
+            self.tracker.record_scan_result(envs, self.root_dir)
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _record_deletion(self, freed: int) -> None:
+        """Best-effort: add *freed* bytes to the current history record."""
+        if freed <= 0:
+            return
+        try:
+            self.tracker.record_deletion(freed)
+        except Exception:  # noqa: BLE001
+            pass
+
     async def _compute_health_scores(self) -> None:
         """Score venv environments and populate the Health column."""
         if not self.venv_rows:
@@ -614,25 +635,32 @@ class TableApp(App):
 
     @is_venv_tab
     def action_confirm_delete(self):
-        if self._multi_select_mode and self._selected_venv_indices:
-            # Multi-select mode: delete all selected rows
-            for data_index in list(self._selected_venv_indices):
-                row = self.venv_rows[data_index]
+        freed_now = 0
+        if self._multi_select_mode and self._selected_venv_paths:
+            # Multi-select mode: delete all selected rows.  Selection is
+            # tracked by path (not by list position) so it stays valid even
+            # after the rows have been re-sorted.
+            for row in self.venv_rows:
+                if row["path"] not in self._selected_venv_paths:
+                    continue
                 if row["status"] == EnvStatus.DELETED.value:
                     continue
                 if self.delete_environment(row["environment"]):
+                    freed_now += int(row["size"])
                     self.bytes_release += int(row["size"])
                     row["status"] = EnvStatus.DELETED.value
-            self._selected_venv_indices.clear()
+            self._selected_venv_paths.clear()
         else:
             # Normal mode: delete all rows marked for deletion
             for row in self.venv_rows:
                 if row["status"] != EnvStatus.MARKED_TO_DELETE.value:
                     continue
                 if self.delete_environment(row["environment"]):
+                    freed_now += int(row["size"])
                     self.bytes_release += int(row["size"])
                     row["status"] = EnvStatus.DELETED.value
 
+        self._record_deletion(freed_now)
         self.render_venv_table()
         self.query_one("#status-label", Label).update(
             f"{format_size(self.bytes_release)} deleted"
@@ -675,6 +703,7 @@ class TableApp(App):
                 return
             if self.delete_environment(row["environment"]):
                 self.bytes_release += int(row["size"])
+                self._record_deletion(int(row["size"]))
                 row["status"] = EnvStatus.DELETED.value
                 table.update_cell_at(
                     (cursor_cell.row, self.VENV_COL_STATUS),
@@ -706,6 +735,7 @@ class TableApp(App):
                 row["status"] = EnvStatus.DELETED.value
                 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"
                 )
@@ -794,7 +824,7 @@ class TableApp(App):
         """Toggle multi-select mode on/off (T key)."""
         self._multi_select_mode = not self._multi_select_mode
         if not self._multi_select_mode:
-            self._selected_venv_indices.clear()
+            self._selected_venv_paths.clear()
         self._update_multi_select_label()
         self.render_venv_table()
 
@@ -810,17 +840,17 @@ class TableApp(App):
         resolved = self._resolve_venv_row(cursor_cell.row)
         if not resolved:
             return
-        data_index, row = resolved
+        _, row = resolved
         if row["status"] == EnvStatus.DELETED.value:
             return
-        if data_index in self._selected_venv_indices:
-            self._selected_venv_indices.discard(data_index)
+        if row["path"] in self._selected_venv_paths:
+            self._selected_venv_paths.discard(row["path"])
         else:
-            self._selected_venv_indices.add(data_index)
+            self._selected_venv_paths.add(row["path"])
         self._update_multi_select_label()
         table.update_cell_at(
-            (cursor_cell.row, self.VENV_COL_STATUS),
-            self._compute_row_status(data_index, row),
+            Coordinate(cursor_cell.row, self.VENV_COL_STATUS),
+            self._compute_row_status(row),
         )
 
     @is_venv_tab
@@ -829,13 +859,13 @@ class TableApp(App):
         if not self._multi_select_mode:
             return
         non_deleted = {
-            i
+            self.venv_rows[i]["path"]
             for i in self._venv_display_indices
             if self.venv_rows[i]["status"] != EnvStatus.DELETED.value
         }
-        if non_deleted == self._selected_venv_indices:
-            self._selected_venv_indices.clear()
+        if non_deleted == self._selected_venv_paths:
+            self._selected_venv_paths.clear()
         else:
-            self._selected_venv_indices = non_deleted
+            self._selected_venv_paths = non_deleted
         self._update_multi_select_label()
         self.render_venv_table()

{killpy-0.23.0 → killpy-0.24.1}/killpy/commands/delete.py

@@ -96,6 +96,14 @@ def delete_cmd(
             abort=True,
         )
 
+    # Record this cleanup session up-front so `killpy stats --history` reflects
+    # it; record_deletion() below updates the same record with the freed bytes.
+    tracker = UsageTracker()
+    try:
+        tracker.record_scan_result(envs, path)
+    except Exception:  # noqa: BLE001
+        pass
+
     cleaner = Cleaner(dry_run=False)
     freed = 0
     errors = 0
@@ -114,9 +122,9 @@ def delete_cmd(
         + (f" — [red]{errors} error(s)[/red]" if errors else "")
     )
 
-    # Best-effort: record deletion in history.
+    # Best-effort: update the history record created above with freed bytes.
     try:
-        UsageTracker().record_deletion(freed)
+        tracker.record_deletion(freed)
     except Exception:  # noqa: BLE001
         pass
 

{killpy-0.23.0 → killpy-0.24.1}/killpy/commands/list.py

@@ -14,6 +14,70 @@ from killpy.files import format_size
 from killpy.scanner import Scanner
 
 
+def _run_json_stream(
+    scanner: Scanner,
+    path: Path,
+    types: tuple[str, ...],
+    older_than: int | None,
+    quiet: bool,
+    stderr_console: Console,
+) -> None:
+    if not quiet:
+        stderr_console.print("[dim]Scanning…[/dim]")
+
+    def _progress(detector, envs):
+        if not quiet:
+            stderr_console.print(
+                f"[dim]  {detector.name}[/dim] — [dim]{len(envs)} found[/dim]",
+            )
+        for env in filter_envs(envs, types or None, older_than):
+            click.echo(json.dumps(env.to_dict()))
+
+    scanner.scan(path, on_progress=_progress)
+
+
+def _scan_with_progress(
+    scanner: Scanner, path: Path, quiet: bool, stderr_console: Console
+):
+    if quiet:
+        return scanner.scan(path)
+
+    status = stderr_console.status("Scanning…", spinner="dots")
+    status.start()
+
+    def _progress(detector, _envs):
+        status.update(f"Scanning… [dim]{detector.name}[/dim]")
+
+    envs = scanner.scan(path, on_progress=_progress)
+    status.stop()
+    return envs
+
+
+def _print_table(envs: list, console: Console) -> None:
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Type", style="dim", min_width=10)
+    table.add_column("Name", min_width=20)
+    table.add_column("Last accessed", min_width=12)
+    table.add_column("Size", justify="right", min_width=9)
+    table.add_column("Path")
+
+    for env in envs:
+        table.add_row(
+            env.type,
+            env.name,
+            env.last_accessed_str,
+            env.size_human,
+            str(env.path),
+        )
+
+    console.print(table)
+    total = sum(e.size_bytes for e in envs)
+    console.print(
+        f"\n[bold]{len(envs)}[/bold] environment(s) — "
+        f"[bold]{format_size(total)}[/bold] total"
+    )
+
+
 @click.command("list")
 @click.option(
     "--path",
@@ -52,26 +116,30 @@ from killpy.scanner import Scanner
     default=False,
     help="Output as JSON array.",
 )
+@click.option(
+    "--quiet",
+    "-q",
+    is_flag=True,
+    default=False,
+    help="Suppress progress messages (useful in scripts/pipelines).",
+)
 def list_cmd(
     path: Path,
     types: tuple[str, ...],
     older_than: int | None,
     as_json: bool,
     as_json_stream: bool,
+    quiet: bool,
 ) -> None:
     """List all detected Python environments under PATH."""
     scanner = Scanner(types=set(types) if types else None)
+    stderr_console = Console(stderr=True)
 
     if as_json_stream:
-
-        def _stream_progress(_detector, envs):
-            for env in filter_envs(envs, types or None, older_than):
-                click.echo(json.dumps(env.to_dict()))
-
-        scanner.scan(path, on_progress=_stream_progress)
+        _run_json_stream(scanner, path, types, older_than, quiet, stderr_console)
         return
 
-    envs = scanner.scan(path)
+    envs = _scan_with_progress(scanner, path, quiet, stderr_console)
     envs = filter_envs(envs, types or None, older_than)
 
     if as_json:
@@ -82,26 +150,4 @@ def list_cmd(
         click.echo("No environments found.")
         return
 
-    console = Console()
-    table = Table(show_header=True, header_style="bold cyan")
-    table.add_column("Type", style="dim", min_width=10)
-    table.add_column("Name", min_width=20)
-    table.add_column("Last accessed", min_width=12)
-    table.add_column("Size", justify="right", min_width=9)
-    table.add_column("Path")
-
-    for env in envs:
-        table.add_row(
-            env.type,
-            env.name,
-            env.last_accessed_str,
-            env.size_human,
-            str(env.path),
-        )
-
-    console.print(table)
-    total = sum(e.size_bytes for e in envs)
-    console.print(
-        f"\n[bold]{len(envs)}[/bold] environment(s) — "
-        f"[bold]{format_size(total)}[/bold] total"
-    )
+    _print_table(envs, Console())

{killpy-0.23.0 → killpy-0.24.1}/killpy/intelligence/tracker.py

@@ -6,9 +6,11 @@ import json
 import logging
 import os
 import tempfile
+from collections.abc import Iterable
+from datetime import datetime, timezone
 from pathlib import Path
 
-from killpy.models import ScanRecord, ScoredEnvironment
+from killpy.models import Environment, ScanRecord, ScoredEnvironment
 
 logger = logging.getLogger(__name__)
 
@@ -35,6 +37,32 @@ class UsageTracker:
         history.append(record.to_dict())
         self._save(history)
 
+    def record_scan_result(
+        self,
+        environments: Iterable[Environment],
+        scan_path: Path | str,
+        *,
+        deleted_bytes: int = 0,
+    ) -> None:
+        """Persist a :class:`~killpy.models.ScanRecord` built from a scan result.
+
+        Convenience wrapper around :meth:`record_scan` so callers don't have to
+        assemble a :class:`ScanRecord` by hand.  Records the number of
+        environments found and their total size; ``deleted_bytes`` can be set
+        when the freed amount is already known, otherwise use
+        :meth:`record_deletion` afterwards to update the same record.
+        """
+        envs = list(environments)
+        self.record_scan(
+            ScanRecord(
+                timestamp=datetime.now(tz=timezone.utc),
+                total_space_found=sum(e.size_bytes for e in envs),
+                total_space_deleted=deleted_bytes,
+                environments_count=len(envs),
+                scan_path=str(scan_path),
+            )
+        )
+
     def record_deletion(self, size_bytes: int) -> None:
         """Increment the ``total_space_deleted`` counter of the last scan record."""
         history = self._load()

{killpy-0.23.0 → killpy-0.24.1}/killpy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.23.0
+Version: 0.24.1
 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/
@@ -31,6 +31,8 @@ Find and delete old `.venv`, conda, poetry, pipenv, uv and more — safely, in s
 uvx killpy --path ~
 ```
 
+> ⭐ Featured in [awesome-python](https://github.com/vinta/awesome-python) — a curated list of the best Python tools
+
 [Documentation](https://tlaloc-es.github.io/killpy/)
 
 [![PyPI](https://img.shields.io/pypi/v/killpy.svg)](https://pypi.org/project/killpy/)
@@ -40,6 +42,7 @@ uvx killpy --path ~
 [![Coverage](https://codecov.io/gh/Tlaloc-Es/killpy/branch/master/graph/badge.svg)](https://codecov.io/gh/Tlaloc-Es/killpy)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Tweet](https://img.shields.io/twitter/url/http/shields.io.svg?style=social)](<https://twitter.com/intent/tweet?text=%F0%9F%90%8D%20KillPy%20helps%20you%20reclaim%20disk%20space%20by%20detecting%20unused%20Python%20environments%20(.venv,%20poetry%20env,%20conda%20env)%20and%20pipx%20packages.%20Clean,%20organize%20and%20free%20up%20space%20effortlessly!%20%F0%9F%9A%80&url=https://github.com/Tlaloc-Es/KillPy>)
+[![Awesome Python](https://awesome.re/badge.svg)](https://github.com/vinta/awesome-python)
 
 ![killpy in action](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/show.gif)
 
@@ -47,6 +50,31 @@ uvx killpy --path ~
 
 ______________________________________________________________________
 
+## Table of Contents
+
+- [The Problem](#the-problem)
+  - [What killpy detects](#what-killpy-detects)
+- [Quickstart](#quickstart)
+- [Interactive TUI](#interactive-tui)
+  - [Keyboard shortcuts](#keyboard-shortcuts)
+  - [Search / filter](#search--filter)
+  - [Multi-select mode](#multi-select-mode)
+- [CLI reference](#cli-reference)
+  - [`killpy` — launch TUI or headless delete](#killpy--launch-tui-or-headless-delete)
+  - [`killpy list` — inspect environments](#killpy-list--inspect-environments)
+  - [`killpy delete` — remove environments](#killpy-delete--remove-environments)
+  - [`killpy stats` — disk usage summary](#killpy-stats--disk-usage-summary)
+  - [`killpy clean` — remove cache directories](#killpy-clean--remove-cache-directories)
+  - [`killpy doctor` — smart health report](#killpy-doctor--smart-health-report)
+- [killpy vs alternatives](#killpy-vs-alternatives)
+- [FAQ](#faq)
+- [Pre-commit hooks](#pre-commit-hooks)
+- [Safety](#safety)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+
+______________________________________________________________________
+
 ## The Problem
 
 If you have been writing Python for more than a year, your disk is probably full of environments you forgot about.
@@ -227,8 +255,11 @@ killpy list --type venv --type conda      # filter by type (repeatable)
 killpy list --older-than 90               # not accessed in the last 90 days
 killpy list --json                        # output as a JSON array
 killpy list --json-stream                 # stream as NDJSON — one line per env
+killpy list --quiet                       # suppress progress output (scripts/CI)
 ```
 
+While scanning, `killpy list` shows a live progress indicator on **stderr** so you can see which detector is running. Stdout receives only the final output (table, JSON, or NDJSON), so pipes and redirections are never polluted. Use `--quiet` / `-q` to silence the progress indicator entirely.
+
 `--json` example output:
 
 ```json
@@ -430,9 +461,12 @@ Deletes every `.venv` / `pyvenv.cfg` env not accessed in the last 90 days, witho
 **How do I use killpy in a CI pipeline or script?**
 
 ```bash
-# List as machine-readable JSON
+# List as machine-readable JSON (progress goes to stderr, JSON to stdout)
 killpy list --json
 
+# Suppress progress output entirely with --quiet / -q
+killpy list --json --quiet | jq '.[] | .size_human'
+
 # Stream results as NDJSON in real time
 killpy list --json-stream | jq '.size_bytes'
 
@@ -440,6 +474,8 @@ killpy list --json-stream | jq '.size_bytes'
 killpy --path ./build_artifacts --delete-all --yes
 ```
 
+Progress messages always go to **stderr**, so stdout is clean for piping even without `--quiet`. Use `-q` when you want no output at all on stderr.
+
 **How do I skip certain directories?**
 
 ```bash
@@ -551,7 +587,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.23.0
+  rev: 0.24.1
   hooks:
     - id: killpy
 ```

{killpy-0.23.0 → killpy-0.24.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "killpy"
-version = "0.23.0"
+version = "0.24.1"
 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 🧹."
 readme = "README.md"
 classifiers = [