smart-pdf-compare 0.1.0

Quick start · Features · CLI · API · Architecture · Limitations

SmartPDFCompare is a lightweight Python library for comparing the extractable text in two PDF versions. It gives applications structured word and page changes, then uses the same coordinates to write readable highlighted PDFs and an optional side-by-side review report.

Features

• Structured comparison — added, removed, replaced, added-page, removed-page, and moved-page records with JSON serialization.
• Unicode-aware text extraction — PyMuPDF word coordinates, NFKC normalization, case folding, ligatures, NBSPs, and dash/minus variants.
• Practical page alignment — content matching for inserted/moved pages, bounded sequential look-ahead, and index-by-index comparison.
• Visual review — native PDF highlights or boxes in safe output copies; optional side-by-side report pages.
• Small CLI — terminal summary, JSON result, highlighted output, report, alignment policy, and style controls.

Install

python -m pip install --upgrade smart-pdf-compare

The package tracks the current major PyMuPDF release. Create a virtual environment first for a predictable setup:

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install --upgrade smart-pdf-compare

Quick start

from smart_pdf_compare import compare_pdfs, highlight_differences

result = compare_pdfs("original.pdf", "revised.pdf")

print(result.is_identical)
print(result.summary)
for change in result.differences:
    print(f"{change.change_type}: {change.old_text!r} -> {change.new_text!r}")

outputs = highlight_differences(
    "original.pdf",
    "revised.pdf",
    output_dir="diff-output",
    result=result,
    include_report=True,
)
print(outputs)

Work with JSON

import json

with open("comparison.json", "w", encoding="utf-8") as file:
    json.dump(result.to_dict(), file, indent=2)

result.truncated is True when max_differences limits returned detail entries. Aggregate counts in result.summary always cover the full comparison.

Highlighted output

Use real PDF annotations by default, or boxes where highlights are not desired:

from smart_pdf_compare import highlight_differences

highlight_differences(
    "original.pdf", "revised.pdf", "diff-output",
    style="box",          # "highlight" is the default
    include_report=True,   # creates difference_report.pdf
)

Source PDFs are never overwritten. The side-by-side report contains only pages with differences, displays page labels, and leaves a clearly labeled blank side for an inserted or removed page.

Alignment choices

from smart_pdf_compare import ComparisonOptions, compare_pdfs

result = compare_pdfs(
    "original.pdf", "revised.pdf",
    options=ComparisonOptions(
        alignment="content",       # default
        similarity_threshold=0.60,
        lookahead=5,
        max_differences=1_000,
    ),
)

Normalization is deliberately conservative: it uses NFKC, case folding, ligature compatibility, non-breaking-space cleanup, and dash/minus unification. Punctuation remains significant by default, so decimal values, negative numbers, negation, and contractions do not silently disappear.

Command line

smart-pdf-compare original.pdf revised.pdf \
  --alignment content \
  --output-dir diff-output \
  --style highlight \
  --report \
  --json diff-output/comparison.json

Limitations

SmartPDFCompare compares the PDF text layer, not rendered pixels. It does not perform OCR, visual-diff analysis, or image comparison. If either document has no extractable text, it raises MissingTextLayerError instead of falsely claiming that two scanned PDFs are identical. Complex tables and multi-column PDFs can also expose an unreliable reading order from the source PDF.

PyMuPDF is available under AGPL or commercial terms. Confirm that its license is appropriate for your use case.

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m build
python -m twine check dist/*

Read the contribution guide, public API, architecture notes, and changelog. Before publishing, verify availability of smart-pdf-compare on PyPI, upload to TestPyPI, install the artifact in a clean environment, and use PyPI Trusted Publishing for the production release.

License

SmartPDFCompare’s own source code is licensed under the MIT License. Its PyMuPDF dependency has separate licensing, described above.