[Epic] Slide Rendering & Export — PDF, PNG/JPG, MP4 (shell-out)

[MHoroszowski]

Problem

Slide-to-image and slide-to-PDF rendering is the most-asked feature outside python-pptx's stated scope. scanny/python-pptx#584 (PDF, 4c), scanny/python-pptx#963 (slide as image, 2c), scanny/python-pptx#1049 (PPT → MP4, 8c), scanny/python-pptx#673 (chart as picture). Pure-Python rendering of OOXML is essentially infeasible (the layout / fonts / shape-effects pipeline is enormous), but every notebook user wants thumbnail previews and every API service wants PDF export. The pragmatic answer is a subprocess shell-out to LibreOffice's headless mode (soffice --headless --convert-to ...) or unoconv, with a documented Windows path that uses PowerPoint COM via pywin32. This epic ships the wrappers, documents the dependencies clearly, and labels everything prior-art:shellout so users can opt out.

Sub-features

• pres.export_pdf(path, engine="auto"|"libreoffice"|"powerpoint"|"unoconv") — wraps soffice --headless --convert-to pdf (Linux/Mac) or PowerPoint COM (Windows)
• slide.export_image(path, format="png"|"jpg"|"svg", dpi=96) — single-slide thumbnail
• pres.export_images(directory, format="png", dpi=96) — all-slides batch
• chart.export_image(path, format="png"|"svg") — single chart render
• pres.export_video(path, format="mp4", duration_per_slide=5) — wraps PowerPoint's "Create a Video" if available, falls back to ffmpeg-stitched images
• Docs page: dependency matrix (which engines support which OS, install instructions for each), with prominent "this requires external software" warning
• Engine auto-detection: probe for soffice, unoconv, pywin32+PowerPoint at module-load and pick the best available
• Fail clearly: if no engine available, raise RenderEngineNotAvailableError with install hints, never silently fall back to a degraded path

Prior art

• Open PRs: none directly.
• Forks:
  • natter1/python_pptx_interface (PyPI python-pptx-interface) — implements PDF/PNG export but only via Windows + PowerPoint COM (pywin32). Reference for Windows path.
• Commercial alternatives (for reference, NOT cherry-pick targets — proprietary): aspose-slides and spire-presentation both ship native PDF/PNG/SVG/MP4 rendering. They're worth knowing about as the "buy-it" alternative for users who can't tolerate a subprocess.
• User issues this would close: #358, #438, #577, #584, #673, #885, #963, #1049, #1059.
• External tools: LibreOffice soffice --headless; unoconv (deprecated upstream but widely deployed); pywin32 + PowerPoint COM.
• Code paths: new src/pptx/export/ subpackage with one module per engine, plus an engines.py for autodetect.

Acceptance criteria

• pres.export_pdf("out.pdf") on Linux with soffice installed produces a PDF matching PowerPoint's PDF output for the same source within ±5% layout error.
• slide.export_image("out.png", dpi=192) produces a 1.5MB+ PNG at retina resolution.
• Documented engine matrix: which engines work on which OS.
• 8+ behave scenarios across the wrapped engines.
• Clear error path with install hints when no engine is found.
• All export functions explicitly opt-out-able — none are imported into the default pptx namespace, only via from pptx.export import ....

Effort: M (with shell-out)

Without shell-out: would be Multi-quarter L+. With shell-out: Medium — the work is mostly subprocess wrapping, engine probing, and documentation.

Labels

prior-art:shellout, area:export. Explicitly user-flagged in this epic that no pure-Python rendering is in scope; this is the shell-out wrapper.