# PPTX Image Compressor - Packaging & Distribution Guide

## Overview

This project now supports 3 different deployment approaches:
1. **Embedded Python** (Current - Development & Local Use)
2. **PyInstaller Portable** (Recommended for End Users)
3. **Hybrid Approach** (Recommended for Maximum Flexibility)

---

## Approach 1: Embedded Python (Development Setup)

### Use Case
- ✅ Development with VS Code
- ✅ Debugging with Python Debugger
- ✅ Running tests with pytest
- ✅ Source code control & modifications

### What You Have
- `install_and_run.bat` - Main launcher
- `.venv/` - Virtual environment for development
- Source code - Fully editable

### Usage
```bash
# Development (with --debug flag to see pip output)
.\install_and_run.bat --debug -i "path\to\file.pptx" -o "path\to\output.pptx"

# With VS Code debugger
# Open pptx_image_compress.py and click "Debug" or press F5

# Run tests
.\.venv\Scripts\pytest tests/
```

### Setup Instructions
1. Ensure Python 3.9+ is installed on Windows
2. Run: `.\install_and_run.bat`
3. Virtual environment is created/updated automatically

### Files
- `install_and_run.bat` - Handles Python setup and execution
- `requirements.txt` - Python package dependencies for runtime
- `requirements-dev.txt` - Development dependencies (pytest, coverage, etc.)

---

## Approach 2: PyInstaller Portable (User Distribution)

### Use Case
- ✅ Distribute to end users (No Python installation needed)
- ✅ Single-file executable
- ✅ Professional appearance
- ✅ "Just download and run" experience
- ✅ Drag-and-drop support for non-technical users

### What Gets Generated
- `dist/pptx-image-compress.exe` - Standalone executable
- `dist/run.bat` - Simple command-line wrapper
- `dist/dragdrop.bat` - Drag-and-drop wrapper (easiest for users)

### Usage by End User
```bash
# Option 1: Drag-and-drop (Easiest!)
#   Drag a .pptx file onto dragdrop.bat
#   Output: filename_compressed.pptx

# Option 2: Command line
.\pptx-image-compress.exe -i "path\to\file.pptx" -o "path\to\output.pptx"

# Option 3: Wrapper
.\run.bat -i "path\to\file.pptx" -o "path\to\output.pptx"

# Get help
.\pptx-image-compress.exe --help
```

### Build Instructions
1. Ensure you have the development environment set up (Approach 1)
2. Run: `.\build.bat`
3. Wait for build to complete (first run takes 2-3 minutes)
4. Generated files are in `dist/` folder

### Build Files
- `build.bat` - Automated build script that:
  - Installs PyInstaller if needed
  - Compiles Python to standalone executable
  - Creates wrapper batch file
  - Prepares distribution package

### Advantages
- No Python installation required on user's machine
- Smaller footprint than full Python installation
- Professional distribution option
- Can be code-signed and digitally stamped

### Limitations
- Larger file size (~80-150 MB) due to bundled Python
- First launch slightly slower (unpacking)
- Harder to debug if issues occur

### Distribution Notes
- Ensure `caesiumclt.exe` is in the same directory as the .exe
- Can optionally add `.venv\Lib\site-packages\svg_polish\*` if svg-polish needs updating
- All dependencies are pre-bundled
- Users can:
  1. **Drag-and-drop files** onto `dragdrop.bat` for easy compression
  2. Use command line for batch operations
  3. Call `.exe` directly with custom parameters

### Drag-and-Drop Feature
The `dragdrop.bat` wrapper provides the easiest user experience:
- Drag a `.pptx` file onto `dragdrop.bat`
- Automatically creates `[filename]_compressed.pptx` in the same directory
- Shows progress and completion status
- No command-line knowledge required

---

## Approach 3: Hybrid (Recommended)

### Use Case
- ✅ Flexible development workflow
- ✅ Easy distribution to users
- ✅ Best of both worlds

### How It Works
**For Developers:**
- Use Embedded Python approach (Approach 1)
- Edit code, debug, run tests
- Keep development lightweight

**For Users:**
- Use PyInstaller Portable (Approach 2)
- Download and run .exe
- No installation or configuration needed

### Workflow
```
Development Phase:
├── Edit code
├── Test with: .\.venv\Scripts\pytest
├── Debug with VS Code
└── Use: .\install_and_run.bat --debug -i file.pptx

Release Phase:
├── Run: .\build.bat
├── Test the .exe: .\dist\pptx-image-compress.exe -i file.pptx
├── Package: Copy dist/* to users
└── Users just run: pptx-image-compress.exe
```

---

## Dependency Management

### Runtime Dependencies (required for execution)
See `requirements.txt`:
- `svg-polish==1.0.0` - SVG optimization library (brings defusedxml)

The core script uses only Python Standard Library modules:
- No need for external image libraries
- Uses system's `caesiumclt.exe` for image compression
- Handles PPTX files using only built-in zipfile module

### Development Dependencies (for testing/development)
See `requirements-dev.txt`:
- `pytest==9.0.3` - Testing framework
- `pytest-cov==7.1.0` - Coverage reporting
- Plus all runtime dependencies

### Managing Dependencies

**Update packages:**
```bash
.\.venv\Scripts\pip install --upgrade -r requirements.txt
```

**Add new package:**
```bash
.\.venv\Scripts\pip install package_name
.\.venv\Scripts\pip freeze > requirements.txt
```

**For development:**
```bash
.\.venv\Scripts\pip install -r requirements-dev.txt
```

---

## Troubleshooting

### Development Setup Issues

**Problem:** "Python not found"
- **Solution:** Run `.\install_and_run.bat` which will download and setup Python

**Problem:** "svg_polish not found"
- **Solution:** Run with `--debug` flag to see installation details
- Or manually: `.\.venv\Scripts\pip install svg-polish`

### PyInstaller Build Issues

**Problem:** Build takes too long
- **Solution:** First build is slower due to PyInstaller analysis. Subsequent builds are faster.

**Problem:** .exe won't run
- **Solution:** Ensure `caesiumclt.exe` is in the same directory or system PATH

**Problem:** "PyInstaller not installed"
- **Solution:** Run `build.bat` again - it will auto-install PyInstaller

---

## Technical Comparison

| Aspect | Embedded Python | PyInstaller | Hybrid |
|--------|-----------------|-------------|--------|
| **Installation** | Auto (via batch) | None (single .exe) | Mixed |
| **Disk Space** | ~50 MB | ~100-150 MB | Both available |
| **Execution Speed** | Fast | Fast | Fast |
| **Debuggability** | Excellent | Difficult | Excellent (dev) |
| **Distribution** | Manual setup | Just .exe | Just .exe (users) |
| **Development** | Quick iteration | Requires rebuild | Quick iteration |

---

## Recommended Workflow

### For You (Developer)
```
1. Daily Development:
   - Use: .\install_and_run.bat --debug
   - Edit code in VS Code
   - Test with pytest
   - Use debugger with F5

2. Before Release:
   - Run: .\build.bat
   - Test: .\dist\pptx-image-compress.exe
   - Package and distribute
```

### For End Users
```
1. First Time:
   - Download pptx-image-compress.exe
   - Download run.bat (optional)
   - Download caesiumclt.exe (if image compression needed)
   
2. Usage:
   - Double-click run.bat
   - Or: pptx-image-compress.exe -i input.pptx -o output.pptx
```

---

## Next Steps

1. **Test Embedded Python Setup:**
   ```bash
   .\install_and_run.bat --debug -i test.pptx -o test_output.pptx
   ```

2. **Build Portable Distribution:**
   ```bash
   .\build.bat
   ```

3. **Test the Executable:**
   ```bash
   .\dist\pptx-image-compress.exe -h
   ```

4. **Check Generated Files:**
   - `dist/pptx-image-compress.exe` - Main executable
   - `dist/run.bat` - Batch wrapper

---

## Support & Maintenance

- Keep Python version updated for security
- Update dependencies: `pip install --upgrade -r requirements.txt`
- Rebuild .exe when updating dependencies: `.\build.bat`
- Test both approaches before major updates