recdelete 1.0.0
Fast, secure, cross-platform recursive file/folder deletion tool
License: MIT
Requires Python: >=3.8
Keywords: cli, delete, recursive, file-management, cleanup, node_modules, cache, cross-platform, fast, secure

# 🗑️ RecDelete for Python

[![PyPI version](https://img.shields.io/pypi/v/recdelete.svg)](https://pypi.org/project/recdelete/)
[![Python Version](https://img.shields.io/pypi/pyversions/recdelete.svg)](https://pypi.org/project/recdelete/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **Fast, secure, cross-platform recursive file/folder deletion tool for Python**

## 📥 Installation

```bash
pip install recdelete
```

The binary is automatically downloaded for your platform during installation.

## 🚀 Quick Start

### CLI

```bash
# Dry run (preview only)
recdelete ./projects node_modules --dry-run

# Actually delete
recdelete ./projects node_modules --force

# Delete log files
recdelete ./logs "*.log" --only-files
```

### Python API

```python
from recdelete import delete, clean_node_modules, RecDelete

# Simple delete
result = delete("./projects", "node_modules", dry_run=True, only_dirs=True)
print(f"Would delete {result.total_deleted} items")
print(f"Would free {result.bytes_freed_human}")

# Clean node_modules
result = clean_node_modules("./projects", dry_run=True)
```

## 📖 API Reference

### RecDelete Class

```python
from recdelete import RecDelete

rd = RecDelete()

# Main delete method
result = rd.delete(
    start_path="./projects",
    target_name="node_modules",
    dry_run=True,            # Preview only
    only_dirs=True,          # Only directories
    only_files=False,        # Only files
    force=True,              # Skip confirmation
    max_depth=None,          # None for unlimited
    parallel=4,              # Worker count
    include=["*.cache"],     # Include patterns
    exclude=["*important*"], # Exclude patterns
    verbose=False,           # Detailed output
    log_file="./log.txt"     # Log to file
)
```

### Convenience Functions

```python
from recdelete import (
    delete,
    scan,
    clean_node_modules,
    clean_python_cache,
    clean_build_artifacts
)

# Scan (dry run)
result = scan("./projects", "*.tmp")

# Clean node_modules
result = clean_node_modules("./projects", dry_run=True)

# Clean Python cache (__pycache__, .pytest_cache, *.pyc)
result = clean_python_cache("./projects")

# Clean build artifacts (dist, build, .next, etc.)
result = clean_build_artifacts("./projects")
```

### DeleteResult Class

```python
@dataclass
class DeleteResult:
    files_deleted: int       # Files deleted
    dirs_deleted: int        # Directories deleted
    files_matched: int       # Files matched
    dirs_matched: int        # Directories matched
    bytes_freed: int         # Bytes freed
    bytes_freed_human: str   # Human-readable size (e.g., "1.5 GB")
    items_scanned: int       # Total items scanned
    errors: int              # Error count
    deleted_paths: list      # List of deleted paths
    error_messages: list     # List of error messages
    start_path: str          # Start path
    target_name: str         # Target pattern
    dry_run: bool            # Was this a dry run
    elapsed_ms: int          # Elapsed milliseconds
    success: bool            # Success status
    
    @property
    def total_deleted(self) -> int:
        """Total deleted items (files + directories)."""
        return self.files_deleted + self.dirs_deleted
```

## 💡 Examples

### Clean Up Node.js Projects

```python
from recdelete import clean_node_modules

# Preview what would be deleted
preview = clean_node_modules("./projects", dry_run=True)
print(f"Would free {preview.bytes_freed_human}")

# Actually delete
result = clean_node_modules("./projects")
print(f"Freed {result.bytes_freed_human}!")
```

### Delete Log Files

```python
from recdelete import delete

result = delete(
    "./logs",
    "*.log",
    only_files=True,
    exclude=["*important*", "*backup*"],
    dry_run=True
)

print(f"Found {result.files_matched} log files")
for path in result.deleted_paths:
    print(f"  - {path}")
```

### Clean Python Project

```python
from recdelete import clean_python_cache, clean_build_artifacts

# Clean all Python cache
result = clean_python_cache("./my_project")
print(f"Cleaned {result.total_deleted} cache items")

# Clean build artifacts
result = clean_build_artifacts("./my_project")
print(f"Removed {result.dirs_deleted} build directories")
```

### Using with Context

```python
from recdelete import RecDelete

# Create instance once, reuse
rd = RecDelete()

# Multiple operations
for project in ["./project1", "./project2", "./project3"]:
    result = rd.clean_node_modules(project, dry_run=False)
    print(f"{project}: Freed {result.bytes_freed_human}")
```

## 🛡️ Security

- **Protected Paths**: System directories (`/`, `C:\Windows`, etc.) cannot be deleted
- **Symbolic Links**: Not followed to prevent escaping directories
- **Dry Run**: Always preview with `dry_run=True` first
- **Confirmation**: Requires confirmation unless `force=True` is used

## 🔗 Links

- **GitHub**: [https://github.com/BhumaSai/cli-tool-recdelete](https://github.com/BhumaSai/cli-tool-recdelete)
- **PyPI**: [https://pypi.org/project/recdelete/](https://pypi.org/project/recdelete/)

## ☕ Support

[Buy Me a Coffee](https://buymeacoffee.com/bhumasai)

## 📜 License

MIT License - see [LICENSE](LICENSE) for details.