Metadata-Version: 2.4
Name: pptx-refresh
Version: 0.1.1
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
Requires-Dist: tomli<3,>=2.4.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 command as an isolated user tool so it can run from any project:

```bash
pipx install pptx-refresh
pptx-refresh --version
pptx-refresh doctor
```

Repository contributors may continue to use `make install` or `make setup`.

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.

## Mark content in PowerPoint

Select an ungrouped picture, text box, or ordinary shape and open its Alt Text.
For a rendered TeX table, an ungrouped native PowerPoint table is also a valid
placeholder. Put a relative source path in Alt Text with the exact,
case-sensitive `AUTO:` prefix:

```text
AUTO: figures/main-results.pdf
```

Optional settings go on following lines:

```text
AUTO: figures/main-results.pdf
fit=preserve
aspect_ratio_change=warn
```

Alt Text is the recommended declaration location. For a text box or ordinary
shape, you may instead type the same declaration as visible object text.
Existing legacy presentations that use an `AUTO:` Selection Pane name with
metadata in Alt Text, without a second `AUTO:` prefix, remain supported. For a
new Alt Text or visible declaration, the first nonblank line must begin with
`AUTO:`, and optional settings follow on separate lines. Do not put `AUTO:` in
more than one location on the same object.

The source PowerPoint keeps the declaration editable. The generated PowerPoint
embeds the refreshed picture and converts placeholder shapes or tables as
needed.

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.

## Initialize an existing slide project

Projects may use their existing directory structure. A common layout is:

```text
3_slides/
├── source/
│   └── presentation.pptx
├── input/
│   ├── figures/main-results.pdf
│   └── tables/summary-results.tex
└── output/
```

Create a project configuration once:

```bash
pptx-refresh init 3_slides
```

When `source/` contains exactly one `.pptx`, `init` writes:

```toml
# 3_slides/pptx-refresh.toml
presentation = "source/presentation.pptx"
input_dir = "input"
output_dir = "output/pptx-refresh"
dpi = 300
```

The recommended structure keeps one primary presentation in `source/`. If
`source/` contains more than one `.pptx`, select the intended file during the
one-time initialization:

```bash
pptx-refresh init 3_slides --presentation source/deck-a.pptx
```

That choice is saved as `presentation` in `pptx-refresh.toml`. It persists
across terminal sessions, so subsequent runs do not need `--presentation`:

```bash
cd 3_slides
pptx-refresh validate .
pptx-refresh build .
```

Paths in this file are always resolved from the configuration directory, not
from the shell's current directory. `init` does not move or rewrite project
files. Use `--presentation`, `--input-dir`, or `--output-dir` when discovery
needs an explicit choice.

## Validate and build from anywhere

```bash
pptx-refresh validate /path/to/project/3_slides
pptx-refresh build /path/to/project/3_slides
```

An explicit configuration file is equivalent:

```bash
pptx-refresh build --config /path/to/project/3_slides/pptx-refresh.toml
```

Direct file-oriented commands remain available for scripts that do not want a
configuration file:

```bash
pptx-refresh build 3_slides/source/presentation.pptx \
  --input-dir ../input \
  --output-dir ../output
```

Declarations are relative to the selected input directory. The example
object's Alt Text therefore uses `AUTO: figures/main-results.pdf`. Do not
prefix the declaration with the input directory itself.

A selected input directory — typed as `--input-dir` or read from
`pptx-refresh.toml` — is a trusted logical namespace. File and directory
symlinks declared beneath it may resolve to existing regular files elsewhere,
which supports inputs linked from Dropbox or other modules. Sources may not
resolve into the active publication-owned output paths. When no input
directory is selected, 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 Alt Text or visible `AUTO:` declaration,
the configured input directory, and every symlink target. Build failures leave
the source presentation unchanged.

## License

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