Metadata-Version: 2.4
Name: venvkill
Version: 0.1.3
Summary: npkill for Python — Intelligent Environment Cleaner
Author-email: Harshit Singh <harshit@example.com>
License: MIT
Project-URL: Repository, https://github.com/harshit/venvkill
Keywords: virtualenv,venv,cleaner,cli,disk,python
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: psutil>=5.9.0
Dynamic: license-file

# VENVKILL

> **npkill for Python** — Intelligent Python Environment Cleaner

[![PyPI version](https://img.shields.io/pypi/v/venvkill.svg)](https://pypi.org/project/venvkill/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**venvkill** is a powerful CLI tool that scans your system for Python virtual environments, analyzes them, scores them by deletion priority, and safely cleans them up — freeing gigabytes of disk space.

---

## Features

- **Smart Scanning** — Detects `venv`, `.venv`, `env`, conda, poetry, and pipenv environments
- **Metadata Analysis** — Size, Python version, package count, last-used date
- **Scoring Engine** — Ranks environments by deletion priority (size + age + broken status)
- **Rich UI** — Color-coded, sortable, interactive terminal tables
- **Safe Deletion** — Move to trash first, then confirm permanent delete
- **Cache Detection** — pip cache, `__pycache__`, conda cache
- **JSON Export** — Export full report for scripting or CI pipelines
- **Auto-Clean** — Batch delete environments unused beyond a threshold
- **Cross-Platform** — Windows, macOS, Linux

---

## Installation

```bash
pip install venvkill
```

Or install from source:

```bash
git clone https://github.com/harshit/venvkill
cd venvkill
pip install -e .
```

---

## Usage

### Scan for environments

```bash
# Scan home directory
venvkill scan

# Scan a specific path
venvkill scan --path /projects

# Deep recursive scan
venvkill scan --deep

# Scan current directory (project mode)
venvkill scan --project

# Sort by size instead of score
venvkill scan --sort size
```

**Example output:**

```
╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                      Python Environments                                             │
├────┬──────────┬────────┬──────────┬──────┬───────────┬───────┬────────┬──────────┬──────────────────┤
│ ID │ Name     │   Size │  Python  │ Pkgs │  Last Used │ Score │  Type  │  Status  │ Path             │
├────┼──────────┼────────┼──────────┼──────┼───────────┼───────┼────────┼──────────┼──────────────────┤
│  1 │ ml_env   │ 3.4 GB │  3.10.9  │  128 │  120d ago  │ 18.4  │  venv  │ INACTIVE │ /home/ml_env     │
│  2 │ .venv    │ 850 MB │  3.11.2  │   42 │   45d ago  │  4.0  │  venv  │  ACTIVE  │ /projects/.venv  │
│  3 │ old_proj │ 220 MB │ unknown  │    0 │  365d ago  │ 12.8  │  venv  │  BROKEN  │ /tmp/old_proj    │
╰────┴──────────┴────────┴──────────┴──────┴───────────┴───────┴────────┴──────────┴──────────────────╯

  Legend: ● Active  ● Inactive (>90d)  ● Broken
```

### Interactively clean environments

```bash
# Interactive selection
venvkill clean

# Dry run (preview only)
venvkill clean --dry-run

# Permanently delete (skip trash)
venvkill clean --force

# Delete all found environments
venvkill clean --all

# Only show high-priority targets
venvkill clean --min-score 5.0
```

### Detect and clean caches

```bash
# Show cache sizes
venvkill cache

# Also scan for __pycache__ in current dir
venvkill cache --path /projects

# Clean all detected caches
venvkill cache --clean
```

### Auto-clean inactive environments

```bash
# Delete envs unused for > 180 days (default)
venvkill auto-clean

# Custom threshold
venvkill auto-clean --days 90

# Preview only
venvkill auto-clean --dry-run
```

### Export results

```bash
venvkill export --output report.json
```

### Manage trash

```bash
# List trashed environments
venvkill trash

# Permanently free trashed space
venvkill trash --empty
```

---

## Scoring Formula

Environments are ranked by deletion priority:

```
score = (size_in_gb × 3) + (days_unused / 30) + (broken × 5)
```

| Factor              | Weight | Reason                          |
| ------------------- | ------ | ------------------------------- |
| Size (GB)           | ×3     | Large envs free more disk space |
| Inactivity (months) | ×1     | Older = more likely abandoned   |
| Broken environment  | +5     | No reason to keep a broken env  |

---

## Color Coding

| Color     | Meaning                             |
| --------- | ----------------------------------- |
| 🟢 Green  | Active (used within 90 days)        |
| 🟡 Yellow | Inactive (unused > 90 days)         |
| 🔴 Red    | Broken (missing Python interpreter) |

---

## Safe Deletion

By default, venvkill **moves environments to a trash folder** (`/tmp/venvkill_trash/`) rather than permanently deleting them. This gives you a safety net.

```bash
# See what's in trash
venvkill trash

# Permanently free the space
venvkill trash --empty
```

Use `--force` to skip trash and delete immediately.

---

## JSON Export

```bash
venvkill scan --json results.json
```

Output format:

```json
[
  {
    "path": "/home/user/projects/ml_env",
    "type": "venv",
    "size_bytes": 3650000000,
    "size": "3.4 GB",
    "python_version": "3.10.9",
    "package_count": 128,
    "days_unused": 120,
    "broken": false,
    "inactive": true,
    "score": 18.4,
    "last_modified": "2024-10-01T12:00:00"
  }
]
```

---

## Development

```bash
# Clone and set up
git clone https://github.com/harshit/venvkill
cd venvkill
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Build
python -m build

# Publish
twine upload dist/*
```

---

## Roadmap

- [ ] GUI version (Textual TUI)
- [ ] AI-powered recommendation engine
- [ ] Background monitoring daemon
- [ ] VSCode extension
- [ ] Usage analytics mode (opt-in)

---

## License

MIT © [Harshit Singh](https://github.com/harshit)

---

## Contributing

PRs and issues welcome! Please open an issue before submitting large changes.
