pdfblah 0.1.0__tar.gz

pdfblah-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch: {}
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[test]"
+      - run: pytest -q
+      - name: Build wheel
+        run: pip install build && python -m build

pdfblah-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,23 @@
+name: pypi
+
+# Publishes to PyPI when a GitHub Release is published. Uses PyPI Trusted
+# Publishing (OIDC), so no API token is stored. One-time setup: on PyPI, add a
+# pending publisher for project "pdfblah" -> repo KuvopLLC/pdfblah, workflow
+# pypi.yml.
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pdfblah-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/

pdfblah-0.1.0/LICENSE

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

pdfblah-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: pdfblah
+Version: 0.1.0
+Summary: Real find and replace on the actual text in a PDF. No overlay, metadata preserved.
+Project-URL: Homepage, https://pdfblah.com
+Project-URL: Source, https://github.com/KuvopLLC/pdfblah
+Project-URL: Issues, https://github.com/KuvopLLC/pdfblah/issues
+Author: Kuvop LLC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acrobat-alternative,cli,edit,find,pdf,pdf-editor,redact,replace,text
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: pikepdf>=8
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: reportlab; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pdfblah
+
+Real find and replace on the actual text in a PDF, from the command line.
+
+Most tools "edit" a PDF by painting a box over the old text and drawing new text
+on top, which leaves the original underneath (copy and paste still reveals it) and
+often adds a watermark. `pdfblah` rewrites the real text in the content stream, so:
+
+- the old text is genuinely gone (`pdftotext`, Ctrl-F, and copy show only the new value)
+- no overlay, no watermark
+- the original metadata (dates, Producer, XMP) is preserved byte for byte
+- alignment is auto-detected and kept, so right-aligned numbers stay flush
+- fonts it cannot reproduce are refused instead of garbled
+
+Pure Python (pdfplumber + pikepdf). No system dependencies.
+
+## Install
+
+```sh
+pipx install pdfblah      # or:  pip install pdfblah
+```
+
+## Use
+
+Replace the first match:
+
+```sh
+pdfblah in.pdf out.pdf --find "Old Name" --replace "New Name"
+```
+
+Options:
+
+```sh
+--scope all         change every match           (default: first)
+--scope 3           change the 3rd match
+--ci                ignore case
+--word              whole word only ("cat" will not match "category")
+--page 2            only page 2
+--replace ""        delete the text
+```
+
+Many rules from a file (`FIND | REPLACE | FLAGS` per line):
+
+```sh
+pdfblah in.pdf out.pdf --rules rules.txt
+```
+
+```
+# rules.txt
+Old Company Name | New Company Name | all
+CONFIDENTIAL DRAFT | FINAL | ci
+Jane Doe | John Smith | all word
+Total | Sum | 2
+delete this phrase |
+```
+
+## Library
+
+```python
+from pdfblah import process, apply_rules, parse_rules_file
+
+process("in.pdf", "out.pdf", "999.00", "42.00", scope="all", ci=True)
+```
+
+Each call returns a report dict (`ok`, `count`, `refused`, `reason`, ...).
+
+## What it does not do
+
+Scanned PDFs (image only, no text layer) cannot be edited. Fonts that are not
+embedded and not standard, or use a custom encoding, are refused rather than
+rendered wrong. This is by design: a wrong-looking edit is worse than a clear "no".
+
+## Hosted version
+
+Want it without installing anything, or for a non-technical colleague? The hosted
+version at **[pdfblah.com](https://pdfblah.com)** does the same edit in the browser:
+upload, preview for free, download.
+
+## License
+
+MIT, (c) 2026 Kuvop LLC.

pdfblah-0.1.0/README.md

@@ -0,0 +1,81 @@
+# pdfblah
+
+Real find and replace on the actual text in a PDF, from the command line.
+
+Most tools "edit" a PDF by painting a box over the old text and drawing new text
+on top, which leaves the original underneath (copy and paste still reveals it) and
+often adds a watermark. `pdfblah` rewrites the real text in the content stream, so:
+
+- the old text is genuinely gone (`pdftotext`, Ctrl-F, and copy show only the new value)
+- no overlay, no watermark
+- the original metadata (dates, Producer, XMP) is preserved byte for byte
+- alignment is auto-detected and kept, so right-aligned numbers stay flush
+- fonts it cannot reproduce are refused instead of garbled
+
+Pure Python (pdfplumber + pikepdf). No system dependencies.
+
+## Install
+
+```sh
+pipx install pdfblah      # or:  pip install pdfblah
+```
+
+## Use
+
+Replace the first match:
+
+```sh
+pdfblah in.pdf out.pdf --find "Old Name" --replace "New Name"
+```
+
+Options:
+
+```sh
+--scope all         change every match           (default: first)
+--scope 3           change the 3rd match
+--ci                ignore case
+--word              whole word only ("cat" will not match "category")
+--page 2            only page 2
+--replace ""        delete the text
+```
+
+Many rules from a file (`FIND | REPLACE | FLAGS` per line):
+
+```sh
+pdfblah in.pdf out.pdf --rules rules.txt
+```
+
+```
+# rules.txt
+Old Company Name | New Company Name | all
+CONFIDENTIAL DRAFT | FINAL | ci
+Jane Doe | John Smith | all word
+Total | Sum | 2
+delete this phrase |
+```
+
+## Library
+
+```python
+from pdfblah import process, apply_rules, parse_rules_file
+
+process("in.pdf", "out.pdf", "999.00", "42.00", scope="all", ci=True)
+```
+
+Each call returns a report dict (`ok`, `count`, `refused`, `reason`, ...).
+
+## What it does not do
+
+Scanned PDFs (image only, no text layer) cannot be edited. Fonts that are not
+embedded and not standard, or use a custom encoding, are refused rather than
+rendered wrong. This is by design: a wrong-looking edit is worse than a clear "no".
+
+## Hosted version
+
+Want it without installing anything, or for a non-technical colleague? The hosted
+version at **[pdfblah.com](https://pdfblah.com)** does the same edit in the browser:
+upload, preview for free, download.
+
+## License
+
+MIT, (c) 2026 Kuvop LLC.

pdfblah-0.1.0/pdfblah/__init__.py

@@ -0,0 +1,20 @@
+"""pdfblah: real find and replace on the actual text in a PDF.
+
+Rewrites the real text in the content stream (no overlay, no watermark), preserves
+all original metadata, auto-detects alignment, and refuses fonts it cannot
+reproduce instead of garbling them.
+"""
+from .engine import (
+    process,
+    apply_rules,
+    parse_rules_file,
+    parse_flags,
+    font_safe,
+    detect_alignment,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "process", "apply_rules", "parse_rules_file", "parse_flags",
+    "font_safe", "detect_alignment",
+]

pdfblah-0.1.0/pdfblah/cli.py

@@ -0,0 +1,62 @@
+"""Command-line interface for pdfblah."""
+import argparse
+import json
+import sys
+
+from .engine import process, apply_rules, parse_rules_file
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="pdfblah",
+        description="Real find and replace on the actual text in a PDF. "
+                    "No overlay, metadata preserved, alignment auto-detected.")
+    ap.add_argument("input", help="input PDF")
+    ap.add_argument("output", help="output PDF (never overwrites the input)")
+    ap.add_argument("--find", help="text to find")
+    ap.add_argument("--replace", default="", help="replacement text (empty deletes the text)")
+    ap.add_argument("--rules", metavar="FILE",
+                    help="apply many rules from a file, one 'FIND | REPLACE | FLAGS' per line")
+    ap.add_argument("--scope", default="first", metavar="WHICH",
+                    help="first (default), all, or a number for the Nth match")
+    ap.add_argument("--ci", action="store_true", help="ignore case")
+    ap.add_argument("--word", action="store_true", help="whole word only")
+    ap.add_argument("--page", type=int, help="limit to this page number")
+    ap.add_argument("--json", action="store_true", help="print the full JSON report")
+    a = ap.parse_args(argv)
+
+    if a.rules:
+        with open(a.rules, encoding="utf-8") as fh:
+            rules = parse_rules_file(fh.read())
+        if not rules:
+            print(f"no rules found in {a.rules}", file=sys.stderr)
+            return 2
+        rep = apply_rules(a.input, a.output, rules)
+        if a.json:
+            print(json.dumps(rep, indent=2))
+        else:
+            print(f"{rep['applied']}/{rep['total']} rules applied  ->  {a.output}")
+            for r in rep["rules"]:
+                mark = "ok  " if r["applied"] else "skip"
+                extra = f" (x{r['count']})" if r.get("count") else ""
+                why = "" if r["applied"] else "  " + (r.get("reason") or r.get("error") or "not applied")
+                print(f"  [{mark}] {r['find']!r} -> {r['replace']!r}{extra}{why}")
+        return 0 if rep["applied"] else 1
+
+    if not a.find:
+        ap.error("give --find (with --replace), or --rules FILE")
+    scope = int(a.scope) if a.scope.isdigit() else a.scope
+    r = process(a.input, a.output, a.find, a.replace, a.page, scope, a.ci, a.word)
+    if a.json:
+        print(json.dumps(r, indent=2))
+    elif r.get("ok"):
+        print(f"replaced {r['count']} match(es) of {a.find!r}  ->  {a.output}")
+    elif r.get("refused"):
+        print(f"refused: {r.get('reason')}", file=sys.stderr)
+    else:
+        print(f"failed: {r.get('error')}", file=sys.stderr)
+    return 0 if r.get("ok") else (3 if r.get("refused") else 1)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pdfblah-0.1.0/pdfblah/engine.py

@@ -0,0 +1,387 @@
+"""pdfblah engine: real in-content-stream PDF text replacement.
+
+Rewrites the actual Tj/TJ string operands in the page content stream, so the old
+text is gone (pdftotext, Ctrl-F, and copy show only the new value). No overlay, no
+watermark. Alignment is auto-detected and preserved. All original metadata
+(DocInfo + XMP, including dates and Producer) is kept verbatim. Fonts we cannot
+reproduce (non-embedded exotic or custom-encoded) are refused rather than garbled.
+
+Library use:
+    from pdfblah import process, apply_rules, parse_rules_file
+    process("in.pdf", "out.pdf", "OLD", "NEW", scope="all", ci=True)
+"""
+import os, re, json, tempfile, shutil
+import pikepdf
+from pikepdf import Operator, String, Array
+import pdfplumber
+
+
+# ---- alignment auto-detection (proven on the trade-confirmation PDF) ----------
+def detect_alignment(target, words, tol=1.2, vband=300):
+    tx0, tx1, ttop = target["x0"], target["x1"], target["top"]
+    tcx = (tx0 + tx1) / 2
+    cx = lambda w: (w["x0"] + w["x1"]) / 2
+    band = [w for w in words if abs(w["top"] - ttop) <= vband]
+    m = {"left":   sum(1 for w in band if abs(w["x0"] - tx0) <= tol),
+         "right":  sum(1 for w in band if abs(w["x1"] - tx1) <= tol),
+         "center": sum(1 for w in band if abs(cx(w) - tcx) <= tol)}
+    align = max(m, key=m.get)
+    if m[align] < 2:
+        align = "left"
+    elif m["right"] == m["left"] and any(c.isdigit() for c in target["text"]):
+        align = "right"
+    return align, m
+
+
+# ---- per-character advance widths, taken from the REAL font as rendered --------
+def unit_widths(page, fontname):
+    """Map char -> advance width per 1pt of font size, measured from actual glyph
+    advances of the same font on the page. Font-exact, no substitute needed."""
+    tbl, samples = {}, {}
+    chars = [c for c in page.chars if c.get("fontname") == fontname]
+    # advance = delta of x0 to the next char on the same line & word run
+    chars_sorted = sorted(chars, key=lambda c: (round(c["top"]), c["x0"]))
+    for a, b in zip(chars_sorted, chars_sorted[1:]):
+        if abs(a["top"] - b["top"]) > 1:            # different line
+            continue
+        adv = b["x0"] - a["x0"]
+        size = a.get("size") or 0
+        if size <= 0 or adv <= 0 or adv > size * 3:  # sane advance only
+            continue
+        samples.setdefault(a["text"], []).append(adv / size)
+    for ch, vals in samples.items():
+        vals.sort(); tbl[ch] = vals[len(vals) // 2]   # median
+    return tbl
+
+
+def string_width(s, tbl, size, fallback):
+    return sum(tbl.get(ch, fallback) for ch in s) * size
+
+
+def matcher(find, ci=False, word=False):
+    """Compiled regex for `find`: literal (re.escape), optional case-insensitive
+    and whole-word (not inside a longer alphanumeric run)."""
+    pat = re.escape(find)
+    if word:
+        pat = r"(?<![0-9A-Za-z])" + pat + r"(?![0-9A-Za-z])"
+    return re.compile(pat, re.IGNORECASE if ci else 0)
+
+
+def locate_boxes(words, find, ci=False, word=False):
+    """Ordered boxes where `find` matches: inside one word, or as consecutive
+    words on one line (multi-word phrase). Returns [(x0, top, x1, bottom), ...]."""
+    rx = matcher(find, ci, word)
+    boxes = []
+    for w in words:
+        m = rx.search(w["text"])
+        if not m:
+            continue
+        # box of the matched substring (estimated by char proportion) so the
+        # rewrite targets the match, not the start of a longer word.
+        n = len(w["text"]) or 1; span = w["x1"] - w["x0"]
+        sx0 = w["x0"] + span * (m.start() / n)
+        sx1 = w["x0"] + span * (m.end() / n)
+        boxes.append((sx0, w["top"], sx1, w["bottom"]))
+    if boxes:
+        return boxes
+    fl = find.lower() if ci else find
+    n = len(words)
+    for i in range(n):
+        acc = ""
+        for j in range(i, n):
+            if j > i and abs(words[j]["top"] - words[i]["top"]) > 3:
+                break
+            acc = words[j]["text"] if j == i else acc + " " + words[j]["text"]
+            a = acc.lower() if ci else acc
+            if a == fl:
+                grp = words[i:j + 1]
+                boxes.append((min(w["x0"] for w in grp), min(w["top"] for w in grp),
+                              max(w["x1"] for w in grp), max(w["bottom"] for w in grp)))
+                break
+            if not fl.startswith(a):
+                break
+    return boxes
+
+
+# ---- content-stream rewrite (position-matched to the located instance) --------
+def _mul(m, n):
+    a, b, c, d, e, f = m; A, B, C, D, E, F = n
+    return (a*A + b*C, a*B + b*D, c*A + d*C, c*B + d*D,
+            e*A + f*C + E, e*B + f*D + F)
+
+def _op_text(operands, so):
+    if so == "TJ":
+        return "".join(bytes(e).decode("latin-1") for e in operands[0]
+                       if isinstance(e, (String, bytes)))
+    if so == "\"":
+        return bytes(operands[2]).decode("latin-1")
+    return bytes(operands[0]).decode("latin-1")          # Tj and '
+
+
+def rewrite_stream(pdf, page, find, replace, target_xy, align, size, wtbl, fb,
+                   ci=False, word=False, tol=14.0):
+    """Replace the single find-match whose device position is nearest target_xy
+    (x, y_from_bottom). Honors case-insensitive / whole-word matching. Returns
+    (True, dist) or (False, dist|None)."""
+    rx = matcher(find, ci, word)
+    ID = (1, 0, 0, 1, 0, 0)
+    ctm = ID; gstack = []; tm = ID; tlm = ID; leading = 0.0
+    tx, ty = target_xy
+    best = None                      # (dist, idx, so, mstart, mend)
+    ops = list(pikepdf.parse_content_stream(page))
+
+    def show_pos():
+        m = _mul(tm, ctm)
+        return m[4], m[5]
+
+    for idx, (operands, op) in enumerate(ops):
+        so = str(op)
+        if so == "q": gstack.append(ctm)
+        elif so == "Q": ctm = gstack.pop() if gstack else ctm
+        elif so == "cm": ctm = _mul(tuple(float(x) for x in operands), ctm)
+        elif so == "BT": tm = tlm = ID
+        elif so == "TL": leading = float(operands[0])
+        elif so in ("Td", "TD"):
+            dx, dy = float(operands[0]), float(operands[1])
+            if so == "TD": leading = -dy
+            tlm = _mul((1, 0, 0, 1, dx, dy), tlm); tm = tlm
+        elif so == "Tm": tm = tlm = tuple(float(x) for x in operands)
+        elif so == "T*": tlm = _mul((1, 0, 0, 1, 0, -leading), tlm); tm = tlm
+        elif so in ("Tj", "TJ", "'", "\""):
+            if so in ("'", "\""):
+                tlm = _mul((1, 0, 0, 1, 0, -leading), tlm); tm = tlm
+            x, y = show_pos()
+            txt = _op_text(operands, so)
+            for m in rx.finditer(txt):
+                cx = x + string_width(txt[:m.start()], wtbl, size, fb)
+                d = ((cx - tx) ** 2 + (y - ty) ** 2) ** 0.5
+                if best is None or d < best[0]:
+                    best = (d, idx, so, m.start(), m.end())
+    if best is None or best[0] > tol:
+        return (False, None if best is None else best[0])
+
+    _, idx, so, ms, me = best
+    operands, op = ops[idx]
+    patched = _rewrite_one(operands, so, ms, me, replace, align, size, wtbl, fb)
+    if patched is None:                 # span crosses TJ elements -> unsupported
+        return (False, best[0])
+    ops[idx] = patched
+    page.Contents = pdf.make_stream(pikepdf.unparse_content_stream(ops))
+    return (True, best[0])
+
+
+def _rewrite_one(operands, so, ms, me, replace, align, size, wtbl, fb):
+    """Rewrite the [ms:me] span of an op's shown text with `replace`."""
+    if so == "Tj":
+        s = bytes(operands[0]).decode("latin-1")
+        return _patch_span(s, ms, me, replace, align, size, wtbl, fb)
+    if so == "'":
+        s = bytes(operands[0]).decode("latin-1")
+        return ([String((s[:ms] + replace + s[me:]).encode("latin-1"))], Operator("'"))
+    if so == "\"":
+        s = bytes(operands[2]).decode("latin-1")
+        return ([operands[0], operands[1],
+                 String((s[:ms] + replace + s[me:]).encode("latin-1"))], Operator("\""))
+    # TJ: map the joined offset back to one string element (skip if it crosses)
+    arr = operands[0]; pos = 0; new_arr = []; done = False
+    for e in arr:
+        if isinstance(e, (String, bytes)):
+            es = bytes(e).decode("latin-1"); L = len(es)
+            if not done and pos <= ms and me <= pos + L:
+                ls, le = ms - pos, me - pos
+                new_arr.append(String((es[:ls] + replace + es[le:]).encode("latin-1")))
+                done = True
+            else:
+                new_arr.append(e)
+            pos += L
+        else:
+            new_arr.append(e)
+    return ([Array(new_arr)], Operator("TJ")) if done else None
+
+
+def _patch_span(s, ms, me, replace, align, size, wtbl, fb):
+    """Show `s` with [ms:me] replaced by `replace`, repositioned so the detected
+    anchor edge stays fixed (right/center); left = in place."""
+    ns = s[:ms] + replace + s[me:]
+    if align == "left":
+        return [String(ns.encode("latin-1"))], Operator("Tj")
+    ow = string_width(s[ms:me], wtbl, size, fb)
+    nw = string_width(replace, wtbl, size, fb)
+    frac = (ow - nw) if align == "right" else (ow - nw) / 2.0
+    num = -frac * 1000.0 / size
+    return [Array([num, String(ns.encode("latin-1"))])], Operator("TJ")
+
+
+STD14 = {"helvetica", "times", "courier", "symbol", "zapfdingbats"}
+
+def font_safe(page, fontname, replace, wtbl):
+    """Decide whether NEW text in `fontname` will render faithfully.
+      - embedded font: safe only if every replace char was already observed
+        (in-subset); a brand-new glyph may be missing.
+      - non-embedded: safe only for the true standard-14 families with a
+        standard byte encoding. Everything else (exotic AFP fonts, custom-encoded
+        Arial, etc.) is REFUSED — proven to garble.
+    Returns (bool, reason)."""
+    fam = base_family_lc(fontname)
+    try:
+        fonts = page.get("/Resources", {}).get("/Font", {})
+    except Exception:
+        fonts = {}
+    fd = None
+    for _, f in dict(fonts).items():
+        base = strip_subset(str(f.get("/BaseFont", "")).lstrip("/"))
+        if base and (base.lower() == strip_subset(fontname or "").lower()
+                     or base_family_lc(base) == fam):
+            fd = f; break
+    embedded, enc_custom = False, False
+    if fd is not None:
+        desc = fd.get("/FontDescriptor", {})
+        embedded = any(k in desc for k in ("/FontFile", "/FontFile2", "/FontFile3"))
+        enc = fd.get("/Encoding", None)
+        enc_custom = isinstance(enc, pikepdf.Dictionary)  # has /Differences
+    if embedded:
+        missing = [c for c in replace if c not in wtbl and c != " "]
+        if missing:
+            return False, f"embedded subset font missing glyph(s) {missing!r}"
+        return True, "embedded; all replacement glyphs already present"
+    if fam in STD14 and not enc_custom:
+        return True, "non-embedded standard-14 font with standard encoding"
+    return False, (f"non-embedded font {fontname!r} (family {fam!r}) is not a "
+                   f"standard-14 font{' and uses a custom encoding' if enc_custom else ''}")
+
+
+def base_family_lc(n):
+    return base_family(strip_subset(n or "")).lower().replace(" ", "")
+
+
+def strip_subset(n): return re.sub(r"^[A-Z]{6}\+", "", n or "")
+def base_family(n):
+    n = re.split(r"[-,]", strip_subset(n))[0]
+    return re.sub(r"(?i)(bold|italic|oblique|regular|mt|ps)+$", "", n).strip() or strip_subset(n)
+
+
+def process(input_path, output_path, find, replace, page=None, scope="first",
+            ci=False, word=False, align="auto"):
+    """Real in-stream replacement. `scope` is "first", "all", or an int N (Nth).
+    `ci` = ignore case, `word` = whole-word only. Returns a status dict; metadata
+    (DocInfo + XMP) is preserved verbatim on save."""
+    if os.path.abspath(input_path) == os.path.abspath(output_path):
+        return {"ok": False, "error": "refusing to overwrite the input"}
+    nth = scope if isinstance(scope, int) else None
+
+    # 1) locate all matches (across pages), measure font/alignment per match
+    targets = []           # {pi, xy, align, size, wtbl, fb, fontname}
+    with pdfplumber.open(input_path) as pdf:
+        pages = range(len(pdf.pages)) if page is None else [page - 1]
+        for pi in pages:
+            pg = pdf.pages[pi]
+            words = pg.extract_words(use_text_flow=True)
+            for (x0, top, x1, bottom) in locate_boxes(words, find, ci, word):
+                al, amap = (align, {})
+                if align == "auto":
+                    al, amap = detect_alignment(
+                        {"x0": x0, "top": top, "x1": x1, "bottom": bottom, "text": find}, words)
+                chars = [c for c in pg.chars if x0 - 1 <= c["x0"] <= x1 + 1
+                         and top - 1 <= c["top"] <= bottom + 1]
+                fontname = chars[0].get("fontname") if chars else None
+                size = chars[0].get("size") if chars else 10.0
+                wtbl = unit_widths(pg, fontname) if fontname else {}
+                fb = (sum(wtbl.values()) / len(wtbl)) if wtbl else 0.5
+                targets.append({"pi": pi, "xy": (x0, pg.height - bottom), "align": al,
+                                "amap": amap, "size": size or 10.0, "wtbl": wtbl,
+                                "fb": fb, "fontname": fontname})
+    if not targets:
+        return {"ok": False, "error": f"text {find!r} not found"}
+    if nth is not None:
+        if nth > len(targets):
+            return {"ok": False, "error": f"{find!r} has only {len(targets)} match(es); "
+                    f"asked for #{nth}"}
+        targets = [targets[nth - 1]]
+    elif scope != "all":
+        targets = [targets[0]]                    # "first"
+
+    # 2) FONT-SAFETY GATE — refuse if any selected match uses a font we can't reproduce
+    pdf = pikepdf.open(input_path)
+    for t in targets:
+        safe, reason = font_safe(pdf.pages[t["pi"]], t["fontname"], replace, t["wtbl"])
+        if not safe:
+            return {"ok": False, "refused": True, "font": t["fontname"], "reason": reason,
+                    "hint": "non-embedded/exotic or custom-encoded font; new text can "
+                            "garble, so this is the detect-and-refuse path"}
+
+    # 3) rewrite each selected match (sequential rewrites don't move other runs)
+    count = 0
+    for t in targets:
+        ok, _ = rewrite_stream(pdf, pdf.pages[t["pi"]], find, replace, t["xy"],
+                               t["align"], t["size"], t["wtbl"], t["fb"], ci, word)
+        if ok:
+            count += 1
+    if count == 0:
+        return {"ok": False,
+                "error": f"{find!r} located visually but not found as an editable "
+                         "Tj/TJ string (split/encoded run)"}
+    pdf.save(output_path, fix_metadata_version=False, deterministic_id=False)
+    first = targets[0]
+    return {"ok": True, "page": first["pi"] + 1, "font": first["fontname"],
+            "size_pt": round(first["size"], 2), "align": first["align"],
+            "align_votes": first["amap"], "scope": scope, "count": count,
+            "replaced": f"{find!r} -> {replace!r}", "output": output_path}
+
+
+def apply_rules(input_path, output_path, rules):
+    """Apply many rules in order. Unapplicable rules are reported and skipped.
+    rules: list of {"find","replace","scope"?,"ci"?,"word"?,"page"?,"align"?}."""
+    report = []; cur = input_path; tmps = []; applied = 0
+    for rule in rules:
+        find = rule["find"]; replace = rule.get("replace", "")
+        scope = rule.get("scope", "first")
+        if isinstance(scope, str) and scope.isdigit():
+            scope = int(scope)
+        nxt = tempfile.mktemp(suffix=".pdf")
+        r = process(cur, nxt, find, replace, rule.get("page"), scope,
+                    bool(rule.get("ci")), bool(rule.get("word")), rule.get("align", "auto"))
+        entry = {"find": find, "replace": replace, "applied": bool(r.get("ok")), "scope": scope}
+        for k in ("count", "font", "reason", "error", "refused", "page"):
+            if k in r:
+                entry[k] = r[k]
+        report.append(entry)
+        if r.get("ok"):
+            cur = nxt; tmps.append(nxt); applied += 1
+        elif os.path.exists(nxt):
+            os.remove(nxt)
+    shutil.copyfile(cur, output_path)
+    for t in tmps:
+        if os.path.abspath(t) != os.path.abspath(output_path) and os.path.exists(t):
+            os.remove(t)
+    return {"applied": applied, "total": len(rules),
+            "all_applied": applied == len(rules), "rules": report}
+
+
+def parse_flags(s):
+    out = {"scope": "first", "ci": False, "word": False}
+    for f in (s or "").strip().lower().split():
+        if f == "all": out["scope"] = "all"
+        elif f == "first": out["scope"] = "first"
+        elif f.isdigit(): out["scope"] = int(f)
+        elif f == "ci": out["ci"] = True
+        elif f == "word": out["word"] = True
+        elif re.fullmatch(r"p\d+", f): out["page"] = int(f[1:])
+    return out
+
+
+def parse_rules_file(text):
+    """Parse a rules file: one 'FIND | REPLACE | FLAGS' per line.
+    '#' comment lines and blank lines are skipped. FLAGS: all/first/N/ci/word/pN."""
+    rules = []
+    for raw in text.splitlines():
+        t = raw.strip()
+        if not t or t.startswith("#"):
+            continue
+        parts = t.split("|")
+        find = parts[0].strip()
+        if not find:
+            continue
+        rule = {"find": find, "replace": parts[1].strip() if len(parts) > 1 else ""}
+        rule.update(parse_flags(parts[2] if len(parts) > 2 else ""))
+        rules.append(rule)
+    return rules

pdfblah-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pdfblah"
+version = "0.1.0"
+description = "Real find and replace on the actual text in a PDF. No overlay, metadata preserved."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kuvop LLC" }]
+keywords = ["pdf", "find", "replace", "edit", "text", "cli", "redact", "pdf-editor", "acrobat-alternative"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: POSIX",
+  "Operating System :: MacOS",
+  "Environment :: Console",
+  "Topic :: Text Processing",
+  "Topic :: Utilities",
+  "Intended Audience :: Developers",
+  "Intended Audience :: End Users/Desktop",
+]
+dependencies = ["pdfplumber>=0.11", "pikepdf>=8"]
+
+[project.optional-dependencies]
+test = ["pytest", "reportlab"]
+
+[project.urls]
+Homepage = "https://pdfblah.com"
+Source = "https://github.com/KuvopLLC/pdfblah"
+Issues = "https://github.com/KuvopLLC/pdfblah/issues"
+
+[project.scripts]
+pdfblah = "pdfblah.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pdfblah"]

pdfblah-0.1.0/tests/test_engine.py

@@ -0,0 +1,116 @@
+import pdfplumber
+import pikepdf
+import pytest
+from reportlab.pdfgen import canvas
+
+from pdfblah import process, apply_rules, parse_rules_file, parse_flags, font_safe
+
+
+def make_pdf(path, lines, font="Helvetica", size=16):
+    c = canvas.Canvas(str(path), pagesize=(400, 300))
+    c.setFont(font, size)
+    for i, t in enumerate(lines):
+        c.drawString(40, 250 - i * 40, t)
+    c.save()
+    return str(path)
+
+
+def alltext(path):
+    with pdfplumber.open(str(path)) as pdf:
+        return "\n".join((p.extract_text() or "") for p in pdf.pages)
+
+
+@pytest.fixture
+def reps(tmp_path):
+    return make_pdf(tmp_path / "in.pdf",
+                    ["apple one", "apple two", "Apple three", "pineapple four", "apple five"])
+
+
+def test_scope_first(reps, tmp_path):
+    o = str(tmp_path / "o.pdf")
+    r = process(reps, o, "apple", "APRICOT", scope="first")
+    assert r["ok"] and r["count"] == 1
+    assert alltext(o).count("APRICOT") == 1
+
+
+def test_scope_all(reps, tmp_path):
+    o = str(tmp_path / "o.pdf")
+    r = process(reps, o, "apple", "APRICOT", scope="all")
+    assert r["count"] == 4
+    assert alltext(o).count("APRICOT") == 4
+
+
+def test_scope_nth(reps, tmp_path):
+    o = str(tmp_path / "o.pdf")
+    r = process(reps, o, "apple", "APRICOT", scope=2)
+    assert r["count"] == 1
+
+
+def test_ignore_case(reps, tmp_path):
+    o = str(tmp_path / "o.pdf")
+    r = process(reps, o, "apple", "APRICOT", scope="all", ci=True)
+    assert r["count"] == 5           # also catches "Apple three"
+
+
+def test_whole_word(reps, tmp_path):
+    o = str(tmp_path / "o.pdf")
+    r = process(reps, o, "apple", "APRICOT", scope="all", word=True)
+    assert r["count"] == 3           # spares "pineapple"
+    assert "pineapple" in alltext(o)
+
+
+def test_delete(reps, tmp_path):
+    o = str(tmp_path / "o.pdf")
+    r = process(reps, o, "apple", "", scope="all", word=True)
+    assert r["ok"]
+    assert "apple one" not in alltext(o)
+
+
+def test_not_found(reps, tmp_path):
+    r = process(reps, str(tmp_path / "o.pdf"), "banana", "x")
+    assert not r["ok"] and "not found" in r["error"]
+
+
+def test_no_overwrite(reps):
+    r = process(reps, reps, "apple", "x")
+    assert not r["ok"]
+
+
+def test_metadata_preserved(reps, tmp_path):
+    o = str(tmp_path / "o.pdf")
+    with pikepdf.open(reps) as p:
+        before = {str(k): str(v) for k, v in (p.docinfo or {}).items()}
+    process(reps, o, "apple", "APRICOT", scope="all")
+    with pikepdf.open(o) as p:
+        after = {str(k): str(v) for k, v in (p.docinfo or {}).items()}
+    for k in ("/Producer", "/CreationDate"):
+        if k in before:
+            assert before[k] == after[k]
+
+
+def test_font_safe_refuses_exotic():
+    exotic = {"/Resources": {"/Font": {"/F1": {"/BaseFont": "/C0A075B0.afm"}}}}
+    safe, reason = font_safe(exotic, "C0A075B0.afm", "NEW", {})
+    assert safe is False and "standard-14" in reason
+
+
+def test_font_safe_accepts_standard14():
+    std = {"/Resources": {"/Font": {"/F1": {"/BaseFont": "/Helvetica"}}}}
+    safe, _ = font_safe(std, "Helvetica", "NEW", {})
+    assert safe is True
+
+
+def test_parse_flags():
+    assert parse_flags("all ci") == {"scope": "all", "ci": True, "word": False}
+    assert parse_flags("3 word") == {"scope": 3, "ci": False, "word": True}
+    assert parse_flags("p2")["page"] == 2
+    assert parse_flags("") == {"scope": "first", "ci": False, "word": False}
+
+
+def test_rules_file(reps, tmp_path):
+    rules = parse_rules_file("# comment\napple | APRICOT | all\nApple | X | ci\nbanana | y")
+    assert len(rules) == 3
+    assert rules[0]["scope"] == "all"
+    o = str(tmp_path / "o.pdf")
+    rep = apply_rules(reps, o, rules)
+    assert rep["applied"] == 2 and rep["total"] == 3   # banana not found -> skipped