pdf-form-tools 2.0.0__tar.gz

pdf_form_tools-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 רומן אוסטרובסקי
+
+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.

pdf_form_tools-2.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: pdf-form-tools
+Version: 2.0.0
+Summary: Template-aware tools for filling scanned PDF forms with visual verification
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ceratops-code/pdf-form-tools
+Project-URL: Repository, https://github.com/ceratops-code/pdf-form-tools
+Project-URL: Issues, https://github.com/ceratops-code/pdf-form-tools/issues
+Keywords: pdf,forms,opencv,pymupdf,document-processing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python-headless
+Requires-Dist: pymupdf
+Requires-Dist: pillow
+Requires-Dist: pypdf
+Requires-Dist: reportlab
+Requires-Dist: python-bidi
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# pdf-form-tools
+
+`pdf-form-tools` is an import-only Python package for filling layout-sensitive scanned PDF forms with deterministic placement helpers and visual verification primitives.
+
+It is intentionally small:
+
+- render PDF pages to raster images
+- detect writable regions, checkbox boxes, signature lines, and ID slots
+- draw text, checks, and signatures onto an overlay
+- merge the overlay back into the original PDF
+
+## Install
+
+```bash
+python -m pip install pdf-form-tools
+```
+
+## Example
+
+```python
+from pathlib import Path
+
+from pdf_form_tools import Rect, merge_overlay_pdf, render_pdf_page
+
+source_pdf = Path("form.pdf")
+preview_png = Path("preview-page1.png")
+render_pdf_page(source_pdf, 0, 2, preview_png)
+
+# draw your overlay separately, then merge it back
+merge_overlay_pdf(source_pdf, Path("overlay-page1.png"), Path("form-filled.pdf"))
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m ruff check .
+python -m pytest
+python -m build
+```
+
+## Scope
+
+This package contains reusable low-level helpers only. Form-specific filling flows belong in project-local scripts or thin runners, not in the shared library.

pdf_form_tools-2.0.0/README.md

@@ -0,0 +1,44 @@
+# pdf-form-tools
+
+`pdf-form-tools` is an import-only Python package for filling layout-sensitive scanned PDF forms with deterministic placement helpers and visual verification primitives.
+
+It is intentionally small:
+
+- render PDF pages to raster images
+- detect writable regions, checkbox boxes, signature lines, and ID slots
+- draw text, checks, and signatures onto an overlay
+- merge the overlay back into the original PDF
+
+## Install
+
+```bash
+python -m pip install pdf-form-tools
+```
+
+## Example
+
+```python
+from pathlib import Path
+
+from pdf_form_tools import Rect, merge_overlay_pdf, render_pdf_page
+
+source_pdf = Path("form.pdf")
+preview_png = Path("preview-page1.png")
+render_pdf_page(source_pdf, 0, 2, preview_png)
+
+# draw your overlay separately, then merge it back
+merge_overlay_pdf(source_pdf, Path("overlay-page1.png"), Path("form-filled.pdf"))
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m ruff check .
+python -m pytest
+python -m build
+```
+
+## Scope
+
+This package contains reusable low-level helpers only. Form-specific filling flows belong in project-local scripts or thin runners, not in the shared library.

pdf_form_tools-2.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdf-form-tools"
+version = "2.0.0"
+description = "Template-aware tools for filling scanned PDF forms with visual verification"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["pdf", "forms", "opencv", "pymupdf", "document-processing"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Office/Business :: Office Suites",
+]
+urls = { Homepage = "https://github.com/ceratops-code/pdf-form-tools", Repository = "https://github.com/ceratops-code/pdf-form-tools", Issues = "https://github.com/ceratops-code/pdf-form-tools/issues" }
+dependencies = [
+  "numpy",
+  "opencv-python-headless",
+  "pymupdf",
+  "pillow",
+  "pypdf",
+  "reportlab",
+  "python-bidi",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+  "ruff>=0.6",
+  "twine>=5.1",
+]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pdf_form_tools*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"

pdf_form_tools-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdf_form_tools-2.0.0/src/pdf_form_tools/__init__.py

@@ -0,0 +1,27 @@
+from .pdf_form_overlay import (
+    Rect,
+    centered_address_box,
+    detect_lines,
+    detect_square_boxes,
+    draw_check,
+    draw_id_number,
+    draw_text,
+    merge_overlay_pdf,
+    paste_signature,
+    render_pdf_page,
+    writable_box,
+)
+
+__all__ = [
+    "Rect",
+    "centered_address_box",
+    "detect_lines",
+    "detect_square_boxes",
+    "draw_check",
+    "draw_id_number",
+    "draw_text",
+    "merge_overlay_pdf",
+    "paste_signature",
+    "render_pdf_page",
+    "writable_box",
+]

pdf_form_tools-2.0.0/src/pdf_form_tools/pdf_form_overlay.py

@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from io import BytesIO
+from pathlib import Path
+
+import cv2
+import fitz
+import numpy as np
+from bidi.algorithm import get_display
+from PIL import Image, ImageDraw, ImageFont
+from pypdf import PdfReader, PdfWriter
+from reportlab.lib.utils import ImageReader
+from reportlab.pdfgen import canvas
+
+
+TEXT_COLOR = (20, 20, 20, 255)
+FONT_CANDIDATES = {
+    False: [
+        Path(r"C:\Windows\Fonts\arial.ttf"),
+        Path("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"),
+        Path("/usr/share/fonts/truetype/liberation2/LiberationSans-Regular.ttf"),
+        Path("/Library/Fonts/Arial.ttf"),
+        Path("/System/Library/Fonts/Supplemental/Arial.ttf"),
+    ],
+    True: [
+        Path(r"C:\Windows\Fonts\arialbd.ttf"),
+        Path("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"),
+        Path("/usr/share/fonts/truetype/liberation2/LiberationSans-Bold.ttf"),
+        Path("/Library/Fonts/Arial Bold.ttf"),
+        Path("/System/Library/Fonts/Supplemental/Arial Bold.ttf"),
+    ],
+}
+
+
+@dataclass(frozen=True)
+class Rect:
+    x: int
+    y: int
+    w: int
+    h: int
+
+    @property
+    def x2(self) -> int:
+        return self.x + self.w
+
+    @property
+    def y2(self) -> int:
+        return self.y + self.h
+
+    def inset(self, dx: int, dy: int | None = None) -> "Rect":
+        if dy is None:
+            dy = dx
+        return Rect(self.x + dx, self.y + dy, self.w - dx * 2, self.h - dy * 2)
+
+
+def contains_hebrew(text: str) -> bool:
+    return any("\u0590" <= ch <= "\u05FF" for ch in text)
+
+
+def visual_text(text: str) -> str:
+    return get_display(text) if contains_hebrew(text) else text
+
+
+@lru_cache(maxsize=2)
+def resolve_font_path(bold: bool = False) -> Path:
+    for candidate in FONT_CANDIDATES[bold]:
+        if candidate.exists():
+            return candidate
+    raise FileNotFoundError(f"Could not find a usable {'bold' if bold else 'regular'} TrueType font.")
+
+
+def load_font(size: int, bold: bool = False) -> ImageFont.ImageFont:
+    font_path = resolve_font_path(bold=bold)
+    return ImageFont.truetype(str(font_path), size)
+
+
+def close_small_gaps(mask: np.ndarray, max_gap: int = 4) -> np.ndarray:
+    result = mask.copy()
+    start = None
+    for idx, value in enumerate(mask):
+        if not value and start is None:
+            start = idx
+        elif value and start is not None:
+            if idx - start <= max_gap:
+                result[start:idx] = True
+            start = None
+    if start is not None and len(mask) - start <= max_gap:
+        result[start:] = True
+    return result
+
+
+def longest_true_segment(mask: np.ndarray, min_len: int) -> tuple[int, int] | None:
+    best = None
+    start = None
+    for idx, value in enumerate(mask):
+        if value and start is None:
+            start = idx
+        elif not value and start is not None:
+            if idx - start >= min_len and (best is None or idx - start > best[1] - best[0]):
+                best = (start, idx)
+            start = None
+    if start is not None and len(mask) - start >= min_len:
+        candidate = (start, len(mask))
+        if best is None or candidate[1] - candidate[0] > best[1] - best[0]:
+            best = candidate
+    return best
+
+
+def writable_box(page_gray: np.ndarray, rect: Rect, row_threshold: float = 0.015, col_threshold: float = 0.03) -> Rect:
+    inner = rect.inset(8)
+    crop = page_gray[inner.y:inner.y2, inner.x:inner.x2]
+    ink = crop < 185
+
+    row_density = ink.mean(axis=1)
+    row_mask = row_density < row_threshold
+    row_mask[:4] = False
+    row_mask[-4:] = False
+    row_mask = close_small_gaps(row_mask, max_gap=5)
+    row_segment = longest_true_segment(row_mask, min_len=max(18, crop.shape[0] // 6))
+    if row_segment is None:
+        row_segment = (crop.shape[0] // 3, crop.shape[0] - 12)
+
+    band = crop[row_segment[0]:row_segment[1], :]
+    band_ink = band < 185
+    col_density = band_ink.mean(axis=0)
+    col_mask = col_density < col_threshold
+    col_mask[:6] = False
+    col_mask[-6:] = False
+    col_mask = close_small_gaps(col_mask, max_gap=8)
+    col_segment = longest_true_segment(col_mask, min_len=max(40, crop.shape[1] // 6))
+    if col_segment is None:
+        col_segment = (10, crop.shape[1] - 10)
+
+    box = Rect(
+        inner.x + col_segment[0],
+        inner.y + row_segment[0],
+        col_segment[1] - col_segment[0],
+        row_segment[1] - row_segment[0],
+    )
+    return box.inset(4)
+
+
+def fit_font(
+    draw: ImageDraw.ImageDraw,
+    text: str,
+    rect: Rect,
+    max_size: int,
+    min_size: int,
+    bold: bool,
+) -> tuple[ImageFont.FreeTypeFont, tuple[int, int, int, int]]:
+    prepared = visual_text(text)
+    for size in range(max_size, min_size - 1, -2):
+        font = load_font(size, bold=bold)
+        bbox = draw.textbbox((0, 0), prepared, font=font)
+        width = bbox[2] - bbox[0]
+        height = bbox[3] - bbox[1]
+        if width <= rect.w and height <= rect.h:
+            return font, bbox
+    font = load_font(min_size, bold=bold)
+    bbox = draw.textbbox((0, 0), prepared, font=font)
+    return font, bbox
+
+
+def draw_text(
+    draw: ImageDraw.ImageDraw,
+    text: str,
+    rect: Rect,
+    *,
+    align: str,
+    max_size: int,
+    min_size: int,
+    bold: bool = False,
+    fill: tuple[int, int, int, int] = TEXT_COLOR,
+) -> None:
+    prepared = visual_text(text)
+    font, bbox = fit_font(draw, text, rect, max_size=max_size, min_size=min_size, bold=bold)
+    width = bbox[2] - bbox[0]
+    height = bbox[3] - bbox[1]
+
+    if align == "right":
+        x = rect.x2 - width - bbox[0]
+    elif align == "left":
+        x = rect.x - bbox[0]
+    else:
+        x = rect.x + (rect.w - width) / 2 - bbox[0]
+
+    y = rect.y + (rect.h - height) / 2 - bbox[1]
+    draw.text((x, y), prepared, font=font, fill=fill)
+
+
+def centered_address_box(rect: Rect, *, top_pad: int, side_pad: int, height: int, right_pad: int | None = None) -> Rect:
+    if right_pad is None:
+        right_pad = side_pad
+    return Rect(rect.x + side_pad, rect.y + top_pad, rect.w - side_pad - right_pad, height)
+
+
+def detect_square_boxes(page_gray: np.ndarray, region: Rect) -> list[Rect]:
+    crop = page_gray[region.y:region.y2, region.x:region.x2]
+    _, thresh = cv2.threshold(crop, 210, 255, cv2.THRESH_BINARY_INV)
+    contours, _ = cv2.findContours(thresh, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+    boxes: list[Rect] = []
+    for contour in contours:
+        x, y, w, h = cv2.boundingRect(contour)
+        if 40 <= w <= 60 and 40 <= h <= 60 and 0.8 <= (w / h) <= 1.25:
+            candidate = Rect(region.x + x, region.y + y, w, h)
+            if any(abs(candidate.x - existing.x) < 5 and abs(candidate.y - existing.y) < 5 for existing in boxes):
+                continue
+            boxes.append(candidate)
+    return sorted(boxes, key=lambda item: (item.y, item.x))
+
+
+def detect_lines(page_gray: np.ndarray, region: Rect) -> list[Rect]:
+    crop = page_gray[region.y:region.y2, region.x:region.x2]
+    _, thresh = cv2.threshold(crop, 200, 255, cv2.THRESH_BINARY_INV)
+    contours, _ = cv2.findContours(thresh, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+    lines: list[Rect] = []
+    for contour in contours:
+        x, y, w, h = cv2.boundingRect(contour)
+        if 500 <= w <= 900 and h <= 12:
+            candidate = Rect(region.x + x, region.y + y, w, h)
+            if any(abs(candidate.x - existing.x) < 10 and abs(candidate.y - existing.y) < 10 for existing in lines):
+                continue
+            lines.append(candidate)
+    return sorted(lines, key=lambda item: item.x)
+
+
+def detect_id_slots(page_gray: np.ndarray, rect: Rect) -> list[Rect]:
+    crop = page_gray[rect.y:rect.y2, rect.x:rect.x2]
+    guide_start = int(crop.shape[0] * 0.7)
+    lower = crop[guide_start:, :]
+    ink = lower < 180
+
+    row_sum = ink.sum(axis=1)
+    first_guide_row = next((idx + guide_start for idx, value in enumerate(row_sum) if value >= 6), int(crop.shape[0] * 0.82))
+
+    col_sum = ink.sum(axis=0)
+    peak_columns = [idx for idx, value in enumerate(col_sum) if value >= 8]
+    ranges: list[tuple[int, int]] = []
+    start = None
+    prev = None
+    for idx in peak_columns:
+        if start is None:
+            start = idx
+            prev = idx
+            continue
+        if idx == prev + 1:
+            prev = idx
+            continue
+        ranges.append((start, prev))
+        start = idx
+        prev = idx
+    if start is not None and prev is not None:
+        ranges.append((start, prev))
+
+    boundaries = [0]
+    for left, right in ranges:
+        center = int(round((left + right) / 2))
+        if 4 < center < crop.shape[1] - 5:
+            boundaries.append(center)
+    boundaries.append(crop.shape[1] - 1)
+    boundaries = sorted(set(boundaries))
+
+    if len(boundaries) != 10:
+        raise RuntimeError(f"Expected 10 ID slot boundaries, found {len(boundaries)} for {rect}.")
+
+    digit_top = rect.y + first_guide_row - int(rect.h * 0.34)
+    digit_height = int(rect.h * 0.48)
+    slots: list[Rect] = []
+    for left, right in zip(boundaries, boundaries[1:]):
+        slots.append(Rect(rect.x + left + 3, digit_top, right - left - 6, digit_height))
+    return slots
+
+
+def draw_id_number(draw: ImageDraw.ImageDraw, page_gray: np.ndarray, rect: Rect, number: str) -> None:
+    slots = detect_id_slots(page_gray, rect)
+    if len(number) != len(slots):
+        raise RuntimeError(f"ID length {len(number)} does not match detected slot count {len(slots)}.")
+    for digit, slot in zip(number, slots):
+        draw_text(draw, digit, slot, align="center", max_size=74, min_size=54)
+
+
+def draw_check(
+    draw: ImageDraw.ImageDraw,
+    rect: Rect,
+    *,
+    raise_px: int = 10,
+    fill: tuple[int, int, int, int] = TEXT_COLOR,
+) -> None:
+    x0, y0 = rect.x, rect.y
+    width = max(10, rect.w // 4)
+    p1 = (x0 + rect.w * 0.18, y0 + rect.h * 0.54 - raise_px)
+    p2 = (x0 + rect.w * 0.43, y0 + rect.h * 0.80 - raise_px)
+    p3 = (x0 + rect.w * 0.83, y0 + rect.h * 0.20 - raise_px)
+    draw.line([p1, p2], fill=fill, width=width)
+    draw.line([p2, p3], fill=fill, width=width)
+
+
+def paste_signature(
+    overlay: Image.Image,
+    signature: Image.Image,
+    line_rect: Rect,
+    *,
+    min_cm_width: float = 2.0,
+    target_height: int | None = None,
+    y_offset: int = 45,
+) -> None:
+    alpha_bbox = signature.getchannel("A").getbbox()
+    if alpha_bbox:
+        signature = signature.crop(alpha_bbox)
+
+    min_signature_width = int(round((overlay.width / 21.0) * min_cm_width))
+    target_width = max(min_signature_width, int(line_rect.w * 0.55))
+    if target_height is None:
+        target_height = 260
+    resized = signature.resize((target_width, target_height), Image.Resampling.LANCZOS)
+    x = int(line_rect.x + (line_rect.w - target_width) / 2)
+    y = int(line_rect.y - target_height + y_offset)
+    overlay.alpha_composite(resized, (x, y))
+
+
+def render_pdf_page(pdf_path: Path, page_index: int, scale: int, out_path: Path) -> Image.Image:
+    document = fitz.open(pdf_path)
+    try:
+        page = document[page_index]
+        pixmap = page.get_pixmap(matrix=fitz.Matrix(scale, scale), alpha=False)
+        image = Image.frombytes("RGB", (pixmap.width, pixmap.height), pixmap.samples)
+        image.save(out_path)
+        return image
+    finally:
+        document.close()
+
+
+def merge_overlay_pdf(src_pdf: Path, overlay_png: Path, out_pdf: Path) -> None:
+    reader = PdfReader(str(src_pdf))
+    writer = PdfWriter()
+
+    page = reader.pages[0]
+    width = float(page.mediabox.width)
+    height = float(page.mediabox.height)
+
+    overlay_buffer = BytesIO()
+    c = canvas.Canvas(overlay_buffer, pagesize=(width, height))
+    c.drawImage(ImageReader(str(overlay_png)), 0, 0, width=width, height=height, mask="auto")
+    c.save()
+    overlay_buffer.seek(0)
+    overlay_reader = PdfReader(overlay_buffer)
+
+    merged_page = page
+    merged_page.merge_page(overlay_reader.pages[0])
+    writer.add_page(merged_page)
+    for extra_page in reader.pages[1:]:
+        writer.add_page(extra_page)
+
+    with out_pdf.open("wb") as handle:
+        writer.write(handle)

pdf_form_tools-2.0.0/src/pdf_form_tools.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: pdf-form-tools
+Version: 2.0.0
+Summary: Template-aware tools for filling scanned PDF forms with visual verification
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ceratops-code/pdf-form-tools
+Project-URL: Repository, https://github.com/ceratops-code/pdf-form-tools
+Project-URL: Issues, https://github.com/ceratops-code/pdf-form-tools/issues
+Keywords: pdf,forms,opencv,pymupdf,document-processing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Office/Business :: Office Suites
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python-headless
+Requires-Dist: pymupdf
+Requires-Dist: pillow
+Requires-Dist: pypdf
+Requires-Dist: reportlab
+Requires-Dist: python-bidi
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# pdf-form-tools
+
+`pdf-form-tools` is an import-only Python package for filling layout-sensitive scanned PDF forms with deterministic placement helpers and visual verification primitives.
+
+It is intentionally small:
+
+- render PDF pages to raster images
+- detect writable regions, checkbox boxes, signature lines, and ID slots
+- draw text, checks, and signatures onto an overlay
+- merge the overlay back into the original PDF
+
+## Install
+
+```bash
+python -m pip install pdf-form-tools
+```
+
+## Example
+
+```python
+from pathlib import Path
+
+from pdf_form_tools import Rect, merge_overlay_pdf, render_pdf_page
+
+source_pdf = Path("form.pdf")
+preview_png = Path("preview-page1.png")
+render_pdf_page(source_pdf, 0, 2, preview_png)
+
+# draw your overlay separately, then merge it back
+merge_overlay_pdf(source_pdf, Path("overlay-page1.png"), Path("form-filled.pdf"))
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m ruff check .
+python -m pytest
+python -m build
+```
+
+## Scope
+
+This package contains reusable low-level helpers only. Form-specific filling flows belong in project-local scripts or thin runners, not in the shared library.

pdf_form_tools-2.0.0/src/pdf_form_tools.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/pdf_form_tools/__init__.py
+src/pdf_form_tools/pdf_form_overlay.py
+src/pdf_form_tools.egg-info/PKG-INFO
+src/pdf_form_tools.egg-info/SOURCES.txt
+src/pdf_form_tools.egg-info/dependency_links.txt
+src/pdf_form_tools.egg-info/requires.txt
+src/pdf_form_tools.egg-info/top_level.txt
+tests/test_pdf_form_overlay.py

pdf_form_tools-2.0.0/src/pdf_form_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pdf_form_tools-2.0.0/src/pdf_form_tools.egg-info/requires.txt

@@ -0,0 +1,13 @@
+numpy
+opencv-python-headless
+pymupdf
+pillow
+pypdf
+reportlab
+python-bidi
+
+[dev]
+build>=1.2
+pytest>=8.0
+ruff>=0.6
+twine>=5.1

pdf_form_tools-2.0.0/src/pdf_form_tools.egg-info/top_level.txt

@@ -0,0 +1 @@
+pdf_form_tools

pdf_form_tools-2.0.0/tests/test_pdf_form_overlay.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+import pdf_form_tools.pdf_form_overlay as overlay
+from pdf_form_tools import Rect, centered_address_box
+
+
+def test_rect_inset() -> None:
+    assert Rect(10, 20, 30, 40).inset(5) == Rect(15, 25, 20, 30)
+
+
+def test_centered_address_box() -> None:
+    rect = Rect(100, 200, 400, 120)
+    assert centered_address_box(rect, top_pad=10, side_pad=20, height=50) == Rect(120, 210, 360, 50)
+
+
+def test_load_font_uses_existing_system_font() -> None:
+    font = overlay.load_font(18, bold=False)
+    assert font is not None
+    assert Path(overlay.resolve_font_path()).exists()
+
+
+def test_contains_hebrew_detects_hebrew_characters() -> None:
+    assert overlay.contains_hebrew("אמילי")
+    assert not overlay.contains_hebrew("Emily")