ppt2pptx 0.3.1__tar.gz

ppt2pptx-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ppt2pptx contributors
+
+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.

ppt2pptx-0.3.1/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: ppt2pptx
+Version: 0.3.1
+Summary: A pure-Python converter from legacy PowerPoint .ppt files to .pptx
+Author: ppt2pptx contributors
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ppt2pptx
+
+`ppt2pptx` converts Microsoft PowerPoint 97–2003 binary `.ppt` presentations
+to Office Open XML `.pptx` using only the Python standard library. It reads
+the CFB/OLE container and PowerPoint record stream directly; it never launches
+PowerPoint, LibreOffice, COM, or a conversion service.
+
+The project is useful for a broad set of real presentations, but it is not a
+complete implementation of every legacy PowerPoint feature. Unsupported or
+lossy content is diagnosed instead of being silently presented as fully
+faithful.
+
+## Highlights
+
+- Opens RC4 CryptoAPI password-protected presentations when a password is supplied.
+- Preserves normal slide order and dimensions without mistaking masters or notes for slides.
+- Preserves hidden-slide state so excluded slides remain hidden during slide shows.
+- Restores positioned editable text, fonts, sizes, colors, bold/italic/underline,
+  paragraph alignment, bullets, rotation, flips, and safe external hyperlinks.
+- Preserves PNG, JPEG, GIF, TIFF, EMF, WMF, and PICT media, including cropping,
+  position, rotation, and flips when present.
+- Recreates common editable shapes, solid/gradient backgrounds, comments, speaker
+  notes, slide numbers, dates, headers, and footers.
+- Copies common core properties such as title, author, keywords, and timestamps.
+- Supports atomic single-file and recursive batch conversion with JSON diagnostics.
+
+## Usage
+
+```console
+python -m pip install ppt2pptx
+ppt2pptx presentation.ppt
+ppt2pptx presentation.ppt -o presentation.pptx --report report.json
+ppt2pptx protected.ppt --password-file password.txt
+ppt2pptx inspect presentation.ppt --json
+ppt2pptx batch input-directory -o output-directory --recursive --report batch.json
+```
+
+The input is always read-only and output files are written atomically.  The
+converter refuses to overwrite its input.
+
+The Python API accepts the password directly:
+
+```python
+from ppt2pptx import convert
+
+result = convert("protected.ppt", "protected.pptx", password="secret")
+print(result.report.to_dict())
+```
+
+## Current limitations
+
+Charts, SmartArt, animation timelines, audio/video playback, embedded OLE
+objects, and complex freeform or grouped master geometry remain incomplete.
+Solid and common gradient backgrounds are retained, while advanced fills and
+effects may be approximated. PICT data is preserved, but rendering depends on
+the PPTX consumer. PowerPoint 95 and earlier files use a different record
+format and are deliberately rejected with a clear error.
+
+## Development
+
+```console
+python -m pip install -e .
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+```
+
+The converter itself does not depend on LibreOffice. The real-file regression
+script may use LibreOffice only to verify that generated packages render:
+
+```console
+PYTHONPATH=src python scripts/validate_real_files.py tests/real_samples \
+  -o tests/real_output --render --password hello
+```
+
+## Specification
+
+- [MS-PPT: PowerPoint Binary File Format](https://learn.microsoft.com/openspecs/office_file_formats/ms-ppt/)
+- [MS-CFB: Compound File Binary File Format](https://learn.microsoft.com/openspecs/windows_protocols/ms-cfb/)
+- [MS-ODRAW: Office Drawing Binary File Format](https://learn.microsoft.com/openspecs/office_file_formats/ms-odraw/)

ppt2pptx-0.3.1/README.md

@@ -0,0 +1,79 @@
+# ppt2pptx
+
+`ppt2pptx` converts Microsoft PowerPoint 97–2003 binary `.ppt` presentations
+to Office Open XML `.pptx` using only the Python standard library. It reads
+the CFB/OLE container and PowerPoint record stream directly; it never launches
+PowerPoint, LibreOffice, COM, or a conversion service.
+
+The project is useful for a broad set of real presentations, but it is not a
+complete implementation of every legacy PowerPoint feature. Unsupported or
+lossy content is diagnosed instead of being silently presented as fully
+faithful.
+
+## Highlights
+
+- Opens RC4 CryptoAPI password-protected presentations when a password is supplied.
+- Preserves normal slide order and dimensions without mistaking masters or notes for slides.
+- Preserves hidden-slide state so excluded slides remain hidden during slide shows.
+- Restores positioned editable text, fonts, sizes, colors, bold/italic/underline,
+  paragraph alignment, bullets, rotation, flips, and safe external hyperlinks.
+- Preserves PNG, JPEG, GIF, TIFF, EMF, WMF, and PICT media, including cropping,
+  position, rotation, and flips when present.
+- Recreates common editable shapes, solid/gradient backgrounds, comments, speaker
+  notes, slide numbers, dates, headers, and footers.
+- Copies common core properties such as title, author, keywords, and timestamps.
+- Supports atomic single-file and recursive batch conversion with JSON diagnostics.
+
+## Usage
+
+```console
+python -m pip install ppt2pptx
+ppt2pptx presentation.ppt
+ppt2pptx presentation.ppt -o presentation.pptx --report report.json
+ppt2pptx protected.ppt --password-file password.txt
+ppt2pptx inspect presentation.ppt --json
+ppt2pptx batch input-directory -o output-directory --recursive --report batch.json
+```
+
+The input is always read-only and output files are written atomically.  The
+converter refuses to overwrite its input.
+
+The Python API accepts the password directly:
+
+```python
+from ppt2pptx import convert
+
+result = convert("protected.ppt", "protected.pptx", password="secret")
+print(result.report.to_dict())
+```
+
+## Current limitations
+
+Charts, SmartArt, animation timelines, audio/video playback, embedded OLE
+objects, and complex freeform or grouped master geometry remain incomplete.
+Solid and common gradient backgrounds are retained, while advanced fills and
+effects may be approximated. PICT data is preserved, but rendering depends on
+the PPTX consumer. PowerPoint 95 and earlier files use a different record
+format and are deliberately rejected with a clear error.
+
+## Development
+
+```console
+python -m pip install -e .
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+```
+
+The converter itself does not depend on LibreOffice. The real-file regression
+script may use LibreOffice only to verify that generated packages render:
+
+```console
+PYTHONPATH=src python scripts/validate_real_files.py tests/real_samples \
+  -o tests/real_output --render --password hello
+```
+
+## Specification
+
+- [MS-PPT: PowerPoint Binary File Format](https://learn.microsoft.com/openspecs/office_file_formats/ms-ppt/)
+- [MS-CFB: Compound File Binary File Format](https://learn.microsoft.com/openspecs/windows_protocols/ms-cfb/)
+- [MS-ODRAW: Office Drawing Binary File Format](https://learn.microsoft.com/openspecs/office_file_formats/ms-odraw/)

ppt2pptx-0.3.1/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ppt2pptx"
+version = "0.3.1"
+description = "A pure-Python converter from legacy PowerPoint .ppt files to .pptx"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "ppt2pptx contributors"}]
+dependencies = []
+
+[project.scripts]
+ppt2pptx = "ppt2pptx.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ppt2pptx-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ppt2pptx-0.3.1/src/ppt2pptx/__init__.py

@@ -0,0 +1,6 @@
+"""Public API for ppt2pptx."""
+
+from .converter import ConversionResult, convert, inspect_ppt
+
+__all__ = ["ConversionResult", "convert", "inspect_ppt"]
+__version__ = "0.3.1"

ppt2pptx-0.3.1/src/ppt2pptx/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

ppt2pptx-0.3.1/src/ppt2pptx/cfb.py

@@ -0,0 +1,115 @@
+"""Small bounded reader for CFB/OLE compound files used by legacy PPT."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import struct
+
+from .errors import InvalidPpt
+
+FREE, END, FAT, DIF = 0xFFFFFFFF, 0xFFFFFFFE, 0xFFFFFFFD, 0xFFFFFFFC
+
+@dataclass(frozen=True, slots=True)
+class Limits:
+    max_input_bytes: int = 512 * 1024 * 1024
+    max_stream_bytes: int = 256 * 1024 * 1024
+
+class CompoundFile:
+    def __init__(self, data: bytes, limits: Limits | None = None) -> None:
+        self.limits = limits or Limits()
+        if len(data) > self.limits.max_input_bytes or len(data) < 512:
+            raise InvalidPpt("invalid or oversized compound file")
+        if data[:8] != b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1":
+            raise InvalidPpt("not a Compound File Binary container")
+        self.data = data
+        major = struct.unpack_from("<H", data, 26)[0]
+        self.sector_size = 512 if major == 3 else 4096 if major == 4 else 0
+        if not self.sector_size or len(data) < self.sector_size:
+            raise InvalidPpt("unsupported compound file version")
+        self.mini_sector_size = 64
+        self.mini_cutoff = struct.unpack_from("<I", data, 56)[0]
+        self.first_dir = struct.unpack_from("<I", data, 48)[0]
+        self.first_mini_fat = struct.unpack_from("<I", data, 60)[0]
+        self.num_mini_fat = struct.unpack_from("<I", data, 64)[0]
+        self._sectors = (len(data) - self.sector_size) // self.sector_size
+        self.fat = self._load_fat()
+        self.entries = self._read_directory()
+        self.by_name = {name.casefold(): entry for name, entry in self.entries.items()}
+        self.mini_fat = self._read_chain_values(self.first_mini_fat, self.num_mini_fat)
+        self._mini_stream: bytes | None = None
+
+    @classmethod
+    def from_path(cls, path: str | Path, limits: Limits | None = None) -> "CompoundFile":
+        p = Path(path)
+        actual = limits or Limits()
+        if p.stat().st_size > actual.max_input_bytes:
+            raise InvalidPpt("input exceeds configured size limit")
+        return cls(p.read_bytes(), actual)
+
+    def _sector(self, index: int) -> bytes:
+        if index >= self._sectors or index in (FREE, END, FAT, DIF):
+            raise InvalidPpt("compound file sector reference is invalid")
+        start = (index + 1) * self.sector_size
+        return self.data[start:start + self.sector_size]
+
+    def _load_fat(self) -> tuple[int, ...]:
+        count = struct.unpack_from("<I", self.data, 44)[0]
+        ids = [x for x in struct.unpack_from("<109I", self.data, 76) if x != FREE]
+        next_difat, difat_count = struct.unpack_from("<II", self.data, 68)
+        for _ in range(difat_count):
+            block = self._sector(next_difat)
+            values = struct.unpack("<%dI" % (self.sector_size // 4), block)
+            ids.extend(x for x in values[:-1] if x != FREE)
+            next_difat = values[-1]
+        if len(ids) < count:
+            raise InvalidPpt("compound file FAT is truncated")
+        values: list[int] = []
+        for index in ids[:count]: values.extend(struct.unpack("<%dI" % (self.sector_size // 4), self._sector(index)))
+        return tuple(values)
+
+    def _chain(self, start: int, table: tuple[int, ...], limit: int | None = None) -> list[int]:
+        result, seen, current = [], set(), start
+        while current != END:
+            if current in seen or current >= len(table) or current in (FREE, FAT, DIF):
+                raise InvalidPpt("compound file sector chain is invalid")
+            seen.add(current); result.append(current)
+            if len(result) > (limit or len(table) + 1): raise InvalidPpt("compound file sector chain is unbounded")
+            current = table[current]
+        return result
+
+    def _read_chain_values(self, start: int, declared: int) -> tuple[int, ...]:
+        if not declared: return ()
+        raw = b"".join(self._sector(i) for i in self._chain(start, self.fat, declared))
+        return struct.unpack("<%dI" % (len(raw) // 4), raw)
+
+    def _read_directory(self) -> dict[str, tuple[int, int, int]]:
+        raw = b"".join(self._sector(i) for i in self._chain(self.first_dir, self.fat))
+        entries: list[tuple[str, int, int, int]] = []
+        for offset in range(0, len(raw) - 127, 128):
+            name_len = struct.unpack_from("<H", raw, offset + 64)[0]
+            kind = raw[offset + 66]
+            if kind not in (2, 5) or name_len < 2 or name_len > 64: continue
+            name = raw[offset:offset + name_len - 2].decode("utf-16le", "replace")
+            start, size = struct.unpack_from("<IQ", raw, offset + 116)
+            entries.append((name, kind, start, size))
+        return {name: (kind, start, size) for name, kind, start, size in entries}
+
+    def open_stream(self, name: str) -> bytes:
+        entry = self.by_name.get(name.casefold())
+        if entry is None: raise InvalidPpt(f"required stream is missing: {name}")
+        kind, start, size = entry
+        if kind != 2 or size > self.limits.max_stream_bytes: raise InvalidPpt(f"invalid stream: {name}")
+        if not size: return b""
+        if size < self.mini_cutoff:
+            if self._mini_stream is None:
+                root = next((x for x in self.entries.values() if x[0] == 5), None)
+                if root is None: raise InvalidPpt("compound file root storage is missing")
+                self._mini_stream = self._read_regular(root[1], root[2])
+            chunks = []
+            for idx in self._chain(start, self.mini_fat):
+                pos = idx * self.mini_sector_size; chunks.append(self._mini_stream[pos:pos+self.mini_sector_size])
+            return b"".join(chunks)[:size]
+        return self._read_regular(start, size)
+
+    def _read_regular(self, start: int, size: int) -> bytes:
+        return b"".join(self._sector(i) for i in self._chain(start, self.fat))[:size]

ppt2pptx-0.3.1/src/ppt2pptx/cli.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from . import __version__
+from .cfb import Limits
+from .converter import convert, inspect_ppt
+from .diagnostics import write_json_file
+from .errors import Ppt2PptxError
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("value must be positive")
+    return parsed
+
+def _common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--max-input-bytes", type=_positive_int, default=Limits().max_input_bytes)
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--password", help="password for an encrypted presentation")
+    group.add_argument("--password-file", type=Path, help="UTF-8 file containing the password")
+
+def _password(args: argparse.Namespace) -> str | None:
+    if args.password is not None:
+        return args.password
+    if args.password_file is None:
+        return None
+    if args.password_file.stat().st_size > 4096:
+        raise OSError("password file exceeds 4096 bytes")
+    return args.password_file.read_text(encoding="utf-8").removesuffix("\n").removesuffix("\r")
+
+def _conversion_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ppt2pptx", description="Convert PowerPoint 97–2003 .ppt files to .pptx")
+    parser.add_argument("input", type=Path)
+    parser.add_argument("-o", "--output", type=Path)
+    parser.add_argument("--report", type=Path)
+    parser.add_argument("--version", action="version", version=__version__)
+    _common(parser)
+    return parser
+
+def _inspection_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ppt2pptx inspect", description="Inspect slides and editable text without converting")
+    parser.add_argument("input", type=Path)
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    _common(parser)
+    return parser
+
+def _batch_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ppt2pptx batch", description="Convert a directory of PowerPoint 97–2003 .ppt files")
+    parser.add_argument("input", type=Path)
+    parser.add_argument("-o", "--output", type=Path, required=True)
+    parser.add_argument("--recursive", action="store_true")
+    parser.add_argument("--report", type=Path)
+    _common(parser)
+    return parser
+
+def _same_path(left: Path, right: Path) -> bool:
+    return left.resolve().as_posix().casefold() == right.resolve().as_posix().casefold()
+
+def _batch_sources(root: Path, recursive: bool) -> list[Path]:
+    iterator = root.rglob("*") if recursive else root.iterdir()
+    return sorted(
+        (path for path in iterator if path.is_file() and path.suffix.casefold() == ".ppt" and not path.name.startswith("~$")),
+        key=lambda path: path.relative_to(root).as_posix().casefold(),
+    )
+
+def _run_batch(args: argparse.Namespace) -> int:
+    source_root, output_root = args.input, args.output
+    if not source_root.is_dir():
+        print(f"ppt2pptx: error: batch input is not a directory: {source_root}", file=sys.stderr)
+        return 2
+    sources = _batch_sources(source_root, args.recursive)
+    password = _password(args)
+    if not sources:
+        print(f"ppt2pptx: error: no .ppt files found in {source_root}", file=sys.stderr)
+        return 2
+    destinations = [output_root / source.relative_to(source_root).with_suffix(".pptx") for source in sources]
+    if args.report and any(_same_path(args.report, path) for path in (*sources, *destinations)):
+        print("ppt2pptx: error: report path would overwrite an input or output", file=sys.stderr)
+        return 2
+    results: list[dict[str, object]] = []
+    succeeded = failed = warning_count = 0
+    seen_destinations: set[str] = set()
+    for source, destination in zip(sources, destinations):
+        destination_key = destination.resolve().as_posix().casefold()
+        if destination_key in seen_destinations:
+            error = f"multiple inputs map to the same output {destination}"
+            print(f"Failed {source}: {error}", file=sys.stderr)
+            results.append({"source": str(source), "destination": str(destination), "status": "failed", "error": error})
+            failed += 1
+            continue
+        seen_destinations.add(destination_key)
+        try:
+            result = convert(source, destination, limits=Limits(max_input_bytes=args.max_input_bytes), password=password)
+        except (Ppt2PptxError, OSError) as exc:
+            print(f"Failed {source}: {exc}", file=sys.stderr)
+            results.append({"source": str(source), "destination": str(destination), "status": "failed", "error": str(exc)})
+            failed += 1
+            continue
+        warnings = len(result.report.warnings)
+        warning_count += warnings
+        succeeded += 1
+        print(f"Converted {source} -> {destination}")
+        results.append({"source": str(source), "destination": str(destination), "status": "converted", "slide_count": result.slide_count, "warning_count": warnings, "report": result.report.to_dict()})
+    summary = {"input": str(source_root), "output": str(output_root), "recursive": bool(args.recursive), "file_count": len(sources), "succeeded": succeeded, "failed": failed, "warning_count": warning_count, "results": results}
+    if args.report:
+        write_json_file(args.report, summary)
+    print(f"Batch complete: {succeeded} converted, {failed} failed")
+    return 1 if failed else 0
+
+def main(argv: list[str] | None = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    mode = raw.pop(0) if raw and raw[0] in ("inspect", "batch") else "convert"
+    parser = {"inspect": _inspection_parser, "batch": _batch_parser}.get(mode, _conversion_parser)()
+    args = parser.parse_args(raw)
+    if mode == "batch":
+        try:
+            return _run_batch(args)
+        except (Ppt2PptxError, OSError) as exc:
+            print(f"ppt2pptx: error: {exc}", file=sys.stderr)
+            return 2
+    try:
+        limits = Limits(max_input_bytes=args.max_input_bytes)
+        password = _password(args)
+        if mode == "inspect":
+            result = inspect_ppt(args.input, limits=limits, password=password)
+            print(json.dumps(result, ensure_ascii=False, indent=2) if args.as_json else f"{result['slide_count']} slides; {result['text_box_count']} text boxes")
+            return 0
+        output = args.output or args.input.with_suffix(".pptx")
+        if args.report and (_same_path(args.report, args.input) or _same_path(args.report, output)):
+            print("ppt2pptx: error: report path would overwrite an input or output", file=sys.stderr)
+            return 2
+        result = convert(args.input, args.output, limits=limits, password=password)
+        if args.report:
+            write_json_file(args.report, result.report.to_dict())
+        print(f"Converted {args.input} -> {result.output_path} ({result.slide_count} slides)")
+        return 0
+    except (Ppt2PptxError, OSError) as exc:
+        print(f"ppt2pptx: error: {exc}", file=sys.stderr)
+        return 2
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ppt2pptx-0.3.1/src/ppt2pptx/converter.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from .cfb import CompoundFile, Limits
+from .diagnostics import ConversionReport
+from .encryption import decrypt_powerpoint_document
+from .errors import EncryptedPresentationError, InvalidPpt, UnsupportedPptVersionError, UnsafeOutputPathError
+from .ooxml import write_pptx
+from .oleps import read_summary_information
+from .ppt import Presentation, extract_presentation
+
+@dataclass(frozen=True, slots=True)
+class ConversionResult:
+    output_path: Path
+    report: ConversionReport
+    slide_count: int
+    presentation: Presentation
+
+def _load(source: str | Path, limits: Limits | None = None, report: ConversionReport | None = None, password: str | None = None) -> Presentation:
+    compound = CompoundFile.from_path(source, limits)
+    current_user = compound.open_stream("Current User")
+    document_stream = compound.open_stream("PowerPoint Document")
+    if len(current_user) >= 16 and current_user[12:16] == b"\xdf\xc4\xd1\xf3":
+        document_stream = decrypt_powerpoint_document(document_stream, current_user, password)
+        if report is not None and "encryptedsummary" in compound.by_name:
+            report.warning("ENCRYPTED_METADATA_OMITTED", "encrypted document properties were not copied")
+    if len(current_user) < 8 or current_user[2:4] != b"\xf6\x0f":
+        raise UnsupportedPptVersionError("PowerPoint 95 and earlier presentations are outside the PowerPoint 97–2003 format")
+    pictures = compound.open_stream("Pictures") if "pictures" in compound.by_name else None
+    presentation = extract_presentation(document_stream, pictures)
+    if "\x05summaryinformation" in compound.by_name:
+        try:
+            properties = read_summary_information(compound.open_stream("\x05SummaryInformation"))
+            presentation = replace(presentation, core_properties=properties)
+        except InvalidPpt as exc:
+            if report is not None:
+                report.warning("SUMMARY_INFORMATION_MALFORMED", "malformed optional presentation metadata was omitted", reason=str(exc))
+    return presentation
+
+def inspect_ppt(source: str | Path, *, limits: Limits | None = None, password: str | None = None) -> dict[str, object]:
+    presentation = _load(source, limits, password=password)
+    return {
+        "source": str(source),
+        "slide_count": len(presentation.slides),
+        "slide_size": {"width": presentation.width, "height": presentation.height},
+        "text_box_count": sum(len(slide.text_boxes) for slide in presentation.slides),
+        "picture_count": sum(len(slide.pictures) for slide in presentation.slides),
+        "shape_count": sum(len(slide.shapes) for slide in presentation.slides),
+        "comment_count": sum(len(slide.comments) for slide in presentation.slides),
+        "note_count": sum(len(slide.notes) for slide in presentation.slides),
+        "core_properties": {
+            name: value for name in presentation.core_properties.__dataclass_fields__
+            if (value := getattr(presentation.core_properties, name)) is not None
+        },
+        "slides": [
+            {
+                "index": i + 1,
+                "text_boxes": [
+                    {"text": box.text, "left": box.left, "top": box.top,
+                     "width": box.width, "height": box.height,
+                     "paragraph_alignments": box.paragraph_alignments,
+                     "paragraph_bullets": box.paragraph_bullets,
+                     "rotation": box.rotation, "flip_horizontal": box.flip_horizontal,
+                     "flip_vertical": box.flip_vertical,
+                     "runs": [
+                         {"text": run.text, "bold": run.bold, "italic": run.italic,
+                          "underline": run.underline, "font_size": run.font_size,
+                          "color": run.color, "typeface": run.typeface,
+                          "hyperlink": run.hyperlink}
+                         for run in box.runs
+                     ]}
+                    for box in slide.text_boxes
+                ],
+                "pictures": [
+                    {"extension": picture.extension, "content_type": picture.content_type,
+                     "byte_count": len(picture.data), "left": picture.left,
+                     "top": picture.top, "width": picture.width, "height": picture.height,
+                     "crop_left": picture.crop_left, "crop_top": picture.crop_top,
+                     "crop_right": picture.crop_right, "crop_bottom": picture.crop_bottom,
+                     "rotation": picture.rotation, "flip_horizontal": picture.flip_horizontal,
+                     "flip_vertical": picture.flip_vertical}
+                    for picture in slide.pictures
+                ],
+                "shapes": [
+                    {"preset": shape.preset, "left": shape.left, "top": shape.top,
+                     "width": shape.width, "height": shape.height,
+                     "fill_color": shape.fill_color, "line_color": shape.line_color,
+                     "rotation": shape.rotation, "flip_horizontal": shape.flip_horizontal,
+                     "flip_vertical": shape.flip_vertical}
+                    for shape in slide.shapes
+                ],
+                "background_color": slide.background_color,
+                "background_color_end": slide.background_color_end,
+                "hidden": slide.hidden,
+                "notes": list(slide.notes),
+                "header_footer": ({
+                    "date_text": slide.header_footer.date_text,
+                    "date_is_auto": slide.header_footer.date_is_auto,
+                    "header_text": slide.header_footer.header_text,
+                    "footer_text": slide.header_footer.footer_text,
+                    "show_slide_number": slide.header_footer.show_slide_number,
+                } if slide.header_footer else None),
+                "comments": [
+                    {"author": comment.author, "initials": comment.initials,
+                     "text": comment.text, "left": comment.left,
+                     "top": comment.top, "created": comment.created}
+                    for comment in slide.comments
+                ],
+            }
+            for i, slide in enumerate(presentation.slides)
+        ],
+    }
+
+def convert(source: str | Path, destination: str | Path | None = None, *, limits: Limits | None = None, password: str | None = None) -> ConversionResult:
+    source_path = Path(source)
+    output = Path(destination) if destination is not None else source_path.with_suffix(".pptx")
+    if output.suffix.casefold() != ".pptx": raise UnsafeOutputPathError("destination must use the .pptx extension")
+    if source_path.resolve() == output.resolve(): raise UnsafeOutputPathError("destination must not overwrite the source presentation")
+    report = ConversionReport(str(source_path), str(output))
+    presentation = _load(source_path, limits, report, password)
+    report.warning("ADVANCED_FEATURES_APPROXIMATED", "charts, animations, audio/video, and complex freeform master geometry may be omitted or approximated")
+    if not presentation.slides: report.warning("NO_SLIDES_FOUND", "no normal slide records could be recovered from the presentation")
+    elif any(not (slide.text_boxes or slide.pictures or slide.shapes or slide.header_footer or slide.notes)
+             for slide in presentation.slides):
+        report.warning("EMPTY_SLIDE_CONTENT", "one or more slides had no recoverable editable content")
+    write_pptx(output, presentation)
+    return ConversionResult(output, report, len(presentation.slides), presentation)

ppt2pptx-0.3.1/src/ppt2pptx/diagnostics.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class ConversionReport:
+    source: str
+    destination: str | None = None
+    warnings: list[dict[str, object]] = field(default_factory=list)
+
+    def warning(self, code: str, message: str, **details: object) -> None:
+        self.warnings.append({"code": code, "message": message, **details})
+
+    def to_dict(self) -> dict[str, object]:
+        return {"source": self.source, "destination": self.destination,
+                "warning_count": len(self.warnings), "warnings": self.warnings}
+
+
+def write_json_file(path: str | Path, value: object) -> None:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary = target.with_name(f".{target.name}.tmp")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(target)