killpy 0.21.0__tar.gz → 0.22.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.21.0
+Version: 0.22.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/
@@ -22,9 +22,13 @@ Requires-Dist: textual>=1.0.0
 
 ![Logo](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/logo.png)
 
-### Reclaim disk space by finding and deleting Python environments you no longer use
+### Free GBs of disk space by removing unused Python environments
 
-Python environment cleaner for virtualenv, Conda, Poetry, pipx, pyenv, tox, Pipenv, Hatch, uv, caches, and build artifacts.
+Find and delete old `.venv`, conda, poetry, pipenv, uv and more — safely, in seconds.
+
+```bash
+uvx killpy --path ~
+```
 
 [Documentation](https://tlaloc-es.github.io/killpy/)
 
@@ -515,18 +519,44 @@ Each virtual environment is a full copy (or symlinked tree) of a Python interpre
 
 ______________________________________________________________________
 
-## Pre-commit hook
+## Pre-commit hooks
+
+`killpy` ships four hooks for [pre-commit](https://pre-commit.com/). Add the ones you need to your `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/Tlaloc-Es/KillPy
+  rev: 0.20.0
+  hooks:
+    - id: killpy                  # remove __pycache__ on every commit
+    - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
+    - id: killpy-clean-artifacts  # remove dist/, build/, *.egg-info before committing
+    - id: killpy-remove-venv      # remove .venv (manual stage — see below)
+```
+
+| Hook id | What it removes | Default stage |
+|---------|-----------------|---------------|
+| `killpy` | `__pycache__` directories | `pre-commit` |
+| `killpy-clean-caches` | All local cache dirs (`__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`) | `pre-commit` |
+| `killpy-clean-artifacts` | Build artifacts (`dist/`, `build/`, `*.egg-info`) | `pre-commit` |
+| `killpy-remove-venv` | Local `.venv` environments | `manual` |
+
+**`killpy-remove-venv`** is staged as `manual` because deleting the environment on every commit would require you to recreate it each time. Run it explicitly when you want a clean slate:
 
-Keep your repo free of `__pycache__` on every commit:
+```bash
+pre-commit run killpy-remove-venv --hook-stage manual
+```
+
+Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.21.0
+  rev: 0.22.0
   hooks:
     - id: killpy
-      pass_filenames: false
 ```
 
+Add `killpy-clean-artifacts` if your project generates `dist/` or `build/` locally and you want to guarantee they are never staged by accident.
+
 ______________________________________________________________________
 
 ## Safety

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

@@ -2,9 +2,13 @@
 
 ![Logo](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/logo.png)
 
-### Reclaim disk space by finding and deleting Python environments you no longer use
+### Free GBs of disk space by removing unused Python environments
 
-Python environment cleaner for virtualenv, Conda, Poetry, pipx, pyenv, tox, Pipenv, Hatch, uv, caches, and build artifacts.
+Find and delete old `.venv`, conda, poetry, pipenv, uv and more — safely, in seconds.
+
+```bash
+uvx killpy --path ~
+```
 
 [Documentation](https://tlaloc-es.github.io/killpy/)
 
@@ -495,18 +499,44 @@ Each virtual environment is a full copy (or symlinked tree) of a Python interpre
 
 ______________________________________________________________________
 
-## Pre-commit hook
+## Pre-commit hooks
+
+`killpy` ships four hooks for [pre-commit](https://pre-commit.com/). Add the ones you need to your `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/Tlaloc-Es/KillPy
+  rev: 0.20.0
+  hooks:
+    - id: killpy                  # remove __pycache__ on every commit
+    - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
+    - id: killpy-clean-artifacts  # remove dist/, build/, *.egg-info before committing
+    - id: killpy-remove-venv      # remove .venv (manual stage — see below)
+```
+
+| Hook id | What it removes | Default stage |
+|---------|-----------------|---------------|
+| `killpy` | `__pycache__` directories | `pre-commit` |
+| `killpy-clean-caches` | All local cache dirs (`__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`) | `pre-commit` |
+| `killpy-clean-artifacts` | Build artifacts (`dist/`, `build/`, `*.egg-info`) | `pre-commit` |
+| `killpy-remove-venv` | Local `.venv` environments | `manual` |
+
+**`killpy-remove-venv`** is staged as `manual` because deleting the environment on every commit would require you to recreate it each time. Run it explicitly when you want a clean slate:
 
-Keep your repo free of `__pycache__` on every commit:
+```bash
+pre-commit run killpy-remove-venv --hook-stage manual
+```
+
+Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.21.0
+  rev: 0.22.0
   hooks:
     - id: killpy
-      pass_filenames: false
 ```
 
+Add `killpy-clean-artifacts` if your project generates `dist/` or `build/` locally and you want to guarantee they are never staged by accident.
+
 ______________________________________________________________________
 
 ## Safety

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

@@ -1,3 +1,4 @@
+import logging
 from pathlib import Path
 
 import click
@@ -102,6 +103,7 @@ def _run_delete_all(path: Path, excluded: set[str], yes: bool) -> None:
 )
 @click.pass_context
 def cli(ctx, path: Path, exclude: str, delete_all: bool, yes: bool):
+    logging.basicConfig(level=logging.WARNING)
     excluded = (
         {p.strip() for p in exclude.split(",") if p.strip()} if exclude else set()
     )

killpy-0.22.0/killpy/commands/_utils.py

@@ -0,0 +1,65 @@
+"""Shared helpers for ``killpy`` commands."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from killpy.models import Environment
+
+# Maps user-facing type names (detector names) to the concrete ``Environment.type``
+# values those detectors produce.  Two detectors use sub-type tags instead of
+# their own name: VenvDetector (tags: ".venv", "pyvenv.cfg") and CacheDetector
+# (tags: "__pycache__", ".mypy_cache", ".pytest_cache", ".ruff_cache",
+# "pip-cache", "uv-cache").  Without this mapping, ``--type venv`` and
+# ``--type cache`` would never match anything.
+_TYPE_ALIASES: dict[str, frozenset[str]] = {
+    "venv": frozenset({".venv", "pyvenv.cfg"}),
+    "cache": frozenset(
+        {
+            "__pycache__",
+            ".mypy_cache",
+            ".pytest_cache",
+            ".ruff_cache",
+            "pip-cache",
+            "uv-cache",
+        }
+    ),
+}
+
+
+def filter_envs(
+    envs: list[Environment],
+    types: tuple[str, ...] | None,
+    older_than: int | None,
+) -> list[Environment]:
+    """Return a filtered subset of *envs*.
+
+    Parameters
+    ----------
+    envs:
+        Full list of detected environments.
+    types:
+        If provided, only environments whose :attr:`~killpy.models.Environment.type`
+        matches one of these strings (case-insensitive) are kept.  Detector
+        names such as ``"venv"`` and ``"cache"`` are automatically expanded to
+        their concrete sub-type values via :data:`_TYPE_ALIASES`.
+    older_than:
+        If provided, only environments not accessed in the last *older_than* days
+        are kept.
+    """
+    now = datetime.now(tz=timezone.utc)
+    result = envs
+
+    if types:
+        expanded: set[str] = set()
+        for t in types:
+            t_lower = t.strip().lower()
+            expanded.add(t_lower)
+            expanded.update(_TYPE_ALIASES.get(t_lower, frozenset()))
+        result = [e for e in result if e.type.lower() in expanded]
+
+    if older_than is not None:
+        cutoff = now - timedelta(days=older_than)
+        result = [e for e in result if e.last_accessed < cutoff]
+
+    return result

{killpy-0.21.0 → killpy-0.22.0}/killpy/commands/clean.py

@@ -1,4 +1,3 @@
-import logging
 from pathlib import Path
 
 import click
@@ -10,8 +9,7 @@ from killpy.files import format_size
 @click.command()
 @click.option("--path", default=Path.cwd(), help="Path to the directory to clean")
 def clean(path):
-    logging.basicConfig(level=logging.INFO)
     path = Path(path)
-    logging.info(f"Executing the clean command in {path}")
+    click.echo(f"Cleaning {path}…")
     total_freed_space = remove_pycache(path)
-    logging.info(f"{format_size(total_freed_space)} deleted")
+    click.echo(f"{format_size(total_freed_space)} freed")

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

@@ -3,38 +3,18 @@
 from __future__ import annotations
 
 import sys
-from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 import click
 from rich.console import Console
 
 from killpy.cleaner import Cleaner, CleanerError
+from killpy.commands._utils import filter_envs
 from killpy.files import format_size
 from killpy.intelligence.tracker import UsageTracker
-from killpy.models import Environment
 from killpy.scanner import Scanner
 
 
-def _filter_envs(
-    envs: list[Environment],
-    types: tuple[str, ...] | None,
-    older_than: int | None,
-) -> list[Environment]:
-    now = datetime.now(tz=timezone.utc)
-    result = envs
-
-    if types:
-        type_set = {t.strip().lower() for t in types}
-        result = [e for e in result if e.type.lower() in type_set]
-
-    if older_than is not None:
-        cutoff = now - timedelta(days=older_than)
-        result = [e for e in result if e.last_accessed < cutoff]
-
-    return result
-
-
 @click.command("delete")
 @click.option(
     "--path",
@@ -88,7 +68,7 @@ def delete_cmd(
 
     scanner = Scanner(types=set(types) if types else None)
     envs = scanner.scan(path)
-    envs = _filter_envs(envs, types or None, older_than)
+    envs = filter_envs(envs, types or None, older_than)
 
     if not envs:
         console.print("[yellow]No environments found matching the criteria.[/yellow]")

{killpy-0.21.0 → killpy-0.22.0}/killpy/commands/doctor.py

@@ -10,6 +10,7 @@ import click
 from rich.console import Console
 from rich.table import Table
 
+from killpy.detectors import ALL_DETECTORS
 from killpy.files import format_size
 from killpy.intelligence import SuggestionEngine, UsageTracker, score_all
 from killpy.models import Suggestion
@@ -29,16 +30,9 @@ _TOP_N = 5
 
 # Detectors that surface virtual environments.  Cache / artifact detectors
 # are intentionally excluded from doctor – use `killpy clean` for those.
+_CACHE_ARTIFACT_TYPES: frozenset[str] = frozenset({"cache", "artifacts"})
 _ENV_TYPES: set[str] = {
-    "venv",
-    "poetry",
-    "conda",
-    "pipx",
-    "pyenv",
-    "pipenv",
-    "hatch",
-    "uv",
-    "tox",
+    cls.name for cls in ALL_DETECTORS if cls.name not in _CACHE_ARTIFACT_TYPES
 }
 
 

{killpy-0.21.0 → killpy-0.22.0}/killpy/commands/list.py

@@ -3,39 +3,17 @@
 from __future__ import annotations
 
 import json
-from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 import click
 from rich.console import Console
 from rich.table import Table
 
+from killpy.commands._utils import filter_envs
 from killpy.files import format_size
-from killpy.models import Environment
 from killpy.scanner import Scanner
 
 
-def _filter_envs(
-    envs: list[Environment],
-    types: tuple[str, ...] | None,
-    older_than: int | None,
-) -> list[Environment]:
-    now = datetime.now(tz=timezone.utc)
-    result = envs
-
-    if types:
-        type_set = {t.strip().lower() for t in types}
-        result = [e for e in result if e.type.lower() in type_set]
-
-    if older_than is not None:
-        cutoff = now - timedelta(days=older_than)
-        result = [
-            e for e in result if e.last_accessed < cutoff
-        ]
-
-    return result
-
-
 @click.command("list")
 @click.option(
     "--path",
@@ -87,14 +65,14 @@ def list_cmd(
     if as_json_stream:
 
         def _stream_progress(_detector, envs):
-            for env in _filter_envs(envs, types or None, older_than):
+            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)
         return
 
     envs = scanner.scan(path)
-    envs = _filter_envs(envs, types or None, older_than)
+    envs = filter_envs(envs, types or None, older_than)
 
     if as_json:
         click.echo(json.dumps([e.to_dict() for e in envs], indent=2))

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/artifacts.py

@@ -50,7 +50,8 @@ class ArtifactsDetector(AbstractDetector):
                         stat = artifact_path.stat()
                         size = get_total_size(artifact_path)
                         mtime = datetime.fromtimestamp(
-                            stat.st_mtime, tz=timezone.utc,
+                            stat.st_mtime,
+                            tz=timezone.utc,
                         )
                         envs.append(
                             Environment(
@@ -66,5 +67,4 @@ class ArtifactsDetector(AbstractDetector):
                     pruned.add(d)  # don't recurse inside
             directories[:] = [d for d in directories if d not in pruned]
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/conda.py

@@ -81,5 +81,4 @@ class CondaDetector(AbstractDetector):
             except (FileNotFoundError, OSError) as exc:
                 logger.debug("Skipping inaccessible conda env %s: %s", env_path, exc)
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/hatch.py

@@ -56,7 +56,8 @@ class HatchDetector(AbstractDetector):
                         stat = env_dir.stat()
                         size = get_total_size(env_dir)
                         mtime = datetime.fromtimestamp(
-                            stat.st_mtime, tz=timezone.utc,
+                            stat.st_mtime,
+                            tz=timezone.utc,
                         )
                         envs.append(
                             Environment(
@@ -73,5 +74,4 @@ class HatchDetector(AbstractDetector):
             logger.error("Cannot inspect hatch envs root: %s", exc)
             return []
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/pipenv.py

@@ -49,7 +49,8 @@ class PipenvDetector(AbstractDetector):
                     stat = venv_path.stat()
                     size = get_total_size(venv_path)
                     mtime = datetime.fromtimestamp(
-                        stat.st_mtime, tz=timezone.utc,
+                        stat.st_mtime,
+                        tz=timezone.utc,
                     )
                     envs.append(
                         Environment(
@@ -66,5 +67,4 @@ class PipenvDetector(AbstractDetector):
             logger.error("Cannot inspect pipenv venvs root: %s", exc)
             return []
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/poetry.py

@@ -49,7 +49,8 @@ class PoetryDetector(AbstractDetector):
                     stat = venv_path.stat()
                     size = get_total_size(venv_path)
                     mtime = datetime.fromtimestamp(
-                        stat.st_mtime, tz=timezone.utc,
+                        stat.st_mtime,
+                        tz=timezone.utc,
                     )
                     envs.append(
                         Environment(
@@ -69,5 +70,4 @@ class PoetryDetector(AbstractDetector):
             logger.error("Cannot inspect poetry virtualenvs dir: %s", exc)
             return []
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/pyenv.py

@@ -50,7 +50,8 @@ class PyenvDetector(AbstractDetector):
                     stat = version_dir.stat()
                     size = get_total_size(version_dir)
                     mtime = datetime.fromtimestamp(
-                        stat.st_mtime, tz=timezone.utc,
+                        stat.st_mtime,
+                        tz=timezone.utc,
                     )
                     envs.append(
                         Environment(
@@ -67,5 +68,4 @@ class PyenvDetector(AbstractDetector):
             logger.error("Cannot inspect pyenv versions root: %s", exc)
             return []
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/tox.py

@@ -38,7 +38,8 @@ class ToxDetector(AbstractDetector):
                         stat = tox_path.stat()
                         size = get_total_size(tox_path)
                         mtime = datetime.fromtimestamp(
-                            stat.st_mtime, tz=timezone.utc,
+                            stat.st_mtime,
+                            tz=timezone.utc,
                         )
                         envs.append(
                             Environment(
@@ -54,5 +55,4 @@ class ToxDetector(AbstractDetector):
                     pruned.add(d)
             directories[:] = [d for d in directories if d not in pruned]
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/uv.py

@@ -44,7 +44,8 @@ class UvDetector(AbstractDetector):
                         stat = uv_path.stat()
                         size = get_total_size(uv_path)
                         mtime = datetime.fromtimestamp(
-                            stat.st_mtime, tz=timezone.utc,
+                            stat.st_mtime,
+                            tz=timezone.utc,
                         )
                         envs.append(
                             Environment(
@@ -60,5 +61,4 @@ class UvDetector(AbstractDetector):
                     pruned.add(d)
             directories[:] = [d for d in directories if d not in pruned]
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs

{killpy-0.21.0 → killpy-0.22.0}/killpy/detectors/venv.py

@@ -89,7 +89,6 @@ class VenvDetector(AbstractDetector):
             except (FileNotFoundError, OSError) as exc:
                 logger.debug("Skipping %s: %s", venv_dir, exc)
 
-        envs.sort(key=lambda e: e.size_bytes, reverse=True)
         return envs
 
 

{killpy-0.21.0 → killpy-0.22.0}/killpy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: killpy
-Version: 0.21.0
+Version: 0.22.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/
@@ -22,9 +22,13 @@ Requires-Dist: textual>=1.0.0
 
 ![Logo](https://raw.githubusercontent.com/Tlaloc-Es/killpy/master/logo.png)
 
-### Reclaim disk space by finding and deleting Python environments you no longer use
+### Free GBs of disk space by removing unused Python environments
 
-Python environment cleaner for virtualenv, Conda, Poetry, pipx, pyenv, tox, Pipenv, Hatch, uv, caches, and build artifacts.
+Find and delete old `.venv`, conda, poetry, pipenv, uv and more — safely, in seconds.
+
+```bash
+uvx killpy --path ~
+```
 
 [Documentation](https://tlaloc-es.github.io/killpy/)
 
@@ -515,18 +519,44 @@ Each virtual environment is a full copy (or symlinked tree) of a Python interpre
 
 ______________________________________________________________________
 
-## Pre-commit hook
+## Pre-commit hooks
+
+`killpy` ships four hooks for [pre-commit](https://pre-commit.com/). Add the ones you need to your `.pre-commit-config.yaml`:
+
+```yaml
+- repo: https://github.com/Tlaloc-Es/KillPy
+  rev: 0.20.0
+  hooks:
+    - id: killpy                  # remove __pycache__ on every commit
+    - id: killpy-clean-caches     # also removes .mypy_cache, .pytest_cache, .ruff_cache
+    - id: killpy-clean-artifacts  # remove dist/, build/, *.egg-info before committing
+    - id: killpy-remove-venv      # remove .venv (manual stage — see below)
+```
+
+| Hook id | What it removes | Default stage |
+|---------|-----------------|---------------|
+| `killpy` | `__pycache__` directories | `pre-commit` |
+| `killpy-clean-caches` | All local cache dirs (`__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`) | `pre-commit` |
+| `killpy-clean-artifacts` | Build artifacts (`dist/`, `build/`, `*.egg-info`) | `pre-commit` |
+| `killpy-remove-venv` | Local `.venv` environments | `manual` |
+
+**`killpy-remove-venv`** is staged as `manual` because deleting the environment on every commit would require you to recreate it each time. Run it explicitly when you want a clean slate:
 
-Keep your repo free of `__pycache__` on every commit:
+```bash
+pre-commit run killpy-remove-venv --hook-stage manual
+```
+
+Typical minimal setup (safe for daily use):
 
 ```yaml
 - repo: https://github.com/Tlaloc-Es/KillPy
-  rev: 0.21.0
+  rev: 0.22.0
   hooks:
     - id: killpy
-      pass_filenames: false
 ```
 
+Add `killpy-clean-artifacts` if your project generates `dist/` or `build/` locally and you want to guarantee they are never staged by accident.
+
 ______________________________________________________________________
 
 ## Safety

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

@@ -14,6 +14,7 @@ killpy.egg-info/requires.txt
 killpy.egg-info/top_level.txt
 killpy/cleaners/__init__.py
 killpy/commands/__init__.py
+killpy/commands/_utils.py
 killpy/commands/clean.py
 killpy/commands/delete.py
 killpy/commands/doctor.py

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

@@ -1,6 +1,6 @@
 [project]
 name = "killpy"
-version = "0.21.0"
+version = "0.22.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 = [