# PyShrink - Python Project Cleaner & Packager

🚀 **PyShrink** is a command-line tool that helps you **clean, shrink, and package Python projects** by removing unnecessary files and creating distributable ZIP archives.

Perfect for sharing projects in **enterprise environments** where you need clean, minimal code packages without Git repositories or development artifacts.

---

## ✨ Features

- 🧹 **Smart Cleanup**: Removes `__pycache__`, `.pyc`, `.pytest_cache`, `.git`, virtual environments, and other junk files
- 📦 **Auto-Packaging**: Creates timestamped ZIP files of cleaned projects
- 📝 **README Generation**: Optionally creates README.md with project structure
- 📋 **Requirements Detection**: Automatically generates or validates requirements.txt
- 🎨 **Rich CLI**: Beautiful terminal output with colors and progress indicators
- 🔒 **Safe Operation**: Always works on a copy - original project stays untouched
- ⚡ **Multiple Modes**: Interactive, automated, or full cleanup modes

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install pyshrink
```

### From Source

```bash
git clone https://github.com/yourusername/pyshrink.git
cd pyshrink
pip install -e .
```

---

## 🚀 Quick Start

### Interactive Mode (Recommended for first-time users)

```bash
pyshrink
```

You'll be prompted to:
1. Enter the project path
2. Choose whether to create/validate requirements.txt
3. Choose whether to create README.md

### Specify Project Path

```bash
pyshrink --path /path/to/your/project
```

### Auto-create README and Requirements

```bash
pyshrink --path /path/to/your/project --readme --req
```

### Full Cleanup (No README, No Requirements)

```bash
pyshrink --path /path/to/your/project --full
```

---

## 📖 Usage Examples

### Example 1: Clean Current Directory Interactively

```bash
cd my-python-project
pyshrink --path .
```

Interactive prompts will guide you through the process.

### Example 2: Quick Cleanup with All Options

```bash
pyshrink --path ./my-project --readme --req
```

This will:
- Create a copy of your project
- Generate/validate requirements.txt
- Create README.md if missing
- Remove all junk files
- Create a ZIP file with timestamp

### Example 3: Minimal Package (No Docs)

```bash
pyshrink --path ./my-project --full
```

This creates the smallest possible package - no README, no requirements, just clean code.

---

## 🎯 What Gets Removed?

PyShrink removes common Python development artifacts:

### Files Removed:
- `*.pyc` - Python bytecode
- `*.pyo` - Optimized bytecode
- `*.pyd` - Python DLL
- `.DS_Store` - macOS metadata
- `Thumbs.db` - Windows thumbnails
- `*.log` - Log files
- `*.tmp`, `*.temp` - Temporary files

### Directories Removed:
- `__pycache__/` - Python cache
- `.pytest_cache/` - Pytest cache
- `.mypy_cache/` - MyPy cache
- `.git/` - Git repository
- `.venv/`, `venv/`, `env/` - Virtual environments
- `*.egg-info/` - Package metadata
- `build/`, `dist/` - Build artifacts
- `node_modules/` - Node.js packages (if present)

---

## 📋 Command-Line Options

```
usage: pyshrink [-h] [--path PATH] [--req] [--readme] [--full]

Clean and package Python projects

options:
  -h, --help   show this help message and exit
  --path PATH  Path to the Python project to clean
  --req        Automatically create/validate requirements.txt
  --readme     Automatically create README.md if missing
  --full       Full cleanup (no README, no requirements)
```

---

## 🔧 How It Works

1. **Creates a Safe Copy**: PyShrink copies your project to a new directory with a timestamp (e.g., `myproject_pyshrink_20240207_143022`)

2. **Optional README**: Generates a basic README.md with project structure if requested

3. **Optional Requirements**: Scans your code for imports and creates requirements.txt if requested

4. **Deep Cleanup**: Recursively removes all junk files and directories

5. **Creates ZIP**: Packages everything into a clean ZIP file

6. **Original Untouched**: Your original project directory remains completely unchanged

---

## 📂 Output Structure

After running PyShrink, you'll get:

```
/path/to/project/                    # Your original (unchanged)
/path/to/project_pyshrink_TIMESTAMP/ # Clean working copy
/path/to/project_pyshrink_TIMESTAMP.zip  # Final package
```

---

## 🎨 Rich CLI Interface

PyShrink uses the [Rich](https://github.com/Textualize/rich) library for beautiful terminal output:

- ✅ Colored success messages
- ❌ Clear error messages
- ⚠️ Helpful warnings
- 📊 Clean progress indicators
- 🎨 Syntax highlighting

---

## 🔍 Requirements Detection

When you use `--req`, PyShrink:

1. Scans all `.py` files in your project
2. Extracts `import` and `from X import` statements
3. Filters out standard library modules
4. Creates `requirements.txt` with detected packages
5. Warns about packages it couldn't determine versions for

---

## ⚙️ VS Code Extension

PyShrink also has a **VS Code Extension** that provides:

- 🎯 Command Palette integration
- 📁 Automatic workspace detection
- 🖥️ Interactive terminal execution
- ⚡ Quick access to all PyShrink modes

Install from VS Code Marketplace: Search for "PyShrink"

---

## 🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📝 License

This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.

---

## 🐛 Bug Reports & Feature Requests

Found a bug or have a feature request? Please open an issue on [GitHub Issues](https://github.com/yourusername/pyshrink/issues).

---

## 🙏 Acknowledgments

- Built with [Rich](https://github.com/Textualize/rich) for beautiful terminal output
- Inspired by the need for clean code sharing in enterprise environments

---

## 📊 Project Stats

- **Language**: Python 3.7+
- **Dependencies**: Rich (for CLI)
- **License**: MIT
- **Status**: Active Development

---

**Enjoy using PyShrink! 🚀**

*Made with ❤️ for Python developers who value clean code*
