pypurge 4.0.1

Safe Python project cleanup utility — purge caches, build artifacts, test leftovers, and env clutter with smart protection.

pypurge

Safe & Powerful Python Project Cleaner

---

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

Flag	Description	Default
root...	Directories to clean.	.
-p, --preview	Preview targets without deleting.	False
-y, --yes	Skip interactive confirmation.	False
-q, --quiet	Suppress output except errors.	False
--clean-venv	Include .venv, venv folders.	False
--exclude <pattern>	Exclude glob or regex (re:...).	None
--older-than <days>	Only target items older than N days.	0
--force	Force deletion (chmod if needed).	False
--backup	Create a .zip backup before delete.	False
--config <path>	Path to .pypurge.json.	Auto-detect
--init	Run configuration wizard.	False
--completions <shell>	Generate shell completions.	None

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

Issue	Possible Cause	Solution
"Operation not permitted"	File permissions or locked file.	Try --force or check file owner.
"Lock file is stale"	Previous run crashed or is running.	Remove .pypurge.lock or wait.
"Refusing to run on dangerous root"	You are running on / or ~.	Use --allow-broad-root (Caution!).
No files found	.gitignore might be hiding them.	Try --no-gitignore.

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