killpy 0.24.2__tar.gz → 0.25.1__tar.gz

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

@@ -1,17 +1,25 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.24.2
-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
@@ -44,7 +52,7 @@ uvx killpy --path ~
 [![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)
+![killpy in action](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/demo.gif)
 
 </div>
 
@@ -62,6 +70,7 @@ ______________________________________________________________________
 - [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 find` — locate environments with a package](#killpy-find--locate-environments-with-a-package)
   - [`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)
@@ -115,9 +124,9 @@ uvx killpy --path ~
 | `pyenv` | pyenv-managed Python versions | `~/.pyenv/versions` |
 | `pipenv` | Pipenv virtualenvs | `~/.local/share/virtualenvs` |
 | `hatch` | Hatch environments | `~/.local/share/hatch/env` |
-| `uv` | uv virtual environments | project root `.uv/` |
+| `uv` | uv tool environments (`uv tool install`) and uv-managed Pythons | `~/.local/share/uv` |
 | `tox` | tox environments | `.tox/` inside repo |
-| `cache` | `__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, global pip/uv caches | everywhere |
+| `cache` | `__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, plus global pip/uv caches when the scanned path contains them | project tree, `~/.cache` |
 | `artifacts` | `dist/`, `build/`, `.egg-info`, `.dist-info` | project root |
 
 ______________________________________________________________________
@@ -180,7 +189,7 @@ killpy --path ~ --exclude "company-projects"
 
 The TUI starts immediately and streams results as each detector finishes — no waiting for a full scan before you can start browsing. Select items, mark them, and confirm; **nothing is deleted without explicit action**.
 
-Environments flagged with `⚠️` are actively in use by the current Python session — killpy will show them but they should not be deleted.
+Environments flagged with `⚠️` are actively in use (the environment killpy runs from, or the pyenv global version) — the TUI shows them but refuses to delete them.
 
 ### Keyboard shortcuts
 
@@ -231,6 +240,8 @@ Options:
   -D, --delete-all      Scan and delete ALL found environments without
                         launching the TUI
   -y, --yes             Skip confirmation prompt (use with --delete-all)
+  --force               With --delete-all: also delete environments
+                        currently in use (⚠ system-critical)
   --help                Show this message and exit.
 ```
 
@@ -248,6 +259,8 @@ ______________________________________________________________________
 
 ### `killpy list` — inspect environments
 
+![killpy list](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/list.gif)
+
 ```bash
 killpy list                               # list all detected environments
 killpy list --path ~/projects             # scan a specific path
@@ -260,6 +273,8 @@ 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.
 
+The **Path** column mirrors the form of `--path`: a relative `--path` produces relative paths, an absolute one produces absolute paths (long paths are truncated to keep rows compact). The full absolute path is always available via `--json` / `--json-stream` in the `absolute_path` field.
+
 `--json` example output:
 
 ```json
@@ -284,10 +299,31 @@ While scanning, `killpy list` shows a live progress indicator on **stderr** so y
 killpy list --json-stream --path ~ | jq 'select(.type == "conda") | .size_human'
 ```
 
+![killpy list --json](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/list-json.gif)
+
+______________________________________________________________________
+
+### `killpy find` — locate environments with a package
+
+![killpy find](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/find.gif)
+
+Find every environment that has a given package installed. `PACKAGE` accepts
+standard PEP 508 / uv-style version specifiers.
+
+```bash
+killpy find requests                      # any version of requests
+killpy find "flask>=1.0"                   # version specifier
+killpy find "numpy>=1.24,<2.0"             # combined constraints
+killpy find requests --type venv           # restrict to a type
+killpy find requests --json                # machine-readable output
+```
+
 ______________________________________________________________________
 
 ### `killpy delete` — remove environments
 
+![killpy delete](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/delete.gif)
+
 ```bash
 killpy delete                             # interactive confirmation before delete
 killpy delete --yes                       # skip confirmation
@@ -295,6 +331,7 @@ killpy delete --dry-run                   # preview — nothing is deleted
 killpy delete --type venv                 # only a specific type
 killpy delete --type venv --type cache    # multiple types
 killpy delete --older-than 180 --yes      # delete stale envs, no prompt
+killpy delete --force                     # include in-use (⚠) environments
 killpy delete --path ~/projects
 ```
 
@@ -302,6 +339,8 @@ ______________________________________________________________________
 
 ### `killpy stats` — disk usage summary
 
+![killpy stats](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/stats.gif)
+
 ```bash
 killpy stats
 killpy stats --path ~/projects
@@ -329,6 +368,8 @@ ______________________________________________________________________
 
 ### `killpy clean` — remove cache directories
 
+![killpy clean](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/clean.gif)
+
 ```bash
 killpy clean
 killpy clean --path ~/projects
@@ -351,6 +392,8 @@ Options:
   --help            Show this message and exit.
 ```
 
+![killpy doctor](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/doctor.gif)
+
 `doctor` analyses every detected virtual environment in two phases:
 
 **Phase 1 — Scoring (for sorting only)**
@@ -373,10 +416,9 @@ 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` |
+| 2 | Active git repository **or** `age < 120 days` | `LOW` |
+| 3 | `age ≥ 120 days` | `MEDIUM` |
+| 4 | Fallback | `LOW` |
 
 Age and orphan status are the dominant signals. Size does not affect the category.
 
@@ -532,7 +574,7 @@ Or press `P` in the TUI to clean them for the scanned path.
 
 **What does ⚠️ mean next to an environment?**
 
-The environment is currently in use by the Python session running killpy. It should not be deleted. killpy will still show it so you are aware of it, but treat it with care.
+The environment is currently in use — it is the environment killpy itself runs from, or your pyenv global version. killpy shows it so you are aware of it, but refuses to delete it: the TUI always skips it, and `killpy delete` / `--delete-all` skip it unless you pass `--force`.
 
 **Does it fail if Conda, pipx or pyenv are not installed?**
 
@@ -562,7 +604,7 @@ ______________________________________________________________________
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.20.0
+  rev: 0.25.1
   hooks:
     - id: killpy                  # remove __pycache__ on every commit
     - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
@@ -587,7 +629,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.24.2
+  rev: 0.25.1
   hooks:
     - id: killpy
 ```
@@ -598,7 +640,7 @@ ______________________________________________________________________
 
 ## Safety
 
-`killpy` performs **destructive, irreversible** actions. Always review the selection before confirming removal. The `--dry-run` flag lets you preview everything safely. Environments marked `⚠️` are actively in use and should not be deleted.
+`killpy` performs **destructive, irreversible** actions. Always review the selection before confirming removal. The `--dry-run` flag lets you preview everything safely. Environments marked `⚠️` are actively in use and are skipped by every delete path unless you explicitly pass `--force`.
 
 **You are responsible for files deleted on your system.**
 

killpy-0.24.2/PKG-INFO → killpy-0.25.1/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.4
-Name: killpy
-Version: 0.24.2
-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/
-Project-URL: Repository, https://github.com/Tlaloc-Es/killpy
-Project-URL: Bug Tracker, https://github.com/Tlaloc-Es/killpy/issues
-Classifier: Environment :: Console
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-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
-
 <div align="center">
 
 ![Logo](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/logo.png)
@@ -44,7 +23,7 @@ uvx killpy --path ~
 [![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)
+![killpy in action](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/demo.gif)
 
 </div>
 
@@ -62,6 +41,7 @@ ______________________________________________________________________
 - [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 find` — locate environments with a package](#killpy-find--locate-environments-with-a-package)
   - [`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)
@@ -115,9 +95,9 @@ uvx killpy --path ~
 | `pyenv` | pyenv-managed Python versions | `~/.pyenv/versions` |
 | `pipenv` | Pipenv virtualenvs | `~/.local/share/virtualenvs` |
 | `hatch` | Hatch environments | `~/.local/share/hatch/env` |
-| `uv` | uv virtual environments | project root `.uv/` |
+| `uv` | uv tool environments (`uv tool install`) and uv-managed Pythons | `~/.local/share/uv` |
 | `tox` | tox environments | `.tox/` inside repo |
-| `cache` | `__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, global pip/uv caches | everywhere |
+| `cache` | `__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, plus global pip/uv caches when the scanned path contains them | project tree, `~/.cache` |
 | `artifacts` | `dist/`, `build/`, `.egg-info`, `.dist-info` | project root |
 
 ______________________________________________________________________
@@ -180,7 +160,7 @@ killpy --path ~ --exclude "company-projects"
 
 The TUI starts immediately and streams results as each detector finishes — no waiting for a full scan before you can start browsing. Select items, mark them, and confirm; **nothing is deleted without explicit action**.
 
-Environments flagged with `⚠️` are actively in use by the current Python session — killpy will show them but they should not be deleted.
+Environments flagged with `⚠️` are actively in use (the environment killpy runs from, or the pyenv global version) — the TUI shows them but refuses to delete them.
 
 ### Keyboard shortcuts
 
@@ -231,6 +211,8 @@ Options:
   -D, --delete-all      Scan and delete ALL found environments without
                         launching the TUI
   -y, --yes             Skip confirmation prompt (use with --delete-all)
+  --force               With --delete-all: also delete environments
+                        currently in use (⚠ system-critical)
   --help                Show this message and exit.
 ```
 
@@ -248,6 +230,8 @@ ______________________________________________________________________
 
 ### `killpy list` — inspect environments
 
+![killpy list](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/list.gif)
+
 ```bash
 killpy list                               # list all detected environments
 killpy list --path ~/projects             # scan a specific path
@@ -260,6 +244,8 @@ 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.
 
+The **Path** column mirrors the form of `--path`: a relative `--path` produces relative paths, an absolute one produces absolute paths (long paths are truncated to keep rows compact). The full absolute path is always available via `--json` / `--json-stream` in the `absolute_path` field.
+
 `--json` example output:
 
 ```json
@@ -284,10 +270,31 @@ While scanning, `killpy list` shows a live progress indicator on **stderr** so y
 killpy list --json-stream --path ~ | jq 'select(.type == "conda") | .size_human'
 ```
 
+![killpy list --json](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/list-json.gif)
+
+______________________________________________________________________
+
+### `killpy find` — locate environments with a package
+
+![killpy find](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/find.gif)
+
+Find every environment that has a given package installed. `PACKAGE` accepts
+standard PEP 508 / uv-style version specifiers.
+
+```bash
+killpy find requests                      # any version of requests
+killpy find "flask>=1.0"                   # version specifier
+killpy find "numpy>=1.24,<2.0"             # combined constraints
+killpy find requests --type venv           # restrict to a type
+killpy find requests --json                # machine-readable output
+```
+
 ______________________________________________________________________
 
 ### `killpy delete` — remove environments
 
+![killpy delete](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/delete.gif)
+
 ```bash
 killpy delete                             # interactive confirmation before delete
 killpy delete --yes                       # skip confirmation
@@ -295,6 +302,7 @@ killpy delete --dry-run                   # preview — nothing is deleted
 killpy delete --type venv                 # only a specific type
 killpy delete --type venv --type cache    # multiple types
 killpy delete --older-than 180 --yes      # delete stale envs, no prompt
+killpy delete --force                     # include in-use (⚠) environments
 killpy delete --path ~/projects
 ```
 
@@ -302,6 +310,8 @@ ______________________________________________________________________
 
 ### `killpy stats` — disk usage summary
 
+![killpy stats](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/stats.gif)
+
 ```bash
 killpy stats
 killpy stats --path ~/projects
@@ -329,6 +339,8 @@ ______________________________________________________________________
 
 ### `killpy clean` — remove cache directories
 
+![killpy clean](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/clean.gif)
+
 ```bash
 killpy clean
 killpy clean --path ~/projects
@@ -351,6 +363,8 @@ Options:
   --help            Show this message and exit.
 ```
 
+![killpy doctor](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/docs/gifs/doctor.gif)
+
 `doctor` analyses every detected virtual environment in two phases:
 
 **Phase 1 — Scoring (for sorting only)**
@@ -373,10 +387,9 @@ 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` |
+| 2 | Active git repository **or** `age < 120 days` | `LOW` |
+| 3 | `age ≥ 120 days` | `MEDIUM` |
+| 4 | Fallback | `LOW` |
 
 Age and orphan status are the dominant signals. Size does not affect the category.
 
@@ -532,7 +545,7 @@ Or press `P` in the TUI to clean them for the scanned path.
 
 **What does ⚠️ mean next to an environment?**
 
-The environment is currently in use by the Python session running killpy. It should not be deleted. killpy will still show it so you are aware of it, but treat it with care.
+The environment is currently in use — it is the environment killpy itself runs from, or your pyenv global version. killpy shows it so you are aware of it, but refuses to delete it: the TUI always skips it, and `killpy delete` / `--delete-all` skip it unless you pass `--force`.
 
 **Does it fail if Conda, pipx or pyenv are not installed?**
 
@@ -562,7 +575,7 @@ ______________________________________________________________________
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.20.0
+  rev: 0.25.1
   hooks:
     - id: killpy                  # remove __pycache__ on every commit
     - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
@@ -587,7 +600,7 @@ Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.24.2
+  rev: 0.25.1
   hooks:
     - id: killpy
 ```
@@ -598,7 +611,7 @@ ______________________________________________________________________
 
 ## Safety
 
-`killpy` performs **destructive, irreversible** actions. Always review the selection before confirming removal. The `--dry-run` flag lets you preview everything safely. Environments marked `⚠️` are actively in use and should not be deleted.
+`killpy` performs **destructive, irreversible** actions. Always review the selection before confirming removal. The `--dry-run` flag lets you preview everything safely. Environments marked `⚠️` are actively in use and are skipped by every delete path unless you explicitly pass `--force`.
 
 **You are responsible for files deleted on your system.**
 

{killpy-0.24.2 → 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
@@ -9,7 +13,8 @@ from rich.prompt import Confirm
 
 from killpy.cleaner import Cleaner, CleanerError
 from killpy.cli import TableApp
-from killpy.commands.clean import clean
+from killpy.commands._utils import partition_in_use
+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
@@ -20,11 +25,13 @@ from killpy.intelligence.tracker import UsageTracker
 from killpy.scanner import Scanner
 
 
-def _run_delete_all(path: Path, excluded: set[str], yes: bool) -> None:
+def _run_delete_all(
+    path: Path, excluded: set[str], yes: bool, force: bool = False
+) -> None:
     """Scan and delete all discovered environments without launching the TUI."""
     console = Console()
     scanner = Scanner(excluded=excluded)
-    cleaner = Cleaner()
+    cleaner = Cleaner(force=force)
 
     with Progress(
         SpinnerColumn(),
@@ -34,6 +41,8 @@ def _run_delete_all(path: Path, excluded: set[str], yes: bool) -> None:
     ):
         envs = scanner.scan(path)
 
+    envs = partition_in_use(envs, force, console)
+
     if not envs:
         console.print("[yellow]No environments found.[/yellow]")
         return
@@ -116,21 +125,30 @@ def _run_delete_all(path: Path, excluded: set[str], yes: bool) -> None:
     default=False,
     help="Skip the confirmation prompt (use together with --delete-all).",
 )
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help=(
+        "With --delete-all: also delete environments currently in use "
+        "(flagged system-critical)."
+    ),
+)
 @click.pass_context
-def cli(ctx, path: Path, exclude: str, delete_all: bool, yes: bool):
+def cli(ctx, path: Path, exclude: str, delete_all: bool, yes: bool, force: bool):
     logging.basicConfig(level=logging.WARNING)
     excluded = (
         {p.strip() for p in exclude.split(",") if p.strip()} if exclude else set()
     )
     if not ctx.invoked_subcommand:
         if delete_all:
-            _run_delete_all(path, excluded, yes)
+            _run_delete_all(path, excluded, yes, force)
         else:
             app = TableApp(root_dir=path, excluded=excluded)
             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.24.2 → killpy-0.25.1}/killpy/cleaner.py

@@ -27,6 +27,10 @@ from killpy.models import Environment
 
 logger = logging.getLogger(__name__)
 
+# Minimum number of path components below the filesystem root for a
+# deletion target: refuses e.g. /usr or /home, which are never environments.
+_MIN_DEPTH_BELOW_ROOT = 2
+
 
 class CleanerError(Exception):
     """Raised when a deletion operation fails."""
@@ -40,10 +44,15 @@ class Cleaner:
     dry_run:
         When ``True`` no destructive operations are performed; the method
         still returns the would-be size so callers can show totals.
+    force:
+        When ``True``, allow deleting environments flagged
+        :attr:`~killpy.models.Environment.is_system_critical` (currently in
+        use).  By default those are refused with a :class:`CleanerError`.
     """
 
-    def __init__(self, dry_run: bool = False) -> None:
+    def __init__(self, dry_run: bool = False, force: bool = False) -> None:
         self.dry_run = dry_run
+        self.force = force
 
     # ------------------------------------------------------------------ #
     #  Public API                                                          #
@@ -61,13 +70,22 @@ class Cleaner:
         -------
         int
             Number of bytes freed (or that *would have been* freed in dry-run
-            mode).
+            mode).  ``0`` when the path was already gone — e.g. it was
+            removed together with a previously deleted parent environment —
+            so callers don't over-report freed space.
 
         Raises
         ------
         CleanerError
-            If the underlying removal command fails.
+            If the underlying removal command fails, or when *env* is
+            system-critical and :attr:`force` is ``False``.
         """
+        if env.is_system_critical and not self.force:
+            raise CleanerError(
+                f"Refusing to delete {env.path}: environment is currently in "
+                "use (system-critical). Pass --force to delete it anyway."
+            )
+
         if self.dry_run:
             logger.info("[dry-run] Would delete %s (%s)", env.path, env.size_human)
             return env.size_bytes
@@ -79,8 +97,8 @@ class Cleaner:
                 self._remove_pipx(env.name)
             elif env.managed_by == "uv":
                 self._remove_uv_tool(env.name)
-            else:
-                self._remove_filesystem(env.path)
+            elif not self._remove_filesystem(env.path):
+                return 0
         except CleanerError:
             raise
         except Exception as exc:  # noqa: BLE001
@@ -128,11 +146,41 @@ class Cleaner:
     # ------------------------------------------------------------------ #
 
     @staticmethod
-    def _remove_filesystem(path: Path) -> None:
+    def _ensure_sane_deletion_target(path: Path) -> None:
+        """Refuse obviously wrong deletion targets (defense in depth).
+
+        The scanner should never produce these, but a bug upstream — or a
+        directory swapped underneath us between scan and delete — must not
+        translate into wiping the filesystem root, the user's home, or a
+        symlink's target tree.  These checks are unconditional; ``force``
+        does not bypass them.
+        """
+        if path.is_symlink():
+            raise CleanerError(
+                f"Refusing to delete {path}: it is a symlink (the "
+                "environment may have been replaced since it was scanned)"
+            )
+        try:
+            resolved = path.resolve()
+        except OSError as exc:
+            raise CleanerError(f"Cannot resolve {path}: {exc}") from exc
+        anchor = Path(resolved.anchor)
+        if resolved == anchor:
+            raise CleanerError(f"Refusing to delete the filesystem root: {resolved}")
+        if resolved == Path.home():
+            raise CleanerError(f"Refusing to delete the home directory: {resolved}")
+        if len(resolved.parts) - len(anchor.parts) < _MIN_DEPTH_BELOW_ROOT:
+            raise CleanerError(f"Refusing to delete top-level directory: {resolved}")
+
+    @staticmethod
+    def _remove_filesystem(path: Path) -> bool:
+        """Remove *path* recursively; return False when it no longer exists."""
         if not path.exists():
             logger.warning("Path no longer exists: %s", path)
-            return
+            return False
+        Cleaner._ensure_sane_deletion_target(path)
         shutil.rmtree(path)
+        return True
 
     @staticmethod
     def _remove_conda(env_name: str) -> None:

killpy-0.25.1/killpy/cleaners/__init__.py

@@ -0,0 +1,34 @@
+"""Stateless ``__pycache__`` removal helper used by ``killpy clean``."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+from killpy.files import get_total_size
+
+
+def remove_pycache(path: Path) -> int:
+    """Remove every ``__pycache__`` directory under *path*.
+
+    The walk never follows symlinks, so a link placed inside the tree
+    cannot steer the deletion outside the scanned root.  Failed removals
+    are skipped and not counted as freed space.
+    """
+    total_freed_space = 0
+    for current_root, directories, _files in os.walk(path, topdown=True):
+        if "__pycache__" not in directories:
+            continue
+        # Prune it from the walk: it is deleted below, not descended into.
+        directories.remove("__pycache__")
+        pycache_dir = Path(current_root) / "__pycache__"
+        if pycache_dir.is_symlink():
+            continue
+        try:
+            size = get_total_size(pycache_dir)
+            shutil.rmtree(pycache_dir)
+        except OSError:
+            continue
+        total_freed_space += size
+    return total_freed_space