pdf-sign-kit 0.5.0__py3-none-any.whl

pdf_sign_kit/__init__.py

@@ -0,0 +1,190 @@
+"""pdf-sign-kit: a framework-agnostic toolkit for stamping signatures and
+text onto PDF files, with automatic table-cell detection, cross-platform CJK
+font support, page preview rendering and integrity hashing.
+
+Coordinate convention
+---------------------
+All public stamping functions take ``x`` / ``y`` in PDF points with the page's
+**bottom-left** origin (i.e. the orientation the page is displayed in); page
+rotation is handled internally. Page indices are zero-based.
+
+Note: image stamps are visual ("electronic") signatures, not PKI/certificate
+("digital") signatures.
+"""
+
+from __future__ import annotations
+
+from . import (
+    anchor,
+    background,
+    compose,
+    fonts,
+    geometry,
+    hashing,
+    identity,
+    keywords,
+    logtable,
+    placement,
+    preview,
+    scheme,
+    seam,
+    stamps,
+    template,
+    text,
+    watermark,
+    workflow,
+)
+from .anchor import AFTER, BELOW, OVER, TextAnchor, find_all_text, find_text, stamp_at_anchor
+from .background import remove_background
+from .compose import TRANSPARENT, hconcat, scale_to_height, scale_to_width, vconcat
+from .exceptions import (
+    FontNotFoundError,
+    InvalidImageError,
+    InvalidPdfError,
+    PageOutOfRangeError,
+    PdfSignKitError,
+    PlacementError,
+)
+from .geometry import TableCell, find_table_cell
+from .hashing import hash_file, verify_file_hash
+from .identity import bare_id, identity_matches
+from .keywords import extract_keywords
+from .logtable import render_log_data_url, render_log_image, render_log_png_bytes
+from .placement import (
+    AGREE,
+    CHECKMARK,
+    GENERAL,
+    HANDWRITTEN,
+    TEXT,
+    StampResult,
+    stamp,
+    stamp_batch,
+)
+from .preview import page_count, page_size, render_page, render_page_png
+from .scheme import (
+    DEFAULT_LEVEL_NAMES,
+    DEPARTMENT,
+    GROUP,
+    PERSONAL,
+    FlowScheme,
+    Initiator,
+    LevelSpec,
+    build_metadata,
+)
+from .seam import LEFT, RIGHT, stamp_seam
+from .stamps import (
+    make_agree_image,
+    make_checkmark_image,
+    stamp_agree,
+    stamp_checkmark,
+)
+from .template import OpSpec, PlacementTemplate, load_template, save_template
+from .text import (
+    TextImage,
+    render_text_image,
+    render_wrapped_text_image,
+    stamp_text,
+)
+from .watermark import DEFAULT_COLOR, render_watermark_overlay, stamp_watermark
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "__version__",
+    # submodules
+    "anchor",
+    "background",
+    "compose",
+    "fonts",
+    "geometry",
+    "identity",
+    "keywords",
+    "logtable",
+    "preview",
+    "hashing",
+    "scheme",
+    "placement",
+    "seam",
+    "stamps",
+    "template",
+    "text",
+    "watermark",
+    "workflow",
+    # exceptions
+    "PdfSignKitError",
+    "InvalidPdfError",
+    "InvalidImageError",
+    "PageOutOfRangeError",
+    "FontNotFoundError",
+    "PlacementError",
+    # placement
+    "GENERAL",
+    "HANDWRITTEN",
+    "TEXT",
+    "AGREE",
+    "CHECKMARK",
+    "StampResult",
+    "stamp",
+    "stamp_batch",
+    # compose
+    "TRANSPARENT",
+    "hconcat",
+    "vconcat",
+    "scale_to_height",
+    "scale_to_width",
+    # anchor
+    "AFTER",
+    "BELOW",
+    "OVER",
+    "TextAnchor",
+    "find_text",
+    "find_all_text",
+    "stamp_at_anchor",
+    # watermark / seam
+    "DEFAULT_COLOR",
+    "render_watermark_overlay",
+    "stamp_watermark",
+    "RIGHT",
+    "LEFT",
+    "stamp_seam",
+    # template
+    "OpSpec",
+    "PlacementTemplate",
+    "save_template",
+    "load_template",
+    # stamps
+    "make_checkmark_image",
+    "make_agree_image",
+    "stamp_checkmark",
+    "stamp_agree",
+    # text
+    "TextImage",
+    "render_text_image",
+    "render_wrapped_text_image",
+    "stamp_text",
+    # scheme
+    "PERSONAL",
+    "GROUP",
+    "DEPARTMENT",
+    "DEFAULT_LEVEL_NAMES",
+    "LevelSpec",
+    "FlowScheme",
+    "Initiator",
+    "build_metadata",
+    # geometry / hashing / identity / background / preview / logtable / keywords
+    "TableCell",
+    "find_table_cell",
+    "hash_file",
+    "verify_file_hash",
+    "bare_id",
+    "identity_matches",
+    "remove_background",
+    "page_count",
+    "page_size",
+    "render_page",
+    "render_page_png",
+    "render_log_image",
+    "render_log_png_bytes",
+    "render_log_data_url",
+    "extract_keywords",
+]

pdf_sign_kit/anchor.py

@@ -0,0 +1,213 @@
+"""Text-anchor placement.
+
+Locate a position on a PDF page by searching for visible text (e.g.
+``"签字："``) rather than by detecting table borders. This complements
+:mod:`pdf_sign_kit.geometry` for borderless contracts and blank form
+templates.
+
+The search runs on the page in its display orientation, so returned
+coordinates follow the same bottom-left-origin convention as
+:func:`pdf_sign_kit.stamp`.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+
+import fitz
+
+from .exceptions import InvalidPdfError, PageOutOfRangeError
+from .geometry import TableCell
+from .placement import GENERAL, ImageLike, StampResult, stamp
+
+# Where to place content relative to the matched text.
+AFTER = "after"  # immediately right of the text, vertically centered
+BELOW = "below"  # immediately under the text, left aligned
+OVER = "over"  # centered over the text itself
+
+_POSITIONS = frozenset({AFTER, BELOW, OVER})
+
+
+class TextAnchor:
+    """A matched text rectangle (top-left origin, PDF points, display space)."""
+
+    def __init__(
+        self,
+        page: int,
+        rect: fitz.Rect,
+        matched_text: str,
+    ) -> None:
+        self.page = int(page)
+        self.rect = rect
+        self.left = float(rect.x0)
+        self.top = float(rect.y0)
+        self.width = float(rect.width)
+        self.height = float(rect.height)
+        self.matched_text = matched_text
+
+    def __repr__(self) -> str:
+        return (
+            f"TextAnchor(page={self.page}, left={self.left:.1f}, top={self.top:.1f}, "
+            f"width={self.width:.1f}, height={self.height:.1f}, text={self.matched_text!r})"
+        )
+
+    def point(
+        self,
+        page_height: float,
+        position: str = AFTER,
+        gap: float = 3.0,
+    ) -> tuple[float, float]:
+        """Return bottom-left-origin ``(x, y)`` for the chosen placement spot."""
+        if position not in _POSITIONS:
+            raise ValueError(f"position must be one of {sorted(_POSITIONS)}, got {position!r}")
+        if gap < 0:
+            raise ValueError("gap must be >= 0")
+
+        center_x = self.left + self.width / 2
+        center_y_top = self.top + self.height / 2
+
+        if position == AFTER:
+            x = self.left + self.width + gap
+            y = page_height - center_y_top
+        elif position == BELOW:
+            x = self.left
+            y = page_height - (self.top + self.height + gap)
+        else:  # OVER
+            x = center_x
+            y = page_height - center_y_top
+        return x, y
+
+    def to_cell(self) -> TableCell:
+        """Expose the text rect as a placement cell."""
+        return TableCell(self.left, self.top, self.width, self.height, self.left)
+
+
+def _open_doc(pdf_path: str | os.PathLike) -> fitz.Document:
+    try:
+        return fitz.open(os.fspath(pdf_path))
+    except Exception as exc:
+        raise InvalidPdfError(f"cannot open PDF {pdf_path}: {exc}") from exc
+
+
+def find_all_text(
+    pdf_path: str | os.PathLike,
+    text: str,
+    *,
+    pages: Sequence[int] | None = None,
+) -> list[TextAnchor]:
+    """Find every occurrence of ``text``.
+
+    :param pages: restrict search to these zero-based page indices; ``None``
+        searches the whole document. Multi-line matches are reported with the
+        bounding box of all their line rectangles.
+    """
+    if not text:
+        raise ValueError("search text must not be empty")
+
+    doc = _open_doc(pdf_path)
+    try:
+        if pages is None:
+            target_pages = range(doc.page_count)
+        else:
+            target_pages = list(dict.fromkeys(int(p) for p in pages))
+            for p in target_pages:
+                if p < 0 or p >= doc.page_count:
+                    raise PageOutOfRangeError(
+                        f"page {p} out of range (document has {doc.page_count} pages)"
+                    )
+
+        anchors: list[TextAnchor] = []
+        for page_index in target_pages:
+            page = doc[page_index]
+            # Each returned rect is one distinct match position (a multi-line
+            # search text produces one rect per line, each independently
+            # placeable).
+            for rect in page.search_for(text):
+                anchors.append(TextAnchor(page_index, fitz.Rect(rect), text))
+        return anchors
+    finally:
+        doc.close()
+
+
+def find_text(
+    pdf_path: str | os.PathLike,
+    text: str,
+    *,
+    page: int | None = None,
+    occurrence: int = 0,
+) -> TextAnchor | None:
+    """Find one occurrence of ``text``.
+
+    :param page: zero-based page index; ``None`` searches the whole document.
+    :param occurrence: zero-based index among ordered matches (page order, then
+        in-page order).
+    """
+    if occurrence < 0:
+        raise ValueError("occurrence must be >= 0")
+
+    pages = None if page is None else [int(page)]
+    if page is not None and int(page) < 0:
+        raise ValueError("page must be >= 0")
+
+    anchors = find_all_text(pdf_path, text, pages=pages)
+    if occurrence >= len(anchors):
+        return None
+    return anchors[occurrence]
+
+
+def stamp_at_anchor(
+    pdf_path: str | os.PathLike,
+    image: ImageLike,
+    anchor: TextAnchor,
+    *,
+    position: str = AFTER,
+    gap: float = 3.0,
+    page: int | None = None,
+    out_path: str | os.PathLike | None = None,
+    width: float | None = None,
+    height: float | None = None,
+) -> StampResult:
+    """Stamp ``image`` relative to a text anchor.
+
+    Table-cell detection is skipped (the anchor itself defines the location);
+    the image keeps its natural or explicit size.
+    """
+    if not isinstance(anchor, TextAnchor):
+        raise TypeError(f"anchor must be a TextAnchor, got {type(anchor)!r}")
+
+    doc = _open_doc(pdf_path)
+    try:
+        if anchor.page < 0 or anchor.page >= doc.page_count:
+            raise PageOutOfRangeError(
+                f"anchor page {anchor.page} out of range (document has {doc.page_count} pages)"
+            )
+        page_height = doc[anchor.page].rect.height
+    finally:
+        doc.close()
+
+    x, y = anchor.point(page_height, position, gap)
+    target_page = anchor.page if page is None else int(page)
+    return stamp(
+        pdf_path,
+        image,
+        x,
+        y,
+        page=target_page,
+        out_path=out_path,
+        width=width,
+        height=height,
+        mode=GENERAL,
+        detect_cell=False,
+    )
+
+
+__all__ = [
+    "AFTER",
+    "BELOW",
+    "OVER",
+    "TextAnchor",
+    "find_text",
+    "find_all_text",
+    "stamp_at_anchor",
+]

pdf_sign_kit/background.py

@@ -0,0 +1,55 @@
+"""Turn handwriting/scan images into transparent-PNG stamps."""
+
+from __future__ import annotations
+
+import io
+import os
+from typing import Union
+
+import numpy as np
+from PIL import Image
+
+from .exceptions import InvalidImageError
+
+ImageLike = Union[str, os.PathLike, Image.Image, bytes]
+
+
+def _to_pil(image: ImageLike) -> Image.Image:
+    if isinstance(image, Image.Image):
+        return image
+    if isinstance(image, (str, os.PathLike)):
+        path = os.fspath(image)
+        try:
+            return Image.open(path)
+        except Exception as exc:
+            raise InvalidImageError(f"cannot open image {path}: {exc}") from exc
+    if isinstance(image, bytes):
+        try:
+            return Image.open(io.BytesIO(image))
+        except Exception as exc:
+            raise InvalidImageError(f"cannot decode image bytes: {exc}") from exc
+    raise InvalidImageError(f"unsupported image type: {type(image)!r}")
+
+
+def remove_background(image: ImageLike, threshold: int = 235) -> Image.Image:
+    """Make near-white pixels transparent.
+
+    :param image: PIL image, file path, or raw image bytes.
+    :param threshold: per-channel whiteness threshold (0-255); pixels whose
+        RGB values are all >= threshold become fully transparent.
+    :returns: RGBA :class:`~PIL.Image.Image`.
+    """
+    if not 0 <= threshold <= 255:
+        raise ValueError(f"threshold must be within 0-255, got {threshold!r}")
+
+    img = _to_pil(image)
+    if img.mode != "RGBA":
+        img = img.convert("RGBA")
+
+    data = np.array(img)
+    white_mask = np.all(data[:, :, :3] >= threshold, axis=2)
+    data[white_mask, 3] = 0
+    return Image.fromarray(data)
+
+
+__all__ = ["remove_background"]

pdf_sign_kit/compose.py

@@ -0,0 +1,142 @@
+"""Bitmap composition helpers.
+
+Concatenate multiple PIL images horizontally or vertically with control over
+cross-axis alignment, gaps and the canvas background. All functions accept PIL
+images and return new images; inputs are never modified. RGBA inputs keep their
+transparency when the canvas is also RGBA.
+
+Typical use: assemble a "name + date" signature strip, or stack a name row over
+a date row before stamping the combined image onto a PDF.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from PIL import Image
+
+# Canvas background: transparent by default so composed stamps can be overlaid
+# without white boxes. Pass an RGB/RGBA tuple to force a different background.
+TRANSPARENT = (255, 255, 255, 0)
+
+_H_ALIGN = frozenset({"top", "middle", "bottom"})
+_V_ALIGN = frozenset({"left", "center", "right"})
+
+
+def _normalize(images: Sequence[Image.Image]) -> list[Image.Image]:
+    normalized: list[Image.Image] = []
+    for img in images:
+        if not isinstance(img, Image.Image):
+            raise TypeError(f"compose expects PIL images, got {type(img)!r}")
+        normalized.append(img if img.mode == "RGBA" else img.convert("RGBA"))
+    if not normalized:
+        raise ValueError("compose requires at least one image")
+    return normalized
+
+
+def _canvas(size: tuple[int, int], background) -> Image.Image:
+    mode = "RGBA"
+    return Image.new(mode, size, background if background is not None else TRANSPARENT)
+
+
+def hconcat(
+    images: Sequence[Image.Image],
+    *,
+    gap: int = 0,
+    align: str = "middle",
+    background=TRANSPARENT,
+) -> Image.Image:
+    """Concatenate images left-to-right.
+
+    :param gap: pixel gap inserted between adjacent images.
+    :param align: cross-axis alignment: ``"top"`` / ``"middle"`` / ``"bottom"``.
+    """
+    images = _normalize(images)
+    if align not in _H_ALIGN:
+        raise ValueError(f"align must be one of {sorted(_H_ALIGN)}, got {align!r}")
+    if gap < 0:
+        raise ValueError("gap must be >= 0")
+
+    total_w = sum(img.width for img in images) + gap * (len(images) - 1)
+    total_h = max(img.height for img in images)
+    canvas = _canvas((total_w, total_h), background)
+
+    x = 0
+    for img in images:
+        if align == "top":
+            y = 0
+        elif align == "bottom":
+            y = total_h - img.height
+        else:
+            y = (total_h - img.height) // 2
+        canvas.alpha_composite(img, (x, y))
+        x += img.width + gap
+    return canvas
+
+
+def vconcat(
+    images: Sequence[Image.Image],
+    *,
+    gap: int = 0,
+    align: str = "left",
+    background=TRANSPARENT,
+) -> Image.Image:
+    """Concatenate images top-to-bottom.
+
+    :param gap: pixel gap inserted between adjacent images.
+    :param align: cross-axis alignment: ``"left"`` / ``"center"`` / ``"right"``.
+    """
+    images = _normalize(images)
+    if align not in _V_ALIGN:
+        raise ValueError(f"align must be one of {sorted(_V_ALIGN)}, got {align!r}")
+    if gap < 0:
+        raise ValueError("gap must be >= 0")
+
+    total_w = max(img.width for img in images)
+    total_h = sum(img.height for img in images) + gap * (len(images) - 1)
+    canvas = _canvas((total_w, total_h), background)
+
+    y = 0
+    for img in images:
+        if align == "left":
+            x = 0
+        elif align == "right":
+            x = total_w - img.width
+        else:
+            x = (total_w - img.width) // 2
+        canvas.alpha_composite(img, (x, y))
+        y += img.height + gap
+    return canvas
+
+
+def scale_to_height(img: Image.Image, target_height: int) -> Image.Image:
+    """Return a copy of ``img`` resized to ``target_height`` px, width proportional."""
+    if not isinstance(img, Image.Image):
+        raise TypeError(f"expected a PIL image, got {type(img)!r}")
+    if target_height <= 0:
+        raise ValueError("target_height must be > 0")
+    if img.height == target_height:
+        return img.copy()
+    target_width = max(1, round(img.width * target_height / img.height))
+    return img.resize((target_width, target_height), Image.LANCZOS)
+
+
+def scale_to_width(img: Image.Image, target_width: int) -> Image.Image:
+    """Return a copy of ``img`` resized to ``target_width`` px, height proportional."""
+    if not isinstance(img, Image.Image):
+        raise TypeError(f"expected a PIL image, got {type(img)!r}")
+    if target_width <= 0:
+        raise ValueError("target_width must be > 0")
+    if img.width == target_width:
+        return img.copy()
+    target_height = max(1, round(img.height * target_width / img.width))
+    return img.resize((target_width, target_height), Image.LANCZOS)
+
+
+__all__ = [
+    "TRANSPARENT",
+    "hconcat",
+    "vconcat",
+    "scale_to_height",
+    "scale_to_width",
+]

pdf_sign_kit/exceptions.py

@@ -0,0 +1,27 @@
+"""Exception hierarchy for pdf-sign-kit."""
+
+from __future__ import annotations
+
+
+class PdfSignKitError(Exception):
+    """Base class for all pdf-sign-kit errors."""
+
+
+class InvalidPdfError(PdfSignKitError):
+    """The path does not point to a readable/valid PDF file."""
+
+
+class InvalidImageError(PdfSignKitError):
+    """The supplied image bytes/path cannot be decoded."""
+
+
+class PageOutOfRangeError(PdfSignKitError):
+    """Requested page index is outside the document's page range."""
+
+
+class FontNotFoundError(PdfSignKitError):
+    """No usable font was found and no explicit font path was provided."""
+
+
+class PlacementError(PdfSignKitError):
+    """The image/text could not be placed or the output commit failed."""