Metadata-Version: 2.4
Name: pptx-refresh
Version: 0.1.0
Summary: Refresh declared PowerPoint figures and rendered tables from project sources.
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/pptx-refresh/
Keywords: powerpoint,pptx,presentations,figures,tables
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Office Suites
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml<7,>=6.1.1
Requires-Dist: Pillow<13,>=12.3
Requires-Dist: pypdfium2<6,>=5.12.1
Dynamic: license-file

# pptx-refresh

`pptx-refresh` updates selected figures and rendered TeX tables in a PowerPoint
presentation without changing the rest of the deck. You continue editing text,
layout, and styling in PowerPoint; the generated presentation embeds refreshed
assets and remains portable.

## Requirements

- macOS with a logged-in desktop session
- Python 3.10 or newer
- Microsoft 365 PowerPoint, installed and licensed
- permission for the calling terminal application to control PowerPoint
- `latexmk` and `pdflatex` only when rendering TeX tables

Supported figure sources are PNG, JPEG, and PDF. A PDF may use a same-named PNG
companion for deterministic rendering.

## Install

Install the released package in an isolated environment:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install "pptx-refresh==0.1.0"
.venv/bin/pptx-refresh --version
.venv/bin/pptx-refresh doctor
```

The first `doctor` run may trigger a macOS Automation prompt. Grant the calling
terminal access to Microsoft PowerPoint under **System Settings > Privacy &
Security > Automation**, then run `doctor` again.

## Declare managed objects

In PowerPoint, select an ungrouped picture, ordinary shape, or supported table
placeholder. Give it a unique Selection Pane name beginning with `AUTO:` and
put the source path on the first line of Alt Text.

```text
Selection Pane name:
AUTO:figures/main-results.pdf

Alt Text:
figures/main-results.pdf
```

Source paths must be relative. Absolute paths, `..`, empty path segments,
directories, missing files, and unsupported extensions are rejected. Save and
close the source presentation before validating or building it.

## Standalone projects

When `--input-dir` is omitted, source paths are relative to the presentation's
directory:

```text
slides-project/
├── presentation.pptx
├── figures/
│   └── main-results.pdf
└── tables/
    └── summary-results.tex
```

```bash
pptx-refresh validate presentation.pptx
pptx-refresh build presentation.pptx
```

The default output directory is `output/` beside the presentation.

## Projects with a separate input directory

Use `--input-dir` when the presentation lives under `source/` and its declared
assets live under `input/`:

```text
slides-module/
├── source/
│   └── main.pptx
├── input/
│   └── figures/result.pdf
└── output/
```

From `source/`, run:

```bash
pptx-refresh validate main.pptx \
    --input-dir ../input \
    --output-dir ../output/pptx-refresh

pptx-refresh build main.pptx \
    --input-dir ../input \
    --output-dir ../output/pptx-refresh
```

Relative input and output directories are resolved from the presentation's
directory. Alt Text remains relative to the selected input directory, so the
example deck declares `figures/result.pdf`, not `input/figures/result.pdf`.

An explicit input directory is a trusted logical namespace. File and directory
symlinks declared beneath it may resolve to existing regular files elsewhere,
which supports generated-input workflows. Sources may not resolve into the
active publication-owned output paths. When `--input-dir` is omitted, the
stricter standalone policy requires symlink targets to remain inside the
presentation directory. The same rules apply to PDF companion PNGs.

## Outputs and exit status

A successful build publishes an atomic bundle without overwriting the source:

```text
output/
├── presentation_updated.pptx
├── presentation_updated.pdf
└── report/
    ├── index.html
    ├── report.json
    ├── previews/
    └── diffs/
```

Exit status `0` means the bundle was published without review items. Status `2`
also means publication succeeded, but the report recommends review. Any other
status is a failure.

Open `report/index.html` after each build and review the refreshed presentation
and exported PDF before circulating them.

## Troubleshooting

Run diagnostics with:

```bash
pptx-refresh doctor --json
```

If PowerPoint is unavailable, confirm that it is installed, licensed, and not
blocked by macOS Automation permissions. If a presentation is reported as open,
save and close it in PowerPoint before retrying. TeX-table errors require both
`latexmk` and `pdflatex`; figure-only presentations do not require TeX.

For path errors, check the first Alt Text line, the selected `--input-dir`, and
every symlink target. Build failures leave the source presentation unchanged.

## License

`pptx-refresh` is distributed under the MIT License.
