pptx.errors

Typed safe-refusal exceptions for paper-pptx APIs.

A PaperRefusal means the operation declined to run and the document — the in-memory XML tree and any file on disk — is exactly as it was. Refusals are a success mode: the API judged the requested change unsafe or unsupported and said so instead of guessing. Callers can therefore catch PaperRefusal distinctly from bugs; programmer errors (bad argument types or values) remain TypeError/ValueError as usual.

Paper mutating APIs run inside a package transaction: whatever the operation touched is restored if it refuses, and the deck-wide check runs before anything commits. Some APIs (apply_footers, append_deck, import_slide, clone) additionally validate in full before touching anything. Either way a refusal never leaves a partial edit behind.