pdfedit 0.1.0__py3-none-any.whl

pdfedit/__init__.py

@@ -0,0 +1,4 @@
+"""pdfedit — find and edit any text in a PDF, matching the original
+font, size, and color."""
+
+__version__ = "0.1.0"

pdfedit/__main__.py

@@ -0,0 +1,4 @@
+from pdfedit.cli import main
+
+if __name__ == "__main__":
+    main()

pdfedit/cli.py

@@ -0,0 +1,252 @@
+"""CLI entry point: inspect / edit / batch subcommands."""
+
+import argparse
+import getpass
+import json
+import sys
+from pathlib import Path
+
+import pymupdf
+
+from pdfedit.engine import EditEngine
+from pdfedit.model import extract_spans, is_scanned_page
+
+
+def _open_doc(path: str) -> pymupdf.Document:
+    doc = pymupdf.open(path)
+    if doc.needs_pass:
+        for _ in range(3):
+            password = getpass.getpass(f"'{path}' is encrypted. Password: ")
+            if doc.authenticate(password):
+                break
+        else:
+            print("error: could not authenticate to encrypted PDF", file=sys.stderr)
+            sys.exit(1)
+    return doc
+
+
+def _warn_scanned_pages(doc: pymupdf.Document) -> None:
+    for page_index in range(len(doc)):
+        if is_scanned_page(doc, page_index):
+            print(
+                f"warning: page {page_index + 1} appears to be scanned "
+                "(no text layer) — OCR is out of scope, spans on this page "
+                "will be empty",
+                file=sys.stderr,
+            )
+
+
+def _truncate(text: str, width: int = 40) -> str:
+    text = text.replace("\n", "\\n")
+    if len(text) > width:
+        return text[: width - 1] + "…"
+    return text
+
+
+def _print_span_table(spans: list) -> None:
+    if not spans:
+        print("No text spans found in this document.")
+        return
+    header = f"{'ID':<16} {'PG':>3} {'FONT':<22} {'SIZE':>5} {'COLOR':>8} {'STY':<4} TEXT"
+    print(header)
+    print("-" * len(header))
+    for s in spans:
+        color_hex = f"#{s.color:06x}"
+        print(
+            f"{s.id:<16} {s.page:>3} {s.font:<22} {s.size:>5.1f} "
+            f"{color_hex:>8} {s.style.short_label():<4} {_truncate(s.text)}"
+        )
+    print(f"\n{len(spans)} span(s).")
+
+
+def cmd_inspect(args: argparse.Namespace) -> None:
+    doc = _open_doc(args.file)
+    _warn_scanned_pages(doc)
+    spans = extract_spans(doc)
+    _print_span_table(spans)
+
+
+def cmd_edit(args: argparse.Namespace) -> None:
+    doc = _open_doc(args.file)
+    _warn_scanned_pages(doc)
+    engine = EditEngine(doc)
+
+    if not engine.spans:
+        print("No text spans found in this document.")
+        return
+
+    output_path = str(Path(args.file).with_name(Path(args.file).stem + "_edited.pdf"))
+
+    print(f"Loaded {len(engine.spans)} span(s). Commands:")
+    print("  <span id>   start editing that span")
+    print("  list        show all spans again")
+    print("  queue       show queued edits")
+    print("  save        apply all queued edits and write output, then exit")
+    print("  quit        exit without saving")
+
+    while True:
+        try:
+            command = input("\npdfedit> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nquit (nothing saved)")
+            return
+
+        if not command:
+            continue
+        if command in ("quit", "exit"):
+            print("quit (nothing saved)")
+            return
+        if command == "list":
+            _print_span_table(engine.spans)
+            continue
+        if command == "queue":
+            if not engine.queue:
+                print("(no edits queued)")
+            for span_id, queued in engine.queue.items():
+                print(f"  {span_id}: {_truncate(queued.span.text)!r} -> {_truncate(queued.new_text)!r}")
+            continue
+        if command == "save":
+            if not engine.queue:
+                print("No edits queued, nothing to save.")
+                continue
+            warnings = engine.apply_all()
+            for w in warnings:
+                print(f"warning: {w}", file=sys.stderr)
+            engine.save(output_path)
+            print(f"Saved {output_path}")
+            return
+
+        span = engine.get_span(command)
+        if span is None:
+            print(f"No span with ID '{command}' (try 'list').")
+            continue
+
+        print(f"Current text: {span.text!r}")
+        print(f"Font: {span.font}  Size: {span.size:.1f}  Color: #{span.color:06x}")
+        try:
+            new_text = input("New text (blank to cancel): ")
+        except (EOFError, KeyboardInterrupt):
+            print("\ncancelled")
+            continue
+        if new_text == "":
+            print("cancelled")
+            continue
+
+        preview = engine.queue_edit(span.id, new_text)
+        font_kind = "embedded" if preview.embedded else "Base-14 fallback"
+        size_note = f"{preview.font_size:.1f}pt" if preview.shrunk else f"{preview.font_size:.1f}pt (unchanged)"
+        print(f"Before: {preview.span.text!r}")
+        print(f"After:  {preview.new_text!r}  (font: {preview.font_alias}, {font_kind}, size: {size_note})")
+        if preview.shrunk:
+            print(f"note: text was auto-shrunk from {span.size:.1f}pt to fit the original box")
+        if not preview.fits:
+            print("warning: replacement text still overflows the original box "
+                  "even at the minimum autofit size")
+        print("Queued.")
+
+
+def _validate_batch_entries(engine: EditEngine, edits_data: list) -> list:
+    errors = []
+    for i, entry in enumerate(edits_data):
+        if not isinstance(entry, dict):
+            errors.append(f"entry {i}: must be an object, got {type(entry).__name__}")
+            continue
+        has_id = "id" in entry
+        has_find = "find" in entry
+        if has_id == has_find:
+            errors.append(f"entry {i}: must have exactly one of 'id' or 'find'")
+            continue
+        if "new_text" not in entry or not isinstance(entry["new_text"], str):
+            errors.append(f"entry {i}: missing/invalid 'new_text' (must be a string)")
+            continue
+        if has_id:
+            if not isinstance(entry["id"], str) or not entry["id"]:
+                errors.append(f"entry {i}: 'id' must be a non-empty string")
+            elif engine.get_span(entry["id"]) is None:
+                errors.append(f"entry {i}: no span with id '{entry['id']}'")
+        else:
+            if not isinstance(entry["find"], str) or not entry["find"]:
+                errors.append(f"entry {i}: 'find' must be a non-empty string")
+    return errors
+
+
+def cmd_batch(args: argparse.Namespace) -> None:
+    doc = _open_doc(args.file)
+    _warn_scanned_pages(doc)
+    engine = EditEngine(doc)
+
+    try:
+        with open(args.edits_json) as f:
+            edits_data = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"error: could not read '{args.edits_json}': {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(edits_data, list):
+        print("error: edits JSON must be a list of edit objects", file=sys.stderr)
+        sys.exit(1)
+    if not edits_data:
+        print("No edits in file, nothing to do.")
+        return
+
+    # Validate everything up front; abort without touching anything if any
+    # entry is invalid, rather than silently writing a half-applied PDF.
+    errors = _validate_batch_entries(engine, edits_data)
+    if errors:
+        print(
+            f"error: {len(errors)} invalid edit(s) in '{args.edits_json}', nothing saved:",
+            file=sys.stderr,
+        )
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        sys.exit(1)
+
+    unmatched_finds = []
+    for entry in edits_data:
+        if "id" in entry:
+            engine.queue_edit(entry["id"], entry["new_text"])
+        else:
+            previews = engine.queue_find_replace(entry["find"], entry["new_text"])
+            if not previews:
+                unmatched_finds.append(entry["find"])
+
+    for find in unmatched_finds:
+        print(f"warning: no span found containing {find!r}", file=sys.stderr)
+
+    warnings = engine.apply_all()
+    for w in warnings:
+        print(f"warning: {w}", file=sys.stderr)
+
+    output_path = str(Path(args.file).with_name(Path(args.file).stem + "_edited.pdf"))
+    engine.save(output_path)
+    print(f"Applied {len(edits_data)} edit(s). Saved {output_path}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pdfedit", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_inspect = sub.add_parser("inspect", help="read-only dump of every text span")
+    p_inspect.add_argument("file")
+    p_inspect.set_defaults(func=cmd_inspect)
+
+    p_edit = sub.add_parser("edit", help="interactive edit REPL")
+    p_edit.add_argument("file")
+    p_edit.set_defaults(func=cmd_edit)
+
+    p_batch = sub.add_parser("batch", help="apply a JSON list of edits non-interactively")
+    p_batch.add_argument("file")
+    p_batch.add_argument("edits_json")
+    p_batch.set_defaults(func=cmd_batch)
+
+    return parser
+
+
+def main(argv: list | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

pdfedit/engine.py

@@ -0,0 +1,218 @@
+"""Redaction & replacement engine: apply queued span edits to a document.
+
+White-fill redaction (background sampling is M6). Overflow that can't be
+solved by autofit is warned about, not silently swallowed.
+"""
+
+from dataclasses import dataclass
+
+import pymupdf
+
+from pdfedit.fonts import FontResolver
+from pdfedit.model import Span, extract_spans
+
+# Placeholder fill until M6 adds real background-color sampling.
+_DEFAULT_FILL = (1, 1, 1)
+
+# Autofit: never shrink a span below this fraction of its original size —
+# past that point the text reads as visibly wrong-sized rather than a
+# faithful edit, so we stop and warn instead.
+_AUTOFIT_MIN_RATIO = 0.6
+# Slight safety margin so a shrunk size doesn't land exactly on the boundary
+# and overflow by a rounding hair.
+_AUTOFIT_SAFETY = 0.98
+
+
+def _fit_font_size(font: pymupdf.Font, text: str, original_size: float, max_width: float) -> tuple:
+    """Return (chosen_size, fits) for drawing `text` in `font` within
+    max_width, starting from original_size and shrinking only as far as
+    needed (down to _AUTOFIT_MIN_RATIO of original_size). Glyph advance
+    widths scale linearly with font size for a fixed font, so the required
+    size can be computed directly rather than stepped iteratively."""
+    width = font.text_length(text, fontsize=original_size)
+    if width <= max_width:
+        return original_size, True
+
+    per_point_width = font.text_length(text, fontsize=1.0)
+    min_size = original_size * _AUTOFIT_MIN_RATIO
+    if per_point_width <= 0:
+        return original_size, False
+
+    needed_size = (max_width / per_point_width) * _AUTOFIT_SAFETY
+    chosen_size = max(needed_size, min_size)
+    fits = font.text_length(text, fontsize=chosen_size) <= max_width
+    return chosen_size, fits
+
+
+# A clamp is only applied if the overlap it needs to cut away is less than
+# this fraction of the redaction rect's extent on that axis. Past that, the
+# neighbor's box isn't merely metric-adjacent to the target — it genuinely
+# straddles or contains it (a big heading whose ascent/descent box spans a
+# small line sitting in its whitespace, multi-size spans on one line, etc.).
+# Clamping there would invert the rect to empty and redact nothing, leaving
+# the old glyphs under the new text. Better to redact the full box and
+# accept the small over-redaction risk (in practice apply_redactions leaves
+# a non-overlapping neighbor's glyphs alone).
+_MAX_CLAMP_FRACTION = 0.5
+
+
+def _shrink_to_avoid(rect: pymupdf.Rect, other_bbox: tuple) -> None:
+    """Shrink rect in place so it no longer overlaps other_bbox. PyMuPDF's
+    apply_redactions() removes an entire text-drawing operation if the
+    redaction rectangle overlaps it AT ALL — and span bboxes from
+    get_text("dict") use full font ascent/descent metrics, which routinely
+    overlap a couple points into a vertically adjacent line on tight
+    line-spacing even though the glyphs themselves never touch. Without
+    this, redacting one span can silently erase an untouched neighboring
+    line. We clamp along whichever axis has the shallower intrusion, since
+    that's the axis where the two boxes are merely adjacent rather than
+    truly overlapping — but only when the cut stays under
+    _MAX_CLAMP_FRACTION of the rect (see the constant)."""
+    ox0, oy0, ox1, oy1 = other_bbox
+    ix0, ix1 = max(rect.x0, ox0), min(rect.x1, ox1)
+    iy0, iy1 = max(rect.y0, oy0), min(rect.y1, oy1)
+    if ix0 >= ix1 or iy0 >= iy1:
+        return  # no overlap
+    x_overlap, y_overlap = ix1 - ix0, iy1 - iy0
+    if y_overlap <= x_overlap:
+        if y_overlap >= _MAX_CLAMP_FRACTION * rect.height:
+            return
+        if oy0 < (rect.y0 + rect.y1) / 2:
+            rect.y0 = max(rect.y0, oy1)
+        else:
+            rect.y1 = min(rect.y1, oy0)
+    else:
+        if x_overlap >= _MAX_CLAMP_FRACTION * rect.width:
+            return
+        if ox0 < (rect.x0 + rect.x1) / 2:
+            rect.x0 = max(rect.x0, ox1)
+        else:
+            rect.x1 = min(rect.x1, ox0)
+
+
+@dataclass
+class QueuedEdit:
+    span: Span
+    new_text: str
+    font_size: float  # autofit-resolved size to actually draw with
+
+
+@dataclass
+class EditPreview:
+    span: Span
+    new_text: str
+    font_alias: str
+    embedded: bool
+    font_size: float  # autofit-resolved size (== span.size if it already fit)
+    shrunk: bool
+    fits: bool
+
+
+class EditEngine:
+    """Holds an open document, its spans, and a queue of pending edits."""
+
+    def __init__(self, doc: pymupdf.Document):
+        self.doc = doc
+        self.resolver = FontResolver(doc)
+        self.spans: list[Span] = extract_spans(doc)
+        self._spans_by_id: dict[str, Span] = {s.id: s for s in self.spans}
+        self.queue: dict[str, QueuedEdit] = {}  # keyed by span id
+
+    def get_span(self, span_id: str) -> Span | None:
+        return self._spans_by_id.get(span_id)
+
+    def preview(self, span: Span, new_text: str) -> EditPreview:
+        resolution = self.resolver.resolve(span)
+        font = self.resolver.font_object(resolution)
+        old_width = span.bbox[2] - span.bbox[0]
+        font_size, fits = _fit_font_size(font, new_text, span.size, old_width)
+        return EditPreview(
+            span=span,
+            new_text=new_text,
+            font_alias=resolution.alias,
+            embedded=resolution.embedded,
+            font_size=font_size,
+            shrunk=font_size < span.size - 1e-6,
+            fits=fits,
+        )
+
+    def queue_edit(self, span_id: str, new_text: str) -> EditPreview | None:
+        span = self.get_span(span_id)
+        if span is None:
+            return None
+        preview = self.preview(span, new_text)
+        self.queue[span_id] = QueuedEdit(span=span, new_text=new_text, font_size=preview.font_size)
+        return preview
+
+    def unqueue(self, span_id: str) -> bool:
+        return self.queue.pop(span_id, None) is not None
+
+    def current_text(self, span: Span) -> str:
+        """The span's text as it would be if applied right now: the
+        already-queued replacement if one exists, else its original text."""
+        queued = self.queue.get(span.id)
+        return queued.new_text if queued is not None else span.text
+
+    def queue_find_replace(self, find: str, replacement: str) -> list[EditPreview]:
+        """Find every span whose current text contains `find` and queue an
+        edit replacing that substring with `replacement`, preserving the
+        rest of the span's text. Chains against already-queued edits (by
+        current_text) so multiple find/replace entries targeting the same
+        span in one batch compose in order instead of clobbering each
+        other."""
+        previews = []
+        for span in self.spans:
+            text = self.current_text(span)
+            if find in text:
+                preview = self.queue_edit(span.id, text.replace(find, replacement))
+                previews.append(preview)
+        return previews
+
+    def apply_all(self) -> list[str]:
+        """Apply every queued edit to self.doc in place. Returns a list of
+        warning strings (overflow, font fallback) collected along the way."""
+        warnings: list[str] = list(self.resolver.warnings)
+        edits_by_page: dict[int, list[QueuedEdit]] = {}
+        for edit in self.queue.values():
+            edits_by_page.setdefault(edit.span.page - 1, []).append(edit)
+
+        for page_index, edits in edits_by_page.items():
+            page = self.doc[page_index]
+            edited_ids = {edit.span.id for edit in edits}
+            other_spans = [
+                s for s in self.spans if s.page - 1 == page_index and s.id not in edited_ids
+            ]
+
+            for edit in edits:
+                rect = pymupdf.Rect(edit.span.bbox)
+                for other in other_spans:
+                    _shrink_to_avoid(rect, other.bbox)
+                page.add_redact_annot(rect, fill=_DEFAULT_FILL)
+            page.apply_redactions(images=pymupdf.PDF_REDACT_IMAGE_NONE)
+
+            by_color: dict[tuple, list[QueuedEdit]] = {}
+            for edit in edits:
+                by_color.setdefault(edit.span.color_rgb01(), []).append(edit)
+
+            for color, group in by_color.items():
+                tw = pymupdf.TextWriter(page.rect)
+                for edit in group:
+                    resolution = self.resolver.resolve(edit.span)
+                    font = self.resolver.font_object(resolution)
+                    old_width = edit.span.bbox[2] - edit.span.bbox[0]
+                    final_width = font.text_length(edit.new_text, fontsize=edit.font_size)
+                    if final_width > old_width:
+                        warnings.append(
+                            f"{edit.span.id}: replacement text still overflows original "
+                            f"box at the minimum autofit size "
+                            f"({edit.font_size:.1f}pt, {_AUTOFIT_MIN_RATIO:.0%} of original "
+                            f"{edit.span.size:.1f}pt) — {final_width:.1f}pt > {old_width:.1f}pt"
+                        )
+                    tw.append(edit.span.origin, edit.new_text, font=font, fontsize=edit.font_size)
+                tw.write_text(page, color=color)
+
+        self.queue.clear()
+        return warnings
+
+    def save(self, output_path: str) -> None:
+        self.doc.save(output_path)

pdfedit/fonts.py

@@ -0,0 +1,152 @@
+"""Font resolution engine: for a given span, find the exact embedded font
+program if available, otherwise fall back to the closest Base-14 font based
+on the span's style flags. Resolutions are cached per unique source font
+name so extraction only happens once per document."""
+
+import re
+from dataclasses import dataclass
+
+import pymupdf
+
+from pdfedit.model import Span, SpanStyle
+
+# PyMuPDF's reserved Base-14 font aliases (usable directly as `fontname=`
+# in insert_text/insert_textbox without registering anything).
+_BASE14_HELVETICA = {
+    (False, False): "helv",
+    (True, False): "hebo",
+    (False, True): "heit",
+    (True, True): "hebi",
+}
+_BASE14_TIMES = {
+    (False, False): "tiro",
+    (True, False): "tibo",
+    (False, True): "tiit",
+    (True, True): "tibi",
+}
+_BASE14_COURIER = {
+    (False, False): "cour",
+    (True, False): "cobo",
+    (False, True): "coit",
+    (True, True): "cobi",
+}
+
+# extract_font() ext values that insert_font(fontbuffer=...) can reliably
+# consume. Type1 ("n/a" for standard fonts, "pfb"/"cff" bare for embedded
+# Type1) and Type3 fonts are not safe to reuse this way.
+_SUPPORTED_EMBEDDED_EXTS = {"ttf", "otf"}
+
+_ALIAS_SANITIZE_RE = re.compile(r"[^A-Za-z0-9]+")
+
+
+def base14_alias(style: SpanStyle) -> str:
+    """Pick the closest Base-14 font alias for a span's style flags."""
+    key = (style.bold, style.italic)
+    if style.monospace:
+        return _BASE14_COURIER[key]
+    if style.serif:
+        return _BASE14_TIMES[key]
+    return _BASE14_HELVETICA[key]
+
+
+@dataclass
+class FontResolution:
+    alias: str  # cache key / label, not used directly for text insertion
+    embedded: bool
+    fontbuffer: bytes | None = None  # only set when embedded
+    warning: str | None = None
+
+
+class FontResolver:
+    """Resolves and caches fonts for a single open document.
+
+    Text must be drawn with `pymupdf.TextWriter` against the `pymupdf.Font`
+    objects this returns — NOT `page.insert_text`/`insert_textbox` with a
+    bare `fontname=` string. The latter uses a legacy simple-encoding path
+    that silently mangles any character outside core WinAnsi (bullets,
+    en/em dashes, curly quotes all render as a placeholder middle-dot) even
+    though the font itself has the glyph (verified via `Font.has_glyph`).
+    TextWriter resolves glyphs from the Font object's actual cmap and
+    renders them correctly, and registers the font as a page resource
+    automatically — no separate `page.insert_font()` call needed.
+    """
+
+    def __init__(self, doc: pymupdf.Document):
+        self.doc = doc
+        self._cache: dict[str, FontResolution] = {}
+        self._font_objects: dict[str, pymupdf.Font] = {}  # keyed by alias
+        self._page_font_cache: dict[int, list] = {}
+        self.warnings: list[str] = []
+
+    def _page_fonts(self, page_index: int) -> list:
+        if page_index not in self._page_font_cache:
+            self._page_font_cache[page_index] = self.doc[page_index].get_fonts(full=True)
+        return self._page_font_cache[page_index]
+
+    def _find_xref(self, page_index: int, font_name: str) -> int | None:
+        for entry in self._page_fonts(page_index):
+            xref, _ext, _type, basefont, _name, _encoding, *_ = entry
+            if basefont == font_name:
+                return xref
+        return None
+
+    def _alias_for_embedded(self, font_name: str) -> str:
+        base = _ALIAS_SANITIZE_RE.sub("", font_name) or "font"
+        alias = base
+        n = 1
+        existing_aliases = {r.alias for r in self._cache.values()}
+        while alias in existing_aliases:
+            n += 1
+            alias = f"{base}{n}"
+        return alias
+
+    def resolve(self, span: Span) -> FontResolution:
+        cached = self._cache.get(span.font)
+        if cached is not None:
+            return cached
+
+        resolution = self._resolve_embedded(span)
+        if resolution is None:
+            alias = base14_alias(span.style)
+            resolution = FontResolution(
+                alias=alias,
+                embedded=False,
+                warning=(
+                    f"font '{span.font}' is not embedded (or unsupported); "
+                    f"falling back to Base-14 '{alias}'"
+                ),
+            )
+
+        if resolution.warning:
+            self.warnings.append(resolution.warning)
+        self._cache[span.font] = resolution
+        return resolution
+
+    def _resolve_embedded(self, span: Span) -> FontResolution | None:
+        page_index = span.page - 1
+        xref = self._find_xref(page_index, span.font)
+        if xref is None:
+            return None
+
+        try:
+            basefont, ext, subtype, buffer = self.doc.extract_font(xref)
+        except Exception:
+            return None
+
+        if ext not in _SUPPORTED_EMBEDDED_EXTS or not buffer:
+            return None
+
+        alias = self._alias_for_embedded(span.font)
+        return FontResolution(alias=alias, embedded=True, fontbuffer=buffer)
+
+    def font_object(self, resolution: FontResolution) -> pymupdf.Font:
+        """Get (and cache) the pymupdf.Font object to draw with via
+        TextWriter for this resolution."""
+        font = self._font_objects.get(resolution.alias)
+        if font is None:
+            if resolution.embedded:
+                font = pymupdf.Font(fontbuffer=resolution.fontbuffer)
+            else:
+                font = pymupdf.Font(fontname=resolution.alias)
+            self._font_objects[resolution.alias] = font
+        return font

pdfedit/model.py

@@ -0,0 +1,121 @@
+"""Text model layer: walk a PDF's pages and extract every text span as a
+stable, addressable unit (font, size, color, style, bbox)."""
+
+from dataclasses import dataclass, field
+
+import pymupdf
+
+# Bit flags used by PyMuPDF in span["flags"].
+_FLAG_SUPERSCRIPT = 1
+_FLAG_ITALIC = 2
+_FLAG_SERIFED = 4
+_FLAG_MONOSPACED = 8
+_FLAG_BOLD = 16
+
+
+@dataclass
+class SpanStyle:
+    superscript: bool
+    italic: bool
+    serif: bool
+    monospace: bool
+    bold: bool
+
+    @classmethod
+    def from_flags(cls, flags: int) -> "SpanStyle":
+        return cls(
+            superscript=bool(flags & _FLAG_SUPERSCRIPT),
+            italic=bool(flags & _FLAG_ITALIC),
+            serif=bool(flags & _FLAG_SERIFED),
+            monospace=bool(flags & _FLAG_MONOSPACED),
+            bold=bool(flags & _FLAG_BOLD),
+        )
+
+    def short_label(self) -> str:
+        letters = ""
+        if self.bold:
+            letters += "B"
+        if self.italic:
+            letters += "I"
+        if self.serif:
+            letters += "S"
+        if self.monospace:
+            letters += "M"
+        return letters or "-"
+
+
+@dataclass
+class Span:
+    id: str
+    page: int  # 1-based, human-facing
+    block_no: int  # 0-based, as reported by get_text("dict")
+    line_no: int
+    span_no: int
+    text: str
+    bbox: tuple  # (x0, y0, x1, y1)
+    origin: tuple  # (x, y) baseline origin
+    font: str
+    size: float
+    color: int  # packed sRGB int, as reported by PyMuPDF
+    style: SpanStyle
+    page_rotation: int = field(default=0)
+
+    def color_rgb01(self) -> tuple:
+        """Unpack the span's packed color int into 0-1 float RGB."""
+        return unpack_color(self.color)
+
+
+def unpack_color(color: int) -> tuple:
+    """Unpack a packed sRGB int (as PyMuPDF reports span colors) into a
+    0-1 float (r, g, b) tuple usable by insert_text/insert_textbox."""
+    r = (color >> 16) & 255
+    g = (color >> 8) & 255
+    b = color & 255
+    return (r / 255.0, g / 255.0, b / 255.0)
+
+
+def extract_spans(doc: pymupdf.Document) -> list[Span]:
+    """Walk every page of doc and return a flat list of Span objects, each
+    with a stable ID of the form p{page}-b{block}-l{line}-s{span}."""
+    spans: list[Span] = []
+    for page_index in range(len(doc)):
+        page = doc[page_index]
+        page_no = page_index + 1
+        rotation = page.rotation
+        raw = page.get_text("dict")
+        for block in raw.get("blocks", []):
+            if block.get("type") != 0:
+                continue  # skip image blocks
+            block_no = block["number"]
+            for line_no, line in enumerate(block.get("lines", [])):
+                for span_no, s in enumerate(line.get("spans", [])):
+                    span_id = f"p{page_no}-b{block_no}-l{line_no}-s{span_no}"
+                    spans.append(
+                        Span(
+                            id=span_id,
+                            page=page_no,
+                            block_no=block_no,
+                            line_no=line_no,
+                            span_no=span_no,
+                            text=s["text"],
+                            bbox=tuple(s["bbox"]),
+                            origin=tuple(s["origin"]),
+                            font=s["font"],
+                            size=s["size"],
+                            color=s["color"],
+                            style=SpanStyle.from_flags(s["flags"]),
+                            page_rotation=rotation,
+                        )
+                    )
+    return spans
+
+
+def is_scanned_page(doc: pymupdf.Document, page_index: int) -> bool:
+    """Heuristic check for a scanned/no-text-layer page: no extractable text
+    but at least one image present (a blank page with neither is not
+    considered "scanned", just empty)."""
+    page = doc[page_index]
+    text = page.get_text("text").strip()
+    if text:
+        return False
+    return len(page.get_images()) > 0

pdfedit-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: pdfedit
+Version: 0.1.0
+Summary: Find and edit any text in a PDF while matching the original font, size, and color
+Project-URL: Homepage, https://github.com/sachinpandey22/pdfedit
+Project-URL: Repository, https://github.com/sachinpandey22/pdfedit
+Project-URL: Issues, https://github.com/sachinpandey22/pdfedit/issues
+Author-email: Sachin Pandey <xachin300@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: edit,font,pdf,pymupdf,redaction,text
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: pymupdf>=1.28.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pdfedit
+
+A command-line tool that finds and edits **any** text in a PDF while matching
+the original font, size, and color — not a fixed find-and-replace on known
+form fields. It walks every text span via [PyMuPDF](https://pymupdf.readthedocs.io/),
+resolves each span's real font (embedded extraction, or the closest Base-14
+fallback), then redacts the old glyphs and redraws the replacement in the
+same font, size, and color at the same position.
+
+The original file is never modified — every edit writes `<name>_edited.pdf`
+next to the input.
+
+> **Status:** alpha, pre-1.0 — the API and CLI may still change.
+> White-fill redaction only (colored backgrounds not yet sampled); no
+> paragraph reflow; scanned pages are detected and warned about, not OCR'd.
+
+## Install
+
+```bash
+pip install pdfedit
+```
+
+This puts a `pdfedit` command on your PATH. You can also run it as
+`python -m pdfedit`.
+
+From source (for development):
+
+```bash
+git clone https://github.com/sachinpandey22/pdfedit && cd pdfedit
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"      # editable install + pytest
+```
+
+## Usage
+
+```bash
+pdfedit inspect your-document.pdf          # read-only: list every text span with its id, font, size, color
+pdfedit edit your-document.pdf             # interactive: pick a span id, type a replacement, `save`
+pdfedit batch your-document.pdf edits.json  # non-interactive: apply a list of edits
+```
+
+### `inspect`
+
+Prints one row per span. The `ID` (`p<page>-b<block>-l<line>-s<span>`) is the
+handle you pass to `edit` or a batch file.
+
+### `edit`
+
+A small REPL. Enter a span id, then the replacement text; the edit is
+**queued** with a before/after preview (and the resolved font, and an
+auto-shrink note if the text had to be made smaller to fit). `save` applies
+every queued edit at once and writes the output. `quit` discards everything.
+
+### `batch`
+
+`edits.json` is a JSON array; each entry is either:
+
+```json
+[
+  { "id": "p1-b0-l0-s0", "new_text": "New Name" },
+  { "find": "Old Company", "new_text": "New Company" }
+]
+```
+
+- `id` targets one exact span.
+- `find` replaces that substring in **every** span containing it. Multiple
+  `find` entries against the same span compose in order.
+
+The whole file is validated first — if any entry is malformed or names a
+missing span id, nothing is written and the command exits non-zero.
+
+### Autofit
+
+If a replacement is wider than the original box, the font size shrinks (down
+to 60% of the original) until it fits. Past that floor it's drawn at the
+minimum size and a warning is printed rather than overflowing silently.
+
+### Encrypted PDFs
+
+You're prompted for the password. Note: the `_edited.pdf` copy is written
+**without** encryption.
+
+## Development
+
+```bash
+pytest                                   # run the test suite
+python tests/fixtures/make_sample.py      # regenerate the synthetic test fixture
+```
+
+There's no separate lint config. See
+[`CLAUDE.md`](https://github.com/sachinpandey22/pdfedit/blob/main/CLAUDE.md)
+for the architecture and the two redraw pitfalls the engine works around,
+and [`docs/`](https://github.com/sachinpandey22/pdfedit/tree/main/docs) for
+longer background.

pdfedit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pdfedit/__init__.py,sha256=jFI1Oz_-Wvf_hhzF-eqLvi5UoCPO9x35NWU0JJ52raU,119
+pdfedit/__main__.py,sha256=Fr6ARWNJdlHU2tN8t58l01Hz3bPTFPm77q1Zluu5yxM,68
+pdfedit/cli.py,sha256=ueRPlRsimnOPTRhd5apQVnXaT6qWTUu_qSh7S9yBHwk,8759
+pdfedit/engine.py,sha256=pQ-KJ7up0uknbcEMVijNEbC2A1CIBhEb98ReywGB8D8,9271
+pdfedit/fonts.py,sha256=Gbn9cQysrwkhity_BQEipCmE1Je0vlIK0CNCdTXLkro,5452
+pdfedit/model.py,sha256=jmA884etOiOFrnij1LAkE0lVPE8p_YXta3sgm12r1Ms,3894
+pdfedit-0.1.0.dist-info/METADATA,sha256=i3zudw6tsweWF7dA-FER8y7Als-q-zjupCCKtpXMxTE,4328
+pdfedit-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pdfedit-0.1.0.dist-info/entry_points.txt,sha256=5pFNp3hGvQ8Exwp2GkN72kpij3LrbNAHMJ8FmVFoHnk,45
+pdfedit-0.1.0.dist-info/licenses/LICENSE,sha256=TzbVQ4gnmkXxnv63wVfsN96Wx03tAT4xtmKVbUXC_SU,1070
+pdfedit-0.1.0.dist-info/RECORD,,

pdfedit-0.1.0.dist-info/WHEEL

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

pdfedit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdfedit = pdfedit.cli:main

pdfedit-0.1.0.dist-info/licenses/LICENSE

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