289 lines
7.6 KiB
Markdown
289 lines
7.6 KiB
Markdown
# 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
|