killpy 0.23.0__tar.gz → 0.24.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.23.0
+Version: 0.24.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/
@@ -47,6 +47,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 +252,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 +458,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 +471,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 +584,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.23.0
+  rev: 0.24.0
   hooks:
     - id: killpy
 ```

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

@@ -26,6 +26,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 +231,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 +437,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 +450,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 +563,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.23.0
+  rev: 0.24.0
   hooks:
     - id: killpy
 ```

{killpy-0.23.0 → killpy-0.24.0}/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.0}/killpy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.23.0
+Version: 0.24.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/
@@ -47,6 +47,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 +252,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 +458,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 +471,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 +584,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.23.0
+  rev: 0.24.0
   hooks:
     - id: killpy
 ```

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

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