open-document-lib 1.3.0__tar.gz → 1.4.0__tar.gz

{open_document_lib-1.3.0/open_document_lib.egg-info → open_document_lib-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-document-lib
-Version: 1.3.0
+Version: 1.4.0
 Summary: Standard-library toolkit for reading, editing, and writing OpenDocument Format files (ODT, ODP, ODS, ODG)
 Author: Patrick Leiverkus
 License: MIT
@@ -30,6 +30,8 @@ Provides-Extra: scholarly
 Requires-Dist: bibtexparser>=1.4; extra == "scholarly"
 Provides-Extra: validate
 Requires-Dist: lxml>=4.9; extra == "validate"
+Provides-Extra: render
+Requires-Dist: Pillow>=10; extra == "render"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.9; extra == "dev"
@@ -37,6 +39,7 @@ Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: hypothesis>=6.0; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: Pillow>=10; extra == "dev"
 Dynamic: license-file
 
 # open-document-lib
@@ -190,6 +193,14 @@ helpers) is internal and may change without notice.
 | `find_pandoc() -> str \| None` | Locate the `pandoc` binary. |
 | `latex_to_mathml(latex) -> bytes` | Convert a LaTeX snippet to MathML via Pandoc. |
 
+### Rendering
+
+| Signature | Description |
+|---|---|
+| `render_to_pdf(odf_path, outdir) -> Path` | Render an ODF file to PDF via LibreOffice (isolated profile). |
+| `pdf_to_pngs(pdf_path, outdir, dpi=150) -> list[Path]` | Render each PDF page to a PNG via `pdftoppm` (Poppler). |
+| `build_contact_sheet(images, output_path, columns=0) -> Path` | Compose page thumbnails into one labelled grid image. Requires Pillow (`pip install open-document-lib[render]`). |
+
 ## License
 
 MIT. See [LICENSE](https://github.com/leiverkus/open-document-skills/blob/main/LICENSE).

{open_document_lib-1.3.0 → open_document_lib-1.4.0}/docs/library-api.md

@@ -149,6 +149,14 @@ helpers) is internal and may change without notice.
 | `find_pandoc() -> str \| None` | Locate the `pandoc` binary. |
 | `latex_to_mathml(latex) -> bytes` | Convert a LaTeX snippet to MathML via Pandoc. |
 
+### Rendering
+
+| Signature | Description |
+|---|---|
+| `render_to_pdf(odf_path, outdir) -> Path` | Render an ODF file to PDF via LibreOffice (isolated profile). |
+| `pdf_to_pngs(pdf_path, outdir, dpi=150) -> list[Path]` | Render each PDF page to a PNG via `pdftoppm` (Poppler). |
+| `build_contact_sheet(images, output_path, columns=0) -> Path` | Compose page thumbnails into one labelled grid image. Requires Pillow (`pip install open-document-lib[render]`). |
+
 ## License
 
 MIT. See [LICENSE](https://github.com/leiverkus/open-document-skills/blob/main/LICENSE).

{open_document_lib-1.3.0 → open_document_lib-1.4.0}/odf_lib/__init__.py

@@ -23,6 +23,7 @@ from odf_lib.odf_common import (
     ODF_NAMESPACES,
     VERSION,
     apply_strict_schema_check,
+    build_contact_sheet,
     clear_children,
     copy_into_package,
     copy_with_multiple_members,
@@ -42,6 +43,8 @@ from odf_lib.odf_common import (
     pack_dir_as_odf,
     pack_flat_odf,
     parse_xml_from_zip,
+    pdf_to_pngs,
+    render_to_pdf,
     replace_pattern_with_element_in_element,
     replace_text_in_element,
     sniff_image_mime,
@@ -105,4 +108,8 @@ __all__ = [
     "find_soffice",
     "find_pandoc",
     "latex_to_mathml",
+    # Rendering
+    "render_to_pdf",
+    "pdf_to_pngs",
+    "build_contact_sheet",
 ]

{open_document_lib-1.3.0 → open_document_lib-1.4.0}/odf_lib/odf_common.py

@@ -19,7 +19,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from xml.etree import ElementTree as ET
 
-VERSION = "1.3.0"  # keep in sync with pyproject.toml (see CONTRIBUTING.md)
+VERSION = "1.4.0"  # keep in sync with pyproject.toml (see CONTRIBUTING.md)
 
 ODF_NAMESPACES: dict[str, str] = {
     "office": "urn:oasis:names:tc:opendocument:xmlns:office:1.0",
@@ -1630,3 +1630,149 @@ def local_name(tag: str) -> str:
         The local name part (e.g. ``"text"``).
     """
     return tag.split("}", 1)[1] if tag.startswith("{") else tag
+
+
+def render_to_pdf(odf_path: Path, outdir: Path) -> Path:
+    """Render an ODF file to PDF with LibreOffice.
+
+    Uses an isolated, throwaway user profile so concurrent renders do not
+    clash. The PDF is written to *outdir* as ``<stem>.pdf``.
+
+    Args:
+        odf_path: Source ODF file.
+        outdir: Directory for the PDF (created if absent).
+
+    Returns:
+        Path to the rendered PDF.
+
+    Raises:
+        SystemExit: If LibreOffice fails or the PDF is not produced.
+    """
+    import subprocess
+
+    outdir.mkdir(parents=True, exist_ok=True)
+    soffice: str = find_soffice()
+    profile: str = tempfile.mkdtemp(prefix="odf-soffice-")
+    try:
+        result = subprocess.run(
+            [
+                soffice,
+                f"-env:UserInstallation=file://{profile}",
+                "--headless",
+                "--convert-to",
+                "pdf",
+                "--outdir",
+                str(outdir),
+                str(odf_path),
+            ],
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+        )
+    finally:
+        shutil.rmtree(profile, ignore_errors=True)
+    pdf: Path = outdir / f"{odf_path.stem}.pdf"
+    if result.returncode != 0 or not pdf.exists():
+        raise SystemExit(f"LibreOffice failed to render {odf_path.name}:\n{result.stdout}")
+    return pdf
+
+
+def pdf_to_pngs(pdf_path: Path, outdir: Path, dpi: int = 150) -> list[Path]:
+    """Render every page of a PDF to a PNG with ``pdftoppm`` (Poppler).
+
+    Args:
+        pdf_path: Source PDF.
+        outdir: Directory for the page PNGs (created if absent).
+        dpi: Render resolution.
+
+    Returns:
+        Sorted list of ``<stem>-N.png`` page images.
+
+    Raises:
+        SystemExit: If ``pdftoppm`` is not installed or rendering fails.
+    """
+    import subprocess
+
+    pdftoppm: str | None = shutil.which("pdftoppm")
+    if pdftoppm is None:
+        raise SystemExit(
+            "pdftoppm not found — install Poppler (e.g. 'brew install poppler' or 'apt install poppler-utils')"
+        )
+    outdir.mkdir(parents=True, exist_ok=True)
+    prefix: Path = outdir / pdf_path.stem
+    result = subprocess.run(
+        [pdftoppm, "-png", "-r", str(dpi), str(pdf_path), str(prefix)],
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+    )
+    if result.returncode != 0:
+        raise SystemExit(f"pdftoppm failed for {pdf_path.name}:\n{result.stdout}")
+    return sorted(outdir.glob(f"{pdf_path.stem}-*.png"))
+
+
+def build_contact_sheet(images: list[Path], output_path: Path, columns: int = 0) -> Path:
+    """Compose page thumbnails into a single labelled grid image.
+
+    A contact sheet shows every page of a document at once, so layout and
+    cross-page consistency can be judged in a single glance. Requires Pillow.
+
+    Args:
+        images: Page images, in order.
+        output_path: Destination PNG.
+        columns: Grid columns; 0 picks 2 for landscape pages, 3 for portrait.
+
+    Returns:
+        Path to the contact sheet PNG.
+
+    Raises:
+        SystemExit: If Pillow is not installed or *images* is empty.
+    """
+    try:
+        from PIL import Image, ImageDraw, ImageFont
+    except ImportError:
+        raise SystemExit(
+            "Contact sheet rendering requires Pillow. Install with:\n"
+            "  pip install open-document-lib[render]\n"
+            "Or render per-page PNGs with --png and inspect them individually."
+        ) from None
+
+    if not images:
+        raise SystemExit("build_contact_sheet: no page images to compose")
+
+    thumb_w = 480
+    pad = 16
+    label_h = 22
+    bg = (245, 245, 247)
+
+    thumbs: list[Image.Image] = []
+    for path in images:
+        img = Image.open(path).convert("RGB")
+        ratio = thumb_w / img.width
+        thumbs.append(img.resize((thumb_w, max(1, round(img.height * ratio))), Image.LANCZOS))
+
+    if columns <= 0:
+        columns = 2 if thumbs[0].width >= thumbs[0].height else 3
+    columns = min(columns, len(thumbs))
+    rows = (len(thumbs) + columns - 1) // columns
+
+    cell_w = thumb_w + pad
+    cell_h = max(t.height for t in thumbs) + pad + label_h
+    sheet = Image.new("RGB", (columns * cell_w + pad, rows * cell_h + pad), bg)
+    draw = ImageDraw.Draw(sheet)
+    try:
+        font = ImageFont.truetype("/System/Library/Fonts/Supplemental/Arial.ttf", 15)
+    except OSError:
+        font = ImageFont.load_default()
+
+    for index, thumb in enumerate(thumbs):
+        col = index % columns
+        row = index // columns
+        x = pad + col * cell_w
+        y = pad + row * cell_h
+        draw.text((x, y), f"Page {index + 1}", fill=(60, 60, 70), font=font)
+        sheet.paste(thumb, (x, y + label_h))
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(output_path)
+    return output_path

{open_document_lib-1.3.0 → open_document_lib-1.4.0/open_document_lib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-document-lib
-Version: 1.3.0
+Version: 1.4.0
 Summary: Standard-library toolkit for reading, editing, and writing OpenDocument Format files (ODT, ODP, ODS, ODG)
 Author: Patrick Leiverkus
 License: MIT
@@ -30,6 +30,8 @@ Provides-Extra: scholarly
 Requires-Dist: bibtexparser>=1.4; extra == "scholarly"
 Provides-Extra: validate
 Requires-Dist: lxml>=4.9; extra == "validate"
+Provides-Extra: render
+Requires-Dist: Pillow>=10; extra == "render"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: ruff>=0.9; extra == "dev"
@@ -37,6 +39,7 @@ Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: hypothesis>=6.0; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: Pillow>=10; extra == "dev"
 Dynamic: license-file
 
 # open-document-lib
@@ -190,6 +193,14 @@ helpers) is internal and may change without notice.
 | `find_pandoc() -> str \| None` | Locate the `pandoc` binary. |
 | `latex_to_mathml(latex) -> bytes` | Convert a LaTeX snippet to MathML via Pandoc. |
 
+### Rendering
+
+| Signature | Description |
+|---|---|
+| `render_to_pdf(odf_path, outdir) -> Path` | Render an ODF file to PDF via LibreOffice (isolated profile). |
+| `pdf_to_pngs(pdf_path, outdir, dpi=150) -> list[Path]` | Render each PDF page to a PNG via `pdftoppm` (Poppler). |
+| `build_contact_sheet(images, output_path, columns=0) -> Path` | Compose page thumbnails into one labelled grid image. Requires Pillow (`pip install open-document-lib[render]`). |
+
 ## License
 
 MIT. See [LICENSE](https://github.com/leiverkus/open-document-skills/blob/main/LICENSE).

{open_document_lib-1.3.0 → open_document_lib-1.4.0}/open_document_lib.egg-info/requires.txt

@@ -6,10 +6,14 @@ pytest-cov>=5.0
 hypothesis>=6.0
 build>=1.0
 mypy>=1.8
+Pillow>=10
 
 [odf]
 odfpy>=1.4.0
 
+[render]
+Pillow>=10
+
 [scholarly]
 bibtexparser>=1.4
 

{open_document_lib-1.3.0 → open_document_lib-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "open-document-lib"
-version = "1.3.0"
+version = "1.4.0"
 description = "Standard-library toolkit for reading, editing, and writing OpenDocument Format files (ODT, ODP, ODS, ODG)"
 readme = "docs/library-api.md"
 requires-python = ">=3.10"
@@ -47,7 +47,8 @@ Issues = "https://github.com/leiverkus/open-document-skills/issues"
 odf = ["odfpy>=1.4.0"]
 scholarly = ["bibtexparser>=1.4"]
 validate = ["lxml>=4.9"]
-dev = ["pytest>=8.0", "ruff>=0.9", "pytest-cov>=5.0", "hypothesis>=6.0", "build>=1.0", "mypy>=1.8"]
+render = ["Pillow>=10"]
+dev = ["pytest>=8.0", "ruff>=0.9", "pytest-cov>=5.0", "hypothesis>=6.0", "build>=1.0", "mypy>=1.8", "Pillow>=10"]
 
 [tool.setuptools]
 packages = ["odf_lib"]

{open_document_lib-1.3.0 → open_document_lib-1.4.0}/tests/test_lib_odf_common.py

@@ -15,6 +15,7 @@ from xml.etree import ElementTree as ET
 
 from odf_lib.odf_common import (
     VERSION,
+    build_contact_sheet,
     clear_children,
     copy_into_package,
     copy_with_multiple_members,
@@ -559,5 +560,53 @@ class LibOdfCommonTests(unittest.TestCase):
                 find_soffice()
 
 
+try:
+    from PIL import Image as _PILImage
+
+    HAVE_PILLOW = True
+except ImportError:
+    HAVE_PILLOW = False
+
+
+@unittest.skipUnless(HAVE_PILLOW, "Pillow not installed")
+class ContactSheetTests(unittest.TestCase):
+    def _make_pages(self, tmp: Path, count: int, size: tuple[int, int] = (320, 240)) -> list[Path]:
+        paths: list[Path] = []
+        for i in range(count):
+            path = tmp / f"page-{i + 1}.png"
+            _PILImage.new("RGB", size, (200, 200 + i * 10, 220)).save(path)
+            paths.append(path)
+        return paths
+
+    def test_contact_sheet_composes_a_valid_grid(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pages = self._make_pages(tmp_path, 5)
+            out = tmp_path / "sheet.png"
+            result = build_contact_sheet(pages, out)
+            self.assertEqual(result, out)
+            self.assertTrue(out.exists())
+            with _PILImage.open(out) as sheet:
+                self.assertEqual(sheet.format, "PNG")
+                # 5 landscape pages -> 2 columns, 3 rows: sheet is wider than one cell.
+                self.assertGreater(sheet.width, 480)
+                self.assertGreater(sheet.height, 480)
+
+    def test_contact_sheet_respects_explicit_columns(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            pages = self._make_pages(tmp_path, 4)
+            wide = build_contact_sheet(pages, tmp_path / "wide.png", columns=4)
+            narrow = build_contact_sheet(pages, tmp_path / "narrow.png", columns=1)
+            with _PILImage.open(wide) as w, _PILImage.open(narrow) as n:
+                self.assertGreater(w.width, n.width)
+                self.assertGreater(n.height, w.height)
+
+    def test_contact_sheet_rejects_empty_input(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            with self.assertRaises(SystemExit):
+                build_contact_sheet([], Path(tmp) / "sheet.png")
+
+
 if __name__ == "__main__":
     unittest.main()

{open_document_lib-1.3.0 → open_document_lib-1.4.0}/tests/test_libreoffice_integration.py

@@ -88,6 +88,45 @@ class LibreOfficeIntegrationTests(unittest.TestCase):
             self.assertTrue(pdf.exists())
             self.assertGreater(pdf.stat().st_size, 0)
 
+    def test_ods_render_to_pdf(self) -> None:
+        """The new ODS render.py must produce a PDF."""
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            scripts = SKILLS / "ods" / "scripts"
+            ods = tmp_path / "book.ods"
+            outdir = tmp_path / "qa"
+            run_script(scripts / "create_minimal_ods.py", FIXTURES / "ods_workbook.json", ods)
+            run_script(scripts / "render.py", ods, "--outdir", outdir)
+            pdf = outdir / "book.pdf"
+            self.assertTrue(pdf.exists())
+            self.assertGreater(pdf.stat().st_size, 0)
+
+    def test_contact_sheet_render(self) -> None:
+        """render.py --contact-sheet must compose all pages into one PNG."""
+        import shutil
+
+        if not shutil.which("pdftoppm"):
+            self.skipTest("pdftoppm (Poppler) not available")
+        try:
+            import PIL  # noqa: F401
+        except ImportError:
+            self.skipTest("Pillow not installed")
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            scripts = SKILLS / "odp" / "scripts"
+            spec = tmp_path / "deck.json"
+            spec.write_text(
+                json.dumps({"slides": [{"name": f"S{i}", "title": f"Slide {i}"} for i in range(1, 4)]}),
+                encoding="utf-8",
+            )
+            odp = tmp_path / "deck.odp"
+            run_script(scripts / "create_minimal_odp.py", spec, odp)
+            outdir = tmp_path / "qa"
+            run_script(scripts / "render.py", odp, "--outdir", outdir, "--contact-sheet")
+            sheet = outdir / "deck-contact.png"
+            self.assertTrue(sheet.exists())
+            self.assertGreater(sheet.stat().st_size, 0)
+
     def test_markdown_to_odt_renders_to_pdf(self) -> None:
         """An ODT built from Markdown must render to a non-empty PDF."""
         with tempfile.TemporaryDirectory() as tmp: