pypurge is a production-grade Python cleanup utility designed to safely remove auto-generated files, caches, virtualenv leftovers, test artifacts, and temporary files — without putting your system at risk.

Think of it as a precision broom for Python projects. No more find . -name __pycache__ -delete or risky scripts.

⚡ Quick Start (The "5-Minute Rule")

Prerequisites

• Python 3.8+
• No other external dependencies required.

Installation

pip install pypurge

Run

Clean your current project interactively:

pypurge

Demo

# Preview what would be deleted without touching anything
pypurge --preview

# Clean everything, including virtual environments, older than 7 days
pypurge --clean-venv --older-than 7

✨ Features

Core

• Targeted Cleanup: Smartly handles __pycache__, .pytest_cache, build/, dist/, .egg-info, and more.
• Virtualenv Purge: Optional cleaning of virtual environments (--clean-venv).
• Smart Preview: Shows detailed counts, groups, and disk usage before you confirm deletion.
• Shell Completions: Native auto-completion for bash, zsh, and fish.

Performance & Safety

• 🛡️ Safety-first Design: Prevents accidental root-level deletion (/, ~) and protects system directories.
• Atomic Backups: Create a zip backup with SHA256 manifest before cleaning (--backup).
• Concurrency Safety: Stale lock & lockfile protection to avoid multi-process conflicts.
• Gitignore Awareness: Respects .gitignore rules to avoid cleaning untracked files (--no-gitignore to disable).

Advanced

• Age-based Filtering: Delete only items older than N days (--older-than).
• Configuration Wizard: Easily setup exclusions with pypurge --init.
• CI/CD Ready: Supports non-interactive modes (--yes, --quiet, --log-format json).

🛠️ Configuration

You can configure pypurge using CLI arguments or a .pypurge.json file.

CLI Arguments

Configuration File (.pypurge.json)

Create a .pypurge.json file in your project root for persistent settings.

{
  "exclude_dirs": [".git", "node_modules"],
  "exclude_patterns": ["re:.*migrations.*", "data/"],
  "dir_groups": {
    "CustomData": ["temp_run/", "scratch/"]
  }
}

🏗️ Architecture

pypurge follows a modular architecture for safety and maintainability.

src/pypurge/
├── cli.py             # Entry point
└── modules/
    ├── safety.py      # Root/System protection logic
    ├── scan.py        # File scanning & pattern matching
    ├── deletion.py    # Safe removal operations
    ├── locking.py     # Process locking mechanism
    ├── backup.py      # Atomic backup creation
    ├── config.py      # JSON schema validation
    └── ui.py          # Rich terminal output

Data Flow:

1. CLI: Parses args and loads config.
2. Safety: Validates target root (blocks /, ~).
3. Locking: Acquires .pypurge.lock.
4. Scan: Walks directory tree -> Filters by rules/gitignore -> Groups targets.
5. UI: Displays preview & asks confirmation.
6. Backup: (Optional) Archives targets to zip.
7. Deletion: Removes files/dirs.
8. Cleanup: Releases lock.

🐞 Troubleshooting

Debug Mode: Use --log-format text (default) or --log-format json with --log-file pypurge.log to inspect operations.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to set up your development environment and submit Pull Requests.

To run tests locally:

tox

🗺️ Roadmap

We are constantly improving pypurge. Check out our ROADMAP.md for upcoming features, including:

• Enhanced AI-based clutter detection.
• Plugin system for custom cleaners.
• Deeper IDE integrations.

License

MIT © Dhruv