Metadata-Version: 2.4
Name: recdelete
Version: 1.0.0
Summary: Fast, secure, cross-platform recursive file/folder deletion tool
Author-email: BSR <bhumasairam123@gmail.com>
Maintainer-email: BSR <bhumasairam123@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/BhumaSai/cli-tool-recdelete
Project-URL: Documentation, https://github.com/BhumaSai/cli-tool-recdelete#readme
Project-URL: Repository, https://github.com/BhumaSai/cli-tool-recdelete.git
Project-URL: Issues, https://github.com/BhumaSai/cli-tool-recdelete/issues
Project-URL: Changelog, https://github.com/BhumaSai/cli-tool-recdelete/blob/main/CHANGELOG.md
Project-URL: Funding, https://buymeacoffee.com/bhumasai
Keywords: cli,delete,recursive,file-management,cleanup,node_modules,cache,cross-platform,fast,secure
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Filesystems
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# 🗑️ 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.
