pptx-image-compress/PACKAGING_GUIDE.md

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

# 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

# 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:

.\.venv\Scripts\pip install --upgrade -r requirements.txt

Add new package:

.\.venv\Scripts\pip install package_name
.\.venv\Scripts\pip freeze > requirements.txt

For development:

.\.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:

   .\install_and_run.bat --debug -i test.pptx -o test_output.pptx
   

2. Build Portable Distribution:

   .\build.bat
   

3. Test the Executable:

   .\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