Metadata-Version: 2.4
Name: pptxforge
Version: 0.1.0
Summary: Generate beautiful PowerPoint decks programmatically with native 3D models, cinematic transitions, and themed layouts.
Author-email: pptxforge maintainer <you@example.com>
License: MIT License
        
        Copyright (c) 2026 [USER_NAME_PLACEHOLDER]
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/GA16-24/pptxforge
Project-URL: Repository, https://github.com/GA16-24/pptxforge
Project-URL: Issues, https://github.com/GA16-24/pptxforge/issues
Project-URL: Changelog, https://github.com/GA16-24/pptxforge/blob/main/CHANGELOG.md
Keywords: powerpoint,pptx,presentation,deck,3d,morph,cinematic,ooxml,office-addins,slides
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-pptx<2.0,>=1.0.2
Requires-Dist: lxml>=5.0
Requires-Dist: pydantic>=2.6
Requires-Dist: typing-extensions>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.0
Requires-Dist: Pillow>=10.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# pptxforge

> Generate beautiful PowerPoint decks programmatically — with native 3D models, cinematic transitions, and themed layouts.

[![PyPI version](https://img.shields.io/pypi/v/pptxforge.svg)](https://pypi.org/project/pptxforge/)
[![Python versions](https://img.shields.io/pypi/pyversions/pptxforge.svg)](https://pypi.org/project/pptxforge/)
[![License: MIT](https://img.shields.io/pypi/l/pptxforge.svg)](LICENSE)
[![CI](https://github.com/GA16-24/pptxforge/actions/workflows/ci.yml/badge.svg)](https://github.com/GA16-24/pptxforge/actions/workflows/ci.yml)

![Hero](docs/screenshots/hero-citrem-title.png)

## Why pptxforge?

Most Python tools for PowerPoint focus on filling in templates. **pptxforge** focuses on producing *beautiful* decks: 10 themed designs, native embedded 3D models that PowerPoint can morph between, four cinematic transition helpers, and content-aware visual primitives that make slides look hand-designed.

| Themed primitives that stay aligned | Repulsion-based label scales | Cinematic morph helpers |
| :---: | :---: | :---: |
| ![CardGrid + StatRow](docs/screenshots/cardgrid-callout.png) | ![LabeledScale](docs/screenshots/labeled-scale.png) | ![Cinematic helpers cover](docs/screenshots/cinematic-cover.png) |

## Install

```bash
pip install pptxforge
```

Python 3.10 or later. Generated `.pptx` files open in PowerPoint Desktop, PowerPoint Online, Keynote, and LibreOffice Impress.

## Quickstart

```python
from pptxforge import Card, CardGrid, Deck, themes

deck = Deck(theme=themes.MIDNIGHT_EXECUTIVE, title="Hello, world")

deck.add_title_slide(
    title="Hello, pptxforge",
    subtitle="Your first deck in six lines of Python",
)

deck.add_content_slide(
    title="Three things pptxforge does",
    layout=CardGrid(
        [
            Card(number="1", title="Themes", body="10 production themes, light and dark."),
            Card(number="2", title="Native 3D", body="Embed GLB models PowerPoint can morph between."),
            Card(number="3", title="Cinematic", body="Zoom, pan, reveal, and shape-transform helpers."),
        ],
        columns=3,
    ),
)

deck.save("hello-world/")
```

That's it. You now have `hello-world/deck.pptx`. Open it in PowerPoint.

A complete runnable version lives in [`examples/hello_world/build.py`](examples/hello_world/build.py).

## Features

- **10 themes** — Pacific Deep, Midnight Executive, Forest Moss, Coral Energy, Slate Minimalist, Royal Plum, Monochrome Ink, Amber Editorial, Sunrise Citrus, Berry Bold.
- **Native 3D models** — embed GLB files, with auto-fit cameras and morph between camera angles using PowerPoint's native morph engine.
- **Cinematic transitions** — `cinematic_zoom`, `prezi_canvas`, `number_reveal`, `shape_transform`, plus `model3d_flight` for multi-waypoint camera tours.
- **Visual primitives** — `LabeledScale` (with collision-avoiding labels), `CardGrid`, `Callout`, `StatRow`.
- **Image fetching** — `fetch_image("modern coffee shop")` works zero-config via Wikimedia Commons; Unsplash and Pexels supported with optional API keys.
- **Layout-variation validator** — catches three-in-a-row identical layouts and other anti-patterns at build time.
- **3D annotations** — `ModelAnnotation` with auto-projected leader lines that point at the right pixel from any camera angle.

## Examples

The [`examples/`](examples/) directory has runnable scripts demonstrating each feature:

| Example | What it shows |
| --- | --- |
| [`hello_world/build.py`](examples/hello_world/build.py) | Minimal deck, no external assets |
| [`cinematic/build.py`](examples/cinematic/build.py) | All four cinematic helpers in one deck |
| [`cinematic_flight/build.py`](examples/cinematic_flight/build.py) | 5-waypoint helmet camera tour |
| [`transitions/build.py`](examples/transitions/build.py) | Every transition type |
| [`fetch_image_quickstart.py`](examples/fetch_image_quickstart.py) | Zero-config image fetching via Wikimedia |
| [`citrem_mayonnaise/build.py`](examples/citrem_mayonnaise/build.py) | Full real-world demo with 3D molecules |

Run any of them from the repo root:

```bash
python examples/hello_world/build.py
```

## Image fetching

`pptxforge.images.fetch_image("Eiffel Tower")` works on first install — Wikimedia Commons is the zero-config default (no key, no signup, public-domain catalogue). For higher-quality photography:

```python
from pptxforge.images import setup_wizard
setup_wizard("unsplash")   # opens browser, prompts for the key, takes ~3 minutes
```

`fetch_image` reads keys from the env first, then from the config file the wizard writes (`%APPDATA%\pptxforge\config.toml` on Windows / `~/.config/pptxforge/config.toml` on POSIX). With any key set, `source="auto"` automatically prefers the paid source over Wikimedia.

## Documentation

- **[SKILL.md](skill/SKILL.md)** — comprehensive usage guide with the decision tree for picking primitives. Originally written for AI coding agents; useful for humans too.
- **[ARCHITECTURE.md](ARCHITECTURE.md)** — public-API contract, module layout, data flow, extension points.
- **[DECISIONS.md](DECISIONS.md)** — dated log of non-obvious technical choices and tradeoffs.

## How it works

pptxforge wraps `python-pptx` with a higher-level API focused on visual quality. It generates standard `.pptx` files that any major presentation tool can open.

3D models are embedded as native PowerPoint 3D objects (not images). Morph transitions between 3D slides use PowerPoint's native morph engine, with shape pairing keyed by `a16:creationId` so the model interpolates smoothly across waypoints. Image fetching uses the Wikimedia Commons API by default; Unsplash and Pexels are supported with optional API keys.

## Limitations

- PowerPoint Online and LibreOffice Impress render PowerPoint's native 3D differently than Desktop — Desktop is the gold target.
- Some PowerPoint features (notably easing on transitions) aren't exposed because the OOXML spec doesn't expose them.
- The library focuses on programmatic generation; it isn't an editor.
- Speaker notes are supported (`notes=` on every `add_*_slide`) but not generated automatically.

## Contributing

Issues and pull requests welcome at [github.com/GA16-24/pptxforge](https://github.com/GA16-24/pptxforge).

To set up a development checkout:

```bash
git clone https://github.com/GA16-24/pptxforge
cd pptxforge
python -m pip install -e '.[dev]'

# All four CI gates:
ruff check src tests
ruff format --check src tests
mypy
pytest -n auto
```

## License

MIT — see [LICENSE](LICENSE).
