killpy 0.22.0__tar.gz → 0.24.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.22.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/
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.1.8
+Requires-Dist: packaging>=24.0
 Requires-Dist: rich>=13.9.4
 Requires-Dist: textual>=1.0.0
 
@@ -46,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.
@@ -226,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
@@ -429,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'
 
@@ -439,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
@@ -550,7 +584,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.22.0
+  rev: 0.24.0
   hooks:
     - id: killpy
 ```

{killpy-0.22.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.22.0
+  rev: 0.24.0
   hooks:
     - id: killpy
 ```

{killpy-0.22.0 → killpy-0.24.0}/killpy/__main__.py

@@ -11,6 +11,7 @@ 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.find import find_cmd
 from killpy.commands.list import list_cmd
 from killpy.commands.stats import stats_cmd
 from killpy.files import format_size
@@ -120,6 +121,7 @@ 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")
+cli.add_command(find_cmd, name="find")
 
 
 if __name__ == "__main__":

killpy-0.24.0/killpy/commands/find.py

@@ -0,0 +1,197 @@
+"""``killpy find`` – locate environments that have a specific package installed."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+from packaging.requirements import Requirement
+from packaging.version import InvalidVersion
+from rich.console import Console
+from rich.table import Table
+
+from killpy.commands._utils import filter_envs
+from killpy.scanner import Scanner
+
+# ---------------------------------------------------------------------------
+# Helpers: read installed-package metadata from a venv directory
+# ---------------------------------------------------------------------------
+
+
+def _site_packages(env_path: Path) -> list[Path]:
+    """Return all site-packages directories found inside *env_path*.
+
+    Supports the Unix layout (``lib/python3.x/site-packages``) and the
+    Windows layout (``Lib/site-packages``).
+    """
+    result: list[Path] = []
+
+    # Unix: lib/python<ver>/site-packages
+    lib = env_path / "lib"
+    if lib.is_dir():
+        for child in lib.iterdir():
+            sp = child / "site-packages"
+            if sp.is_dir():
+                result.append(sp)
+
+    # Windows: Lib/site-packages
+    win_sp = env_path / "Lib" / "site-packages"
+    if win_sp.is_dir():
+        result.append(win_sp)
+
+    return result
+
+
+def _read_metadata_field(metadata_path: Path, field: str) -> str | None:
+    """Return the value of a single RFC 822-style *field* from *metadata_path*."""
+    prefix = f"{field}:"
+    try:
+        with metadata_path.open(encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if line.startswith(prefix):
+                    return line[len(prefix) :].strip()
+                # RFC 822 headers end at the first blank line.
+                if not line.strip():
+                    break
+    except OSError:
+        pass
+    return None
+
+
+def _normalise_name(name: str) -> str:
+    """Normalise a distribution name to a lowercase, underscore form."""
+    return name.lower().replace("-", "_").replace(".", "_")
+
+
+def installed_packages(env_path: Path) -> dict[str, str]:
+    """Return ``{normalised_name: version}`` for every package installed in *env_path*.
+
+    Reads ``*.dist-info/METADATA`` files from all site-packages directories
+    found under the environment root.  Non-venv paths (e.g. conda envs created
+    with ``--prefix``) are supported as long as they follow the same layout.
+    """
+    packages: dict[str, str] = {}
+    for sp in _site_packages(env_path):
+        for dist_info in sp.glob("*.dist-info"):
+            metadata = dist_info / "METADATA"
+            if not metadata.exists():
+                continue
+            name = _read_metadata_field(metadata, "Name")
+            version = _read_metadata_field(metadata, "Version")
+            if name and version:
+                packages[_normalise_name(name)] = version
+    return packages
+
+
+def package_version_match(
+    packages: dict[str, str], requirement: Requirement
+) -> str | None:
+    """Return the installed version string if it satisfies *requirement*, else ``None``."""  # noqa: E501
+    norm_name = _normalise_name(requirement.name)
+    installed = packages.get(norm_name)
+    if installed is None:
+        return None
+    try:
+        if requirement.specifier.contains(installed, prereleases=True):
+            return installed
+    except InvalidVersion:
+        pass
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Click command
+# ---------------------------------------------------------------------------
+
+
+@click.command("find")
+@click.argument("package")
+@click.option(
+    "--path",
+    default=Path.cwd,
+    type=click.Path(path_type=Path, exists=True, file_okay=False, dir_okay=True),
+    help="Root directory to scan.",
+)
+@click.option(
+    "--type",
+    "types",
+    multiple=True,
+    metavar="TYPE",
+    help=(
+        "Limit the scan to these environment types (repeatable). "
+        "Example: --type venv --type conda"
+    ),
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Output as a JSON array.",
+)
+def find_cmd(
+    package: str,
+    path: Path,
+    types: tuple[str, ...],
+    as_json: bool,
+) -> None:
+    """Find environments that have PACKAGE installed.
+
+    PACKAGE accepts standard PEP 508 / uv-style version specifiers:
+
+    \b
+        killpy find requests
+        killpy find "requests>=2.28"
+        killpy find "numpy>=1.24,<2.0"
+        killpy find "django==4.2.*"
+        killpy find "scipy~=1.11"
+    """
+    try:
+        req = Requirement(package)
+    except Exception as exc:  # packaging.requirements.InvalidRequirement
+        raise click.BadParameter(str(exc), param_hint="PACKAGE") from exc
+
+    scanner = Scanner(types=set(types) if types else None)
+    envs = scanner.scan(path)
+    envs = filter_envs(envs, types or None, None)
+
+    matches: list[tuple] = []  # (Environment, version_string)
+    for env in envs:
+        pkgs = installed_packages(env.path)
+        version = package_version_match(pkgs, req)
+        if version is not None:
+            matches.append((env, version))
+
+    if as_json:
+        click.echo(
+            json.dumps(
+                [{**env.to_dict(), "matched_version": ver} for env, ver in matches],
+                indent=2,
+            )
+        )
+        return
+
+    console = Console()
+
+    if not matches:
+        console.print(
+            f"[yellow]No environments found with[/yellow] "
+            f"[bold]{package}[/bold] installed."
+        )
+        return
+
+    table = Table(title=f"Environments with {package!r}", show_lines=False)
+    table.add_column("Path", style="cyan")
+    table.add_column("Type", style="magenta")
+    table.add_column("Installed version", style="green")
+    table.add_column("Env size", style="yellow", justify="right")
+
+    for env, ver in matches:
+        table.add_row(str(env.path), env.type, ver, env.size_human)
+
+    console.print(table)
+    console.print(
+        f"\n[bold]{len(matches)}[/bold] environment(s) match "
+        f"[bold cyan]{package}[/bold cyan]."
+    )

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.22.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/
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click>=8.1.8
+Requires-Dist: packaging>=24.0
 Requires-Dist: rich>=13.9.4
 Requires-Dist: textual>=1.0.0
 
@@ -46,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.
@@ -226,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
@@ -429,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'
 
@@ -439,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
@@ -550,7 +584,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.22.0
+  rev: 0.24.0
   hooks:
     - id: killpy
 ```

{killpy-0.22.0 → killpy-0.24.0}/killpy.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ killpy/commands/_utils.py
 killpy/commands/clean.py
 killpy/commands/delete.py
 killpy/commands/doctor.py
+killpy/commands/find.py
 killpy/commands/list.py
 killpy/commands/stats.py
 killpy/detectors/__init__.py

{killpy-0.22.0 → killpy-0.24.0}/killpy.egg-info/requires.txt

@@ -1,3 +1,4 @@
 click>=8.1.8
+packaging>=24.0
 rich>=13.9.4
 textual>=1.0.0

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

@@ -1,6 +1,6 @@
 [project]
 name = "killpy"
-version = "0.22.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 = [
@@ -11,7 +11,12 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
-dependencies = ["click>=8.1.8", "rich>=13.9.4", "textual>=1.0.0"]
+dependencies = [
+    "click>=8.1.8",
+    "packaging>=24.0",
+    "rich>=13.9.4",
+    "textual>=1.0.0",
+]
 requires-python = ">=3.10"
 
 [project.urls]