smart-pdf-compare 0.1.0__py3-none-any.whl

smart_pdf_compare/__init__.py

@@ -0,0 +1,14 @@
+"""SmartPDFCompare: structured text comparison and PDF highlighting."""
+from .api import ComparisonOptions, compare_pdfs
+from .exceptions import ConfigurationError, InvalidPDFError, MissingTextLayerError, PDFComparisonError
+from .highlighting import HighlightOutputs, create_side_by_side_report, highlight_differences
+from .normalization import NormalizationOptions
+from .results import ChangeType, ComparisonResult, ComparisonSummary, Difference
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ChangeType", "ComparisonOptions", "ComparisonResult", "ComparisonSummary", "ConfigurationError",
+    "Difference", "HighlightOutputs", "InvalidPDFError", "MissingTextLayerError", "NormalizationOptions",
+    "PDFComparisonError", "compare_pdfs", "create_side_by_side_report", "highlight_differences",
+]

smart_pdf_compare/__main__.py

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

smart_pdf_compare/alignment.py

@@ -0,0 +1,121 @@
+"""Page correspondence strategies."""
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+from typing import Literal, Optional, Sequence
+
+from .exceptions import ConfigurationError
+from .extraction import ExtractedPage
+
+AlignmentStrategy = Literal["content", "index", "sequential"]
+
+
+@dataclass(frozen=True)
+class PagePair:
+    old: Optional[int]
+    new: Optional[int]
+    moved: bool = False
+
+
+def _similarity(left: ExtractedPage, right: ExtractedPage) -> float:
+    if not left.words and not right.words:
+        return 1.0
+    if not left.words or not right.words:
+        return 0.0
+    return SequenceMatcher(None, left.signature.split(), right.signature.split(), autojunk=False).ratio()
+
+
+def align_pages(old: Sequence[ExtractedPage], new: Sequence[ExtractedPage], strategy: AlignmentStrategy, threshold: float, lookahead: int) -> list[PagePair]:
+    """Return one-to-one page correspondence, including unpaired pages."""
+    if strategy not in ("content", "index", "sequential"):
+        raise ConfigurationError("alignment must be 'content', 'index', or 'sequential'")
+    if not 0.0 <= threshold <= 1.0:
+        raise ConfigurationError("similarity_threshold must be between 0 and 1")
+    if lookahead < 1:
+        raise ConfigurationError("lookahead must be at least 1")
+    if strategy == "index":
+        pairs = [PagePair(i, i) for i in range(min(len(old), len(new)))]
+        pairs.extend(PagePair(i, None) for i in range(len(new), len(old)))
+        pairs.extend(PagePair(None, j) for j in range(len(old), len(new)))
+        return pairs
+    if strategy == "sequential":
+        return _sequential(old, new, threshold, lookahead)
+    return _content(old, new, threshold)
+
+
+def _content(old: Sequence[ExtractedPage], new: Sequence[ExtractedPage], threshold: float) -> list[PagePair]:
+    # Exact fingerprints are paired first.  Pairing repeated pages in source order
+    # is deterministic, while a unique matching page can be recognized as moved.
+    by_signature: dict[str, deque[int]] = defaultdict(deque)
+    for j, page in enumerate(new):
+        by_signature[page.signature].append(j)
+    matched: dict[int, int] = {}
+    used: set[int] = set()
+    for i, page in enumerate(old):
+        candidates = by_signature[page.signature]
+        if candidates:
+            j = candidates.popleft()
+            matched[i], used = j, used | {j}
+    # Pair sufficiently similar unmatched pages.  This bounded greedy pass avoids
+    # a large stored matrix and makes every page participate at most once.
+    candidates: list[tuple[float, int, int]] = []
+    for i, left in enumerate(old):
+        if i in matched:
+            continue
+        for j, right in enumerate(new):
+            if j not in used:
+                score = _similarity(left, right)
+                if score >= threshold:
+                    candidates.append((score, i, j))
+    for _score, i, j in sorted(candidates, key=lambda item: (-item[0], abs(item[1] - item[2]), item[1], item[2])):
+        if i not in matched and j not in used:
+            matched[i], used = j, used | {j}
+    # A changed page may have no similarity above the threshold.  When the only
+    # remaining pages are positional counterparts, keep them paired as a change.
+    remaining_old = [i for i in range(len(old)) if i not in matched]
+    remaining_new = [j for j in range(len(new)) if j not in used]
+    if len(remaining_old) == len(remaining_new):
+        for i, j in zip(remaining_old, remaining_new):
+            matched[i], used = j, used | {j}
+    # A changed index alone is not a move: an insertion shifts every later page.
+    # A move is only reported when two matched pages reverse their relative order.
+    inverted: set[int] = set()
+    ordered_matches = sorted(matched.items())
+    for position, (i, j) in enumerate(ordered_matches):
+        for other_i, other_j in ordered_matches[position + 1:]:
+            if j > other_j:
+                inverted.update((i, other_i))
+    keyed: list[tuple[float, PagePair]] = []
+    reverse = {j: i for i, j in matched.items()}
+    for i in range(len(old)):
+        if i in matched:
+            j = matched[i]
+            keyed.append((float(i), PagePair(i, j, moved=i in inverted and old[i].signature == new[j].signature)))
+        else:
+            keyed.append((float(i), PagePair(i, None)))
+    for j in range(len(new)):
+        if j not in used:
+            before = [reverse[k] for k in range(j - 1, -1, -1) if k in reverse]
+            keyed.append(((before[0] + 0.5) if before else -0.5, PagePair(None, j)))
+    return [pair for _, pair in sorted(keyed, key=lambda item: item[0])]
+
+
+def _sequential(old: Sequence[ExtractedPage], new: Sequence[ExtractedPage], threshold: float, lookahead: int) -> list[PagePair]:
+    pairs: list[PagePair] = []
+    i = j = 0
+    while i < len(old) and j < len(new):
+        if _similarity(old[i], new[j]) >= threshold:
+            pairs.append(PagePair(i, j)); i += 1; j += 1; continue
+        new_anchor = next((k for k in range(j + 1, min(len(new), j + lookahead + 1)) if _similarity(old[i], new[k]) >= threshold), None)
+        old_anchor = next((k for k in range(i + 1, min(len(old), i + lookahead + 1)) if _similarity(old[k], new[j]) >= threshold), None)
+        if new_anchor is not None and (old_anchor is None or new_anchor - j <= old_anchor - i):
+            pairs.extend(PagePair(None, k) for k in range(j, new_anchor)); j = new_anchor
+        elif old_anchor is not None:
+            pairs.extend(PagePair(k, None) for k in range(i, old_anchor)); i = old_anchor
+        else:
+            pairs.append(PagePair(i, j)); i += 1; j += 1
+    pairs.extend(PagePair(k, None) for k in range(i, len(old)))
+    pairs.extend(PagePair(None, k) for k in range(j, len(new)))
+    return pairs

smart_pdf_compare/api.py

@@ -0,0 +1,82 @@
+"""The small public comparison API."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from .alignment import AlignmentStrategy, align_pages
+from .diff import compare_words
+from .exceptions import ConfigurationError, MissingTextLayerError
+from .extraction import ExtractedPage, extract_document, open_pdf
+from .normalization import NormalizationOptions
+from .results import ChangeType, ComparisonResult, ComparisonSummary, Difference, _PageMarkup
+
+
+@dataclass(frozen=True)
+class ComparisonOptions:
+    """Options for :func:`compare_pdfs`.
+
+    ``content`` alignment matches equivalent pages wherever they occur;
+    ``sequential`` resynchronizes within ``lookahead`` pages; ``index`` pairs
+    pages by position.  The default is a conservative content strategy.
+    """
+
+    alignment: AlignmentStrategy = "content"
+    similarity_threshold: float = 0.60
+    lookahead: int = 5
+    max_differences: int | None = 1_000
+    normalization: NormalizationOptions = NormalizationOptions()
+
+
+def compare_pdfs(old_pdf: str | Path, new_pdf: str | Path, *, options: ComparisonOptions | None = None) -> ComparisonResult:
+    """Compare two text-based local PDFs and return structured changes.
+
+    Textual identity means all extracted normalized words occur in the same page
+    order.  It does not establish visual or pixel-perfect identity.
+    """
+    settings = options or ComparisonOptions()
+    if settings.max_differences is not None and settings.max_differences < 0:
+        raise ConfigurationError("max_differences must be non-negative or None")
+    with open_pdf(old_pdf) as old_document, open_pdf(new_pdf) as new_document:
+        old_pages = extract_document(old_document, settings.normalization)
+        new_pages = extract_document(new_document, settings.normalization)
+    if not any(page.words for page in old_pages) or not any(page.words for page in new_pages):
+        missing = "original" if not any(page.words for page in old_pages) else "revised"
+        if not any(page.words for page in old_pages) and not any(page.words for page in new_pages):
+            missing = "original and revised"
+        raise MissingTextLayerError(f"No extractable text in {missing} PDF; OCR and visual comparison are not supported.")
+    pairs = align_pages(old_pages, new_pages, settings.alignment, settings.similarity_threshold, settings.lookahead)
+    entries: list[Difference] = []
+    markup: list[_PageMarkup] = []
+    added_pages = removed_pages = moved_pages = modified_pages = added_words = removed_words = 0
+    for pair in pairs:
+        if pair.old is None:
+            page = new_pages[pair.new]  # type: ignore[index]
+            entries.append(Difference(ChangeType.PAGE_ADDED, None, pair.new + 1, "", " ".join(word.text for word in page.words)))
+            markup.append(_PageMarkup(None, pair.new, new_rects=[word.rect for word in page.words], changed=True))
+            added_pages += 1; added_words += len(page.words); continue
+        if pair.new is None:
+            page = old_pages[pair.old]
+            entries.append(Difference(ChangeType.PAGE_REMOVED, pair.old + 1, None, " ".join(word.text for word in page.words), ""))
+            markup.append(_PageMarkup(pair.old, None, old_rects=[word.rect for word in page.words], changed=True))
+            removed_pages += 1; removed_words += len(page.words); continue
+        old_page, new_page = old_pages[pair.old], new_pages[pair.new]
+        word_diff = compare_words(old_page.words, new_page.words, pair.old, pair.new)
+        entries.extend(word_diff.differences)
+        changed = bool(word_diff.differences)
+        markup.append(_PageMarkup(pair.old, pair.new, [old_page.words[index].rect for index in word_diff.old_indexes], [new_page.words[index].rect for index in word_diff.new_indexes], changed))
+        added_words += word_diff.added_words; removed_words += word_diff.removed_words
+        if changed:
+            modified_pages += 1
+        elif pair.moved:
+            entries.append(Difference(ChangeType.PAGE_MOVED, pair.old + 1, pair.new + 1))
+            moved_pages += 1
+    total = len(entries)
+    truncated = settings.max_differences is not None and total > settings.max_differences
+    visible = entries[:settings.max_differences] if truncated else entries
+    summary = ComparisonSummary(len(old_pages), len(new_pages), added_pages, removed_pages, moved_pages, modified_pages, added_words, removed_words, total)
+    warnings = []
+    if any(not page.words for page in old_pages + new_pages):
+        warnings.append("One or more blank or textless pages could not be compared word by word.")
+    return ComparisonResult(not entries, summary, visible, warnings, truncated, markup)

smart_pdf_compare/cli.py

@@ -0,0 +1,51 @@
+"""Command-line interface backed entirely by the public library API."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Sequence
+
+from .api import ComparisonOptions, compare_pdfs
+from .exceptions import PDFComparisonError
+from .highlighting import highlight_differences
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="smart-pdf-compare", description="Compare the extracted text of two PDFs.")
+    parser.add_argument("original", help="original PDF")
+    parser.add_argument("revised", help="revised PDF")
+    parser.add_argument("--alignment", choices=("content", "index", "sequential"), default="content")
+    parser.add_argument("--threshold", type=float, default=0.60, help="page similarity threshold (0..1)")
+    parser.add_argument("--lookahead", type=int, default=5, help="sequential resynchronization window")
+    parser.add_argument("--max-differences", type=int, default=1000)
+    parser.add_argument("--json", dest="json_path", type=Path, help="write JSON result")
+    parser.add_argument("--output-dir", type=Path, help="write highlighted PDFs here")
+    parser.add_argument("--style", choices=("highlight", "box"), default="highlight")
+    parser.add_argument("--report", action="store_true", help="also write a side-by-side report")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        options = ComparisonOptions(args.alignment, args.threshold, args.lookahead, args.max_differences)
+        result = compare_pdfs(args.original, args.revised, options=options)
+        print(json.dumps(result.summary.__dict__, indent=2))
+        print("Textually identical." if result.is_identical else f"{result.summary.differences} difference(s) detected.")
+        if args.json_path:
+            args.json_path.parent.mkdir(parents=True, exist_ok=True)
+            args.json_path.write_text(json.dumps(result.to_dict(), indent=2), encoding="utf-8")
+        if args.output_dir:
+            outputs = highlight_differences(args.original, args.revised, args.output_dir, result=result, style=args.style, include_report=args.report)
+            print(f"Highlighted PDFs: {outputs.original}, {outputs.revised}")
+            if outputs.report:
+                print(f"Difference report: {outputs.report}")
+        return 0 if result.is_identical else 1
+    except (PDFComparisonError, OSError, ValueError) as exc:
+        print(f"error: {exc}")
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

smart_pdf_compare/diff.py

@@ -0,0 +1,53 @@
+"""Word-level diffs with source-coordinate tracking."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+from typing import Sequence
+
+from .extraction import Word
+from .results import ChangeType, Difference
+
+
+@dataclass(frozen=True)
+class WordDiff:
+    differences: list[Difference]
+    old_indexes: list[int]
+    new_indexes: list[int]
+    added_words: int
+    removed_words: int
+
+
+def _text(words: Sequence[Word], start: int, end: int) -> str:
+    return " ".join(word.text for word in words[start:end])
+
+
+def _context(words: Sequence[Word], start: int, end: int) -> str:
+    if not words or start >= len(words):
+        return ""
+    anchor = min(start, len(words) - 1)
+    block, line = words[anchor].block, words[anchor].line
+    return " ".join(word.text for word in words if word.block == block and word.line == line)
+
+
+def compare_words(old: Sequence[Word], new: Sequence[Word], old_page: int, new_page: int) -> WordDiff:
+    """Diff normalized word streams and retain ranges for PDF markup."""
+    matcher = SequenceMatcher(None, [word.normalized for word in old], [word.normalized for word in new], autojunk=False)
+    entries: list[Difference] = []
+    old_indexes: list[int] = []
+    new_indexes: list[int] = []
+    added = removed = 0
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag == "equal":
+            continue
+        if tag == "delete":
+            entries.append(Difference(ChangeType.REMOVED, old_page + 1, new_page + 1, _text(old, i1, i2), "", _context(old, i1, i2), ""))
+            old_indexes.extend(range(i1, i2)); removed += i2 - i1
+        elif tag == "insert":
+            entries.append(Difference(ChangeType.ADDED, old_page + 1, new_page + 1, "", _text(new, j1, j2), "", _context(new, j1, j2)))
+            new_indexes.extend(range(j1, j2)); added += j2 - j1
+        else:
+            entries.append(Difference(ChangeType.REPLACED, old_page + 1, new_page + 1, _text(old, i1, i2), _text(new, j1, j2), _context(old, i1, i2), _context(new, j1, j2)))
+            old_indexes.extend(range(i1, i2)); new_indexes.extend(range(j1, j2))
+            removed += i2 - i1; added += j2 - j1
+    return WordDiff(entries, old_indexes, new_indexes, added, removed)

smart_pdf_compare/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions raised by SmartPDFCompare."""
+
+
+class PDFComparisonError(Exception):
+    """Base class for comparison and output errors."""
+
+
+class InvalidPDFError(PDFComparisonError):
+    """A supplied file is missing, unreadable, or is not a PDF."""
+
+
+class MissingTextLayerError(PDFComparisonError):
+    """A document has no extractable text and cannot be safely compared."""
+
+
+class ConfigurationError(PDFComparisonError):
+    """An unsupported comparison or rendering option was requested."""

smart_pdf_compare/extraction.py

@@ -0,0 +1,59 @@
+"""Extraction of positioned PDF words using PyMuPDF."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Sequence
+
+import pymupdf
+
+from .exceptions import InvalidPDFError
+from .normalization import NormalizationOptions, normalize_token
+
+
+@dataclass(frozen=True)
+class Word:
+    text: str
+    normalized: str
+    rect: tuple[float, float, float, float]
+    block: int
+    line: int
+
+
+@dataclass(frozen=True)
+class ExtractedPage:
+    number: int
+    words: tuple[Word, ...]
+
+    @property
+    def signature(self) -> str:
+        return " ".join(word.normalized for word in self.words if word.normalized)
+
+
+def open_pdf(path: str | Path) -> pymupdf.Document:
+    """Open a local PDF, converting PyMuPDF errors to a public exception."""
+    candidate = Path(path)
+    if not candidate.is_file():
+        raise InvalidPDFError(f"PDF file does not exist: {candidate}")
+    try:
+        document = pymupdf.open(candidate)
+    except (pymupdf.FileDataError, RuntimeError, OSError) as exc:
+        raise InvalidPDFError(f"Cannot read PDF '{candidate}': {exc}") from exc
+    if document.page_count == 0:
+        document.close()
+        raise InvalidPDFError(f"PDF has no pages: {candidate}")
+    return document
+
+
+def extract_document(document: pymupdf.Document, options: NormalizationOptions) -> list[ExtractedPage]:
+    """Extract reading-order words and their coordinates from every page."""
+    pages: list[ExtractedPage] = []
+    for number, page in enumerate(document):
+        raw_words: Sequence[tuple] = page.get_text("words", sort=True)
+        words = tuple(
+            Word(str(item[4]), normalize_token(str(item[4]), options), tuple(float(v) for v in item[:4]), int(item[5]), int(item[6]))
+            for item in raw_words
+            if str(item[4]).strip()
+        )
+        pages.append(ExtractedPage(number, words))
+    return pages

smart_pdf_compare/highlighting.py

@@ -0,0 +1,107 @@
+"""Safe highlighted-copy and side-by-side PDF generation."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import pymupdf
+
+from .api import ComparisonOptions, compare_pdfs
+from .exceptions import ConfigurationError
+from .results import ComparisonResult, _PageMarkup
+
+HighlightStyle = Literal["highlight", "box"]
+
+
+@dataclass(frozen=True)
+class HighlightOutputs:
+    original: Path
+    revised: Path
+    report: Path | None = None
+
+
+def _validate_style(style: HighlightStyle) -> None:
+    if style not in ("highlight", "box"):
+        raise ConfigurationError("style must be 'highlight' or 'box'")
+
+
+def _annotate(page: pymupdf.Page, rects: list[tuple[float, float, float, float]], color: tuple[float, float, float], style: HighlightStyle) -> None:
+    for coords in rects:
+        rect = pymupdf.Rect(coords) & page.rect
+        if rect.is_empty or rect.is_infinite:
+            continue
+        annot = page.add_highlight_annot(rect) if style == "highlight" else page.add_rect_annot(rect)
+        annot.set_colors(stroke=color)
+        if style == "box":
+            annot.set_border(width=1.2)
+        annot.update(opacity=0.45)
+
+
+def highlight_differences(old_pdf: str | Path, new_pdf: str | Path, output_dir: str | Path, *, result: ComparisonResult | None = None, options: ComparisonOptions | None = None, style: HighlightStyle = "highlight", include_report: bool = False, removed_color: tuple[float, float, float] = (1, 0.2, 0.2), added_color: tuple[float, float, float] = (0.1, 0.65, 0.2)) -> HighlightOutputs:
+    """Write highlighted copies without modifying either source PDF."""
+    _validate_style(style)
+    comparison = result or compare_pdfs(old_pdf, new_pdf, options=options)
+    target = Path(output_dir); target.mkdir(parents=True, exist_ok=True)
+    old_output, new_output = target / "original_highlighted.pdf", target / "revised_highlighted.pdf"
+    with pymupdf.open(old_pdf) as old_document, pymupdf.open(new_pdf) as new_document:
+        for mark in comparison._markup:
+            if mark.old_page is not None:
+                _annotate(old_document[mark.old_page], mark.old_rects, removed_color, style)
+            if mark.new_page is not None:
+                _annotate(new_document[mark.new_page], mark.new_rects, added_color, style)
+        old_document.save(old_output, garbage=4, deflate=True)
+        new_document.save(new_output, garbage=4, deflate=True)
+    # Reopen output now: callers never receive a corrupt path silently.
+    with pymupdf.open(old_output), pymupdf.open(new_output):
+        pass
+    report = create_side_by_side_report(old_pdf, new_pdf, comparison, target / "difference_report.pdf", removed_color, added_color) if include_report and not comparison.is_identical else None
+    return HighlightOutputs(old_output, new_output, report)
+
+
+def create_side_by_side_report(old_pdf: str | Path, new_pdf: str | Path, result: ComparisonResult, output_path: str | Path, removed_color: tuple[float, float, float] = (1, 0.2, 0.2), added_color: tuple[float, float, float] = (0.1, 0.65, 0.2)) -> Path | None:
+    """Create a report containing only changed page pairs; return None if equal."""
+    changed = [mark for mark in result._markup if mark.changed]
+    if not changed:
+        return None
+    destination = Path(output_path); destination.parent.mkdir(parents=True, exist_ok=True)
+    report = pymupdf.open()
+    try:
+        with pymupdf.open(old_pdf) as old_document, pymupdf.open(new_pdf) as new_document:
+            for mark in changed:
+                old_page = old_document[mark.old_page] if mark.old_page is not None else None
+                new_page = new_document[mark.new_page] if mark.new_page is not None else None
+                old_width = old_page.rect.width if old_page else 300
+                new_width = new_page.rect.width if new_page else 300
+                height = max(old_page.rect.height if old_page else 200, new_page.rect.height if new_page else 200) + 28
+                page = report.new_page(width=old_width + new_width, height=height)
+                left = pymupdf.Rect(0, 28, old_width, height)
+                right = pymupdf.Rect(old_width, 28, old_width + new_width, height)
+                page.insert_text((6, 18), f"Original page {mark.old_page + 1}" if old_page else "Original: no matching page", fontsize=10)
+                page.insert_text((old_width + 6, 18), f"Revised page {mark.new_page + 1}" if new_page else "Revised: no matching page", fontsize=10)
+                if old_page:
+                    page.show_pdf_page(left, old_document, mark.old_page)
+                    for rect in mark.old_rects:
+                        source = pymupdf.Rect(rect)
+                        page.draw_rect(
+                            pymupdf.Rect(source.x0, source.y0 + 28, source.x1, source.y1 + 28),
+                            color=removed_color,
+                            width=1.2,
+                            overlay=True,
+                        )
+                if new_page:
+                    page.show_pdf_page(right, new_document, mark.new_page)
+                    for rect in mark.new_rects:
+                        source = pymupdf.Rect(rect)
+                        page.draw_rect(
+                            pymupdf.Rect(source.x0 + old_width, source.y0 + 28, source.x1 + old_width, source.y1 + 28),
+                            color=added_color,
+                            width=1.2,
+                            overlay=True,
+                        )
+        report.save(destination, garbage=4, deflate=True)
+    finally:
+        report.close()
+    with pymupdf.open(destination):
+        pass
+    return destination

smart_pdf_compare/normalization.py

@@ -0,0 +1,39 @@
+"""Conservative normalization applied only to comparison tokens."""
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class NormalizationOptions:
+    """Policy for comparison tokens.
+
+    Punctuation is retained by default: removing it can hide meaningful values
+    such as ``1.2`` versus ``12``.  Original PDF text is never altered.
+    """
+
+    ignore_case: bool = True
+    ignore_punctuation: bool = False
+
+
+_DASHES = str.maketrans({
+    "\u2010": "-", "\u2011": "-", "\u2012": "-", "\u2013": "-", "\u2014": "-", "\u2212": "-",
+})
+_PUNCTUATION = re.compile(r"[^\w\s'-]", re.UNICODE)
+
+
+def normalize_token(text: str, options: NormalizationOptions = NormalizationOptions()) -> str:
+    """Return a comparison key while preserving numeric signs and contractions."""
+    value = unicodedata.normalize("NFKC", text).translate(_DASHES).replace("\u00a0", " ").strip()
+    if options.ignore_case:
+        value = value.casefold()
+    if options.ignore_punctuation:
+        value = _PUNCTUATION.sub("", value)
+    return value
+
+
+def normalized_text(words: list[str], options: NormalizationOptions) -> str:
+    """Create a stable page signature from extracted words."""
+    return " ".join(token for word in words if (token := normalize_token(word, options)))

smart_pdf_compare/results.py

@@ -0,0 +1,74 @@
+"""Public, JSON-friendly comparison result models."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class ChangeType(str, Enum):
+    ADDED = "added"
+    REMOVED = "removed"
+    REPLACED = "replaced"
+    PAGE_ADDED = "page_added"
+    PAGE_REMOVED = "page_removed"
+    PAGE_MOVED = "page_moved"
+
+
+@dataclass(frozen=True)
+class Difference:
+    """A readable text or page-level difference (page numbers are one-based)."""
+
+    change_type: ChangeType
+    old_page: Optional[int]
+    new_page: Optional[int]
+    old_text: str = ""
+    new_text: str = ""
+    old_context: str = ""
+    new_context: str = ""
+
+
+@dataclass(frozen=True)
+class ComparisonSummary:
+    old_pages: int
+    new_pages: int
+    added_pages: int
+    removed_pages: int
+    moved_pages: int
+    modified_pages: int
+    added_words: int
+    removed_words: int
+    differences: int
+
+
+@dataclass
+class _PageMarkup:
+    """Internal coordinate data shared by comparison and rendering."""
+
+    old_page: Optional[int]
+    new_page: Optional[int]
+    old_rects: list[tuple[float, float, float, float]] = field(default_factory=list)
+    new_rects: list[tuple[float, float, float, float]] = field(default_factory=list)
+    changed: bool = False
+
+
+@dataclass
+class ComparisonResult:
+    """Structured result of :func:`smart_pdf_compare.compare_pdfs`."""
+
+    is_identical: bool
+    summary: ComparisonSummary
+    differences: list[Difference]
+    warnings: list[str] = field(default_factory=list)
+    truncated: bool = False
+    _markup: list[_PageMarkup] = field(default_factory=list, repr=False)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return JSON-compatible data without internal geometry."""
+        return {
+            "is_identical": self.is_identical,
+            "summary": asdict(self.summary),
+            "differences": [{**asdict(item), "change_type": item.change_type.value} for item in self.differences],
+            "warnings": list(self.warnings),
+            "truncated": self.truncated,
+        }

smart_pdf_compare-0.1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: smart-pdf-compare
+Version: 0.1.0
+Summary: Text-aware PDF comparison, highlighting, and reports.
+Project-URL: Homepage, https://github.com/SmartPDFCompare/SmartPDFCompare
+Project-URL: Issues, https://github.com/SmartPDFCompare/SmartPDFCompare/issues
+Author-email: Abdelrahman Elsheikh <abdelrahmanelsheikh39@gmail.com>
+Maintainer-email: Abdelrahman Elsheikh <abdelrahmanelsheikh39@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: comparison,diff,pdf,pymupdf
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: pymupdf>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <a href="https://github.com/SmartPDFCompare/SmartPDFCompare">
+    <img src="https://raw.githubusercontent.com/SmartPDFCompare/SmartPDFCompare/main/docs/assets/cover.svg" alt="SmartPDFCompare" width="760">
+  </a>
+  <br>
+  <a href="https://github.com/SmartPDFCompare/SmartPDFCompare">
+    <img src="https://readme-typing-svg.demolab.com?font=Inter&weight=700&size=25&duration=3200&pause=900&color=2563EB&center=true&vCenter=true&width=650&lines=Find+the+words+that+changed+in+your+PDFs;Compare.+Highlight.+Review." alt="Animated SmartPDFCompare introduction">
+  </a>
+  <br><br>
+  <a href="https://github.com/SmartPDFCompare/SmartPDFCompare/actions/workflows/tests.yml"><img src="https://github.com/SmartPDFCompare/SmartPDFCompare/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <a href="https://pypi.org/project/smart-pdf-compare/"><img src="https://img.shields.io/pypi/v/smart-pdf-compare.svg?color=2563eb" alt="PyPI"></a>
+  <a href="https://pypi.org/project/smart-pdf-compare/"><img src="https://img.shields.io/pypi/pyversions/smart-pdf-compare.svg" alt="Supported Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2563eb.svg" alt="MIT license"></a>
+  <a href="https://pymupdf.readthedocs.io/en/latest/"><img src="https://img.shields.io/badge/powered%20by-PyMuPDF%202-16a34a.svg" alt="Powered by PyMuPDF 2"></a>
+</div>
+
+<p align="center">
+  <a href="#quick-start"><strong>Quick start</strong></a> ·
+  <a href="#features"><strong>Features</strong></a> ·
+  <a href="#command-line"><strong>CLI</strong></a> ·
+  <a href="docs/api.md"><strong>API</strong></a> ·
+  <a href="docs/architecture.md"><strong>Architecture</strong></a> ·
+  <a href="#limitations"><strong>Limitations</strong></a>
+</p>
+
+**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.
+
+> [!IMPORTANT]
+> SmartPDFCompare uses the current [PyMuPDF 2](https://pymupdf.readthedocs.io/en/latest/) API exclusively: `import pymupdf`.
+
+## Features
+
+- **[Structured comparison](docs/api.md)** — added, removed, replaced, added-page, removed-page, and moved-page records with JSON serialization.
+- **[Unicode-aware text extraction](https://pymupdf.readthedocs.io/en/latest/textpage.html)** — PyMuPDF word coordinates, NFKC normalization, case folding, ligatures, NBSPs, and dash/minus variants.
+- **[Practical page alignment](docs/architecture.md)** — content matching for inserted/moved pages, bounded sequential look-ahead, and index-by-index comparison.
+- **[Visual review](#highlighted-output)** — native PDF highlights or boxes in safe output copies; optional side-by-side report pages.
+- **[Small CLI](#command-line)** — terminal summary, JSON result, highlighted output, report, alignment policy, and style controls.
+
+## Install
+
+```bash
+python -m pip install --upgrade smart-pdf-compare
+```
+
+The package tracks the current major [PyMuPDF](https://pypi.org/project/PyMuPDF/) release. Create a virtual environment first for a predictable setup:
+
+```bash
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+# macOS/Linux: source .venv/bin/activate
+python -m pip install --upgrade smart-pdf-compare
+```
+
+## Quick start
+
+```python
+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
+
+```python
+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
+
+<table>
+  <tr>
+    <td width="50%"><strong>Original</strong><br>Removed or replaced text receives red markup.</td>
+    <td width="50%"><strong>Revised</strong><br>Added or replaced text receives green markup.</td>
+  </tr>
+  <tr>
+    <td><code>original_highlighted.pdf</code></td>
+    <td><code>revised_highlighted.pdf</code></td>
+  </tr>
+</table>
+
+Use real PDF annotations by default, or boxes where highlights are not desired:
+
+```python
+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
+
+```python
+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,
+    ),
+)
+```
+
+| Strategy | Best for | Trade-off |
+| --- | --- | --- |
+| `content` | Documents with inserted, deleted, or moved pages | Greedy matching; not globally optimal for highly repetitive pages. |
+| `sequential` | Mostly ordered revisions | Resynchronizes only inside `lookahead`. |
+| `index` | Stable page-for-page documents | An insertion can make later pages appear modified. |
+
+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
+
+```bash
+smart-pdf-compare original.pdf revised.pdf \
+  --alignment content \
+  --output-dir diff-output \
+  --style highlight \
+  --report \
+  --json diff-output/comparison.json
+```
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Textually identical under the chosen policy. |
+| `1` | Changes were found. |
+| `2` | Input, extraction, or configuration error. |
+
+## 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](https://pymupdf.readthedocs.io/en/latest/about.html#license-and-copyright). Confirm that its license is appropriate for your use case.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+Read the [contribution guide](CONTRIBUTING.md), [public API](docs/api.md), [architecture notes](docs/architecture.md), and [changelog](CHANGELOG.md). Before publishing, verify availability of `smart-pdf-compare` on [PyPI](https://pypi.org/), upload to TestPyPI, install the artifact in a clean environment, and use [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) for the production release.
+
+## License
+
+SmartPDFCompare’s own source code is licensed under the [MIT License](LICENSE). Its PyMuPDF dependency has separate licensing, described above.
+
+---
+
+<div align="center"><sub>Built for clear, reviewable PDF changes.</sub></div>

smart_pdf_compare-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+smart_pdf_compare/__init__.py,sha256=B2IySKWiBJB55BCqkZurBHv-6SJ848AJAy5QO8dHe5o,790
+smart_pdf_compare/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+smart_pdf_compare/alignment.py,sha256=4IHmwCG8NZuqOjRWnfFTFr8-Vs_65feFQZquXdrUWSY,5834
+smart_pdf_compare/api.py,sha256=jNoxi3Bjg-lzmY65tbYxhRqD2NKKTQ8RUCCPQCKha9Q,4743
+smart_pdf_compare/cli.py,sha256=a1ABlEivm7xmIJsEHVwsEqp--JnlRZ0B3Yc8gG0Un9c,2595
+smart_pdf_compare/diff.py,sha256=QNTMS6R6KMrnR98hZzHxUtaQDkm13yRvQOlCl5y9dKg,2258
+smart_pdf_compare/exceptions.py,sha256=adP1IPAcEsBWGoPBgt4VZ75-s1tfUhc8ilWN_xTQGG8,496
+smart_pdf_compare/extraction.py,sha256=sU8BhgxGyjR2NzZG-mqus7YW-ty2qQF94e01t5fZPd8,1908
+smart_pdf_compare/highlighting.py,sha256=ODLO2uksbbTb2HOFkuRBQzjPmOkWASzFrtGISOTrw3M,5703
+smart_pdf_compare/normalization.py,sha256=hh5NaQxAdcw8x9S_gAmopaj2g6vaXjV_SC9mL6sSQqw,1329
+smart_pdf_compare/results.py,sha256=Kg3PoeLxDn8tnuBEBOc7M_hVMJ6O2lipXaBCbInKk3o,2079
+smart_pdf_compare-0.1.0.dist-info/METADATA,sha256=QS356Vho3M_Ppw3tqmPDZgWGH1YMVPuHVFM_3mCERhE,8891
+smart_pdf_compare-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+smart_pdf_compare-0.1.0.dist-info/entry_points.txt,sha256=OETfOM0vKdOPKoBEDr7J0hYVmp5olIDdDB8QxBReEkM,65
+smart_pdf_compare-0.1.0.dist-info/licenses/LICENSE,sha256=Hki__28Lzr-1-YjVCQANQbiNidDlqN3nCS-JrmoYYuY,1085
+smart_pdf_compare-0.1.0.dist-info/RECORD,,

smart_pdf_compare-0.1.0.dist-info/WHEEL

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

smart_pdf_compare-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+smart-pdf-compare = smart_pdf_compare.cli:main

smart_pdf_compare-0.1.0.dist-info/licenses/LICENSE

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