diffpdf 0.1.2__py3-none-any.whl

diffpdf/__init__.py

@@ -0,0 +1,15 @@
+from importlib.metadata import version
+
+from .cli import cli
+
+__version__ = version("diffpdf")
+
+
+def main(args=None):  # pragma: no cover
+    if args is None:
+        cli()
+    else:
+        cli(args, standalone_mode=False)
+
+
+__all__ = ["main", "__version__"]

diffpdf/cli.py

@@ -0,0 +1,71 @@
+import logging
+import sys
+from pathlib import Path
+
+import click
+import colorlog
+
+from .comparators import compare_pdfs
+
+
+def setup_logging(debug, save_log):  # pragma: no cover
+    level = logging.DEBUG if debug else logging.INFO
+
+    formatter = colorlog.ColoredFormatter(
+        "%(log_color)s%(asctime)s %(levelname)-8s%(reset)s %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+        log_colors={
+            "DEBUG": "cyan",
+            "INFO": "green",
+            "WARNING": "yellow",
+            "ERROR": "red",
+            "CRITICAL": "red,bg_white",
+        },
+    )
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+
+    logger = logging.getLogger()
+    logger.setLevel(level)
+    logger.addHandler(console_handler)
+
+    if save_log:
+        file_formatter = logging.Formatter(
+            "%(asctime)s %(levelname)-8s %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        file_handler = logging.FileHandler("log.txt")
+        file_handler.setFormatter(file_formatter)
+        logger.addHandler(file_handler)
+
+    return logger
+
+
+@click.command()
+@click.argument(
+    "reference", type=click.Path(exists=True, dir_okay=False, path_type=Path)
+)
+@click.argument("actual", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "--threshold", type=float, default=0.1, help="Pixelmatch threshold (0.0-1.0)"
+)
+@click.option("--dpi", type=int, default=96, help="Render resolution")
+@click.option(
+    "--output-dir",
+    type=click.Path(file_okay=False, path_type=Path),
+    default="./",
+    help="Diff image output directory",
+)
+@click.option("--debug", is_flag=True, help="Verbose logging")
+@click.option("--save-log", is_flag=True, help="Write log output to log.txt")
+@click.version_option(package_name="diffpdf")
+def cli(reference, actual, threshold, dpi, output_dir, debug, save_log):
+    """Compare two PDF files for structural, textual, and visual differences."""
+    logger = setup_logging(debug, save_log)
+
+    try:
+        compare_pdfs(reference, actual, threshold, dpi, output_dir, logger)
+    except Exception as e:  # pragma: no cover
+        logger.critical(f"Error: {e}")
+        sys.exit(2)

diffpdf/comparators.py

@@ -0,0 +1,22 @@
+import sys
+from pathlib import Path
+
+from .hash_check import check_hash
+from .page_check import check_page_counts
+from .text_check import check_text_content
+from .visual_check import check_visual_content
+
+
+def compare_pdfs(
+    ref: Path, actual: Path, threshold: float, dpi: int, output_dir: Path, logger
+) -> None:
+    check_hash(ref, actual, logger)
+
+    check_page_counts(ref, actual, logger)
+
+    check_text_content(ref, actual, logger)
+
+    check_visual_content(ref, actual, threshold, dpi, output_dir, logger)
+
+    logger.info("PDFs are equivalent")
+    sys.exit(0)

diffpdf/hash_check.py

@@ -0,0 +1,24 @@
+import hashlib
+import sys
+from pathlib import Path
+
+
+def compute_file_hash(filepath: Path) -> str:
+    sha256 = hashlib.sha256()
+    with open(filepath, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+
+def check_hash(ref: Path, actual: Path, logger) -> None:
+    logger.info("[1/4] Checking file hashes...")
+
+    ref_hash = compute_file_hash(ref)
+    actual_hash = compute_file_hash(actual)
+
+    if ref_hash == actual_hash:
+        logger.info("Files are identical (hash match)")
+        sys.exit(0)
+
+    logger.info("Hashes differ, continuing checks")

diffpdf/page_check.py

@@ -0,0 +1,24 @@
+import sys
+from pathlib import Path
+
+import fitz
+
+
+def get_page_count(pdf_path: Path) -> int:
+    doc = fitz.open(pdf_path)
+    count = len(doc)
+    doc.close()
+    return count
+
+
+def check_page_counts(ref: Path, actual: Path, logger) -> None:
+    logger.info("[2/4] Checking page counts...")
+
+    ref_count = get_page_count(ref)
+    actual_count = get_page_count(actual)
+
+    if ref_count != actual_count:
+        logger.error(f"Page count mismatch: expected {ref_count}, got {actual_count}")
+        sys.exit(1)
+
+    logger.info(f"Page counts match ({ref_count} pages)")

diffpdf/text_check.py

@@ -0,0 +1,45 @@
+import difflib
+import sys
+from pathlib import Path
+
+import fitz
+
+
+def extract_text(pdf_path: Path) -> str:
+    doc = fitz.open(pdf_path)
+    text = ""
+    for page in doc:
+        text += page.get_text()
+    doc.close()
+    return text.strip()
+
+
+def generate_diff(ref_text: str, actual_text: str) -> str:
+    ref_lines = ref_text.splitlines(keepends=True)
+    actual_lines = actual_text.splitlines(keepends=True)
+
+    diff = difflib.unified_diff(
+        ref_lines,
+        actual_lines,
+        fromfile="reference.pdf",
+        tofile="actual.pdf",
+        lineterm="",
+    )
+
+    return "".join(diff)
+
+
+def check_text_content(ref: Path, actual: Path, logger) -> None:
+    logger.info("[3/4] Checking text content...")
+
+    ref_text = extract_text(ref)
+    actual_text = extract_text(actual)
+
+    if ref_text != actual_text:
+        diff = generate_diff(ref_text, actual_text)
+        logger.error("Text content mismatch")
+        for line in diff.splitlines():
+            logger.error(line)
+        sys.exit(1)
+
+    logger.info("Text content matches")

diffpdf/visual_check.py

@@ -0,0 +1,63 @@
+import sys
+from pathlib import Path
+
+import fitz
+from PIL import Image
+from pixelmatch.contrib.PIL import pixelmatch
+
+
+def render_page_to_image(pdf_path: Path, page_num: int, dpi: int) -> Image.Image:
+    doc = fitz.open(pdf_path)
+    page = doc[page_num]
+    pix = page.get_pixmap(dpi=dpi)
+    img = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
+    doc.close()
+    return img
+
+
+def compare_images(
+    ref_img: Image.Image, actual_img: Image.Image, threshold: float, output_path: Path
+) -> bool:
+    diff_img = Image.new("RGB", ref_img.size)
+    mismatch_count = pixelmatch(ref_img, actual_img, diff_img, threshold=threshold)
+
+    if mismatch_count > 0:
+        diff_img.save(output_path)
+        return False
+
+    return True
+
+
+def check_visual_content(
+    ref: Path, actual: Path, threshold: float, dpi: int, output_dir: Path, logger
+) -> None:
+    logger.info("[4/4] Checking visual content...")
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    ref_doc = fitz.open(ref)
+    page_count = len(ref_doc)
+    ref_doc.close()
+
+    failing_pages = []
+
+    for page_num in range(page_count):
+        ref_img = render_page_to_image(ref, page_num, dpi)
+        actual_img = render_page_to_image(actual, page_num, dpi)
+
+        ref_name = ref.stem
+        actual_name = actual.stem
+        output_path = (
+            output_dir / f"{ref_name}_vs_{actual_name}_page{page_num + 1}_diff.png"
+        )
+
+        passed = compare_images(ref_img, actual_img, threshold, output_path)
+
+        if not passed:
+            failing_pages.append(page_num + 1)
+
+    if failing_pages:
+        logger.error(f"Visual mismatch on pages: {', '.join(map(str, failing_pages))}")
+        sys.exit(1)
+
+    logger.info("Visual content matches")

diffpdf-0.1.2.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: diffpdf
+Version: 0.1.2
+Summary: A tool for comparing PDF files
+Project-URL: Homepage, https://github.com/JustusRijke/DiffPDF
+Project-URL: Issues, https://github.com/JustusRijke/DiffPDF/issues
+Author-email: Justus Rijke <justusrijke@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: colorlog
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pixelmatch>=0.3.0
+Requires-Dist: pymupdf>=1.23.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DiffPDF
+
+[![CI](https://github.com/JustusRijke/DiffPDF/actions/workflows/ci.yml/badge.svg)](https://github.com/JustusRijke/DiffPDF/actions/workflows/ci.yml)
+
+CLI tool for detecting structural, textual, and visual differences between PDF files, for use in automatic regression tests.
+
+## Installation
+
+```bash
+pip install diffpdf
+```
+
+## Usage
+
+```bash
+diffpdf <baseline.pdf> <actual.pdf> [OPTIONS]
+```
+
+## How It Works
+
+DiffPDF uses a fail-fast sequential pipeline to compare PDFs:
+
+1. **Hash Check** - SHA-256 comparison. If identical, exit immediately with pass.
+2. **Page Count** - Verify both PDFs have the same number of pages.
+3. **Text Content** - Extract and compare text from all pages.
+4. **Visual Check** - Render pages to images and compare using pixelmatch.
+
+Each stage only runs if all previous stages pass.
+
+**⚠️ Performance Warning:** The Python port of pixelmatch is extremely slow.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--threshold` | 0.1 | Pixelmatch threshold (0.0-1.0) |
+| `--dpi` | 96 | Render resolution |
+| `--output-dir` | ./ | Directory for diff images |
+| `--debug` | - | Verbose logging |
+| `--save-log` | - | Write log to log.txt |
+
+## Exit Codes
+
+- `0` — Pass (PDFs are equivalent)
+- `1` — Fail (differences detected)
+- `2` — Error (invalid input or processing error)
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest tests/ -v
+ruff check .
+```
+
+## Acknowledgements
+
+Built with [PyMuPDF](https://pymupdf.readthedocs.io/) for PDF parsing and [pixelmatch-py](https://github.com/whtsky/pixelmatch-py) (Python port of [pixelmatch](https://github.com/mapbox/pixelmatch)) for visual comparison.

diffpdf-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+diffpdf/__init__.py,sha256=kggdyYVRCNA8X7vPwLIDQ6uQN2FoNQY2zqUxnDh_dTg,260
+diffpdf/cli.py,sha256=p1eW8b3ioI9JxZqLnU1oQeDlubeoUbWTd7nR4raQKJY,2204
+diffpdf/comparators.py,sha256=zH-TxYvddyvyjRWRtLjIcDhVxe9PZPTNJyAzPCWu9B8,573
+diffpdf/hash_check.py,sha256=SkNTJddjaXCUWFs3wSlDjVIzBKTS2Buvd-vPBZLAvFI,635
+diffpdf/page_check.py,sha256=alcl8KsPFDgVtKpbEJCcwGZqUlQSjzQcv2-7erxq6HM,573
+diffpdf/text_check.py,sha256=WxEH75a-ieFtelL1ieFVmsriz6eElLkZPPlnnW1lGUU,1056
+diffpdf/visual_check.py,sha256=I8-id14MmyRNmcJC3v9Z7R6-JLEnxlCJ4aLYWWWKNZM,1740
+diffpdf-0.1.2.dist-info/METADATA,sha256=TVxYtQHYNj9wXZEduIPY-tjHxmUZ7j-MahJsNESHIic,2489
+diffpdf-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+diffpdf-0.1.2.dist-info/entry_points.txt,sha256=MYzgwCJSVq_fvPI-R5ApSCFDD4W6nqgwQ8kwXcyndcw,41
+diffpdf-0.1.2.dist-info/licenses/LICENSE,sha256=dMsm7NlDabaS_o0khNX5QyX6pc3fzI6SK56YfZxdzuE,1069
+diffpdf-0.1.2.dist-info/RECORD,,

diffpdf-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

diffpdf-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diffpdf = diffpdf:main

diffpdf-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Justus Rijke
+
+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.