exis-pdfeditor 3.4.1__py3-none-win_amd64.whl

exis_pdfeditor-3.4.1.data/purelib/exis_pdfeditor/__init__.py

@@ -0,0 +1,774 @@
+"""
+Exis.PdfEditor — Python wrapper for the exis-pdf CLI.
+
+Comprehensive PDF toolkit: find/replace, merge, split, form filling, redaction,
+image editing, watermark, page editing, encryption, optimization, digital
+signatures, PDF/A compliance, and more.
+
+Quick start::
+
+    import exis_pdfeditor
+
+    # Point to the native CLI binary (built with Native AOT)
+    exis_pdfeditor.set_cli_path("/path/to/exis-pdf")
+
+    # Optional: set license key (or use EXIS_PDF_LICENSE_KEY env var)
+    exis_pdfeditor.initialize("XXXX-XXXX-XXXX-XXXX")
+
+    # Inspect a PDF (free, no license required)
+    info = exis_pdfeditor.inspect("document.pdf")
+    print(info.pageCount, info.title)
+
+    # Find and replace
+    result = exis_pdfeditor.find_replace(
+        "input.pdf", "output.pdf", "old text", "new text",
+        case_sensitive=False,
+    )
+    print(result.totalReplacements)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Sequence
+
+from ._cli import (
+    PdfEditorError,
+    LicenseError,
+    EvaluationLimitError,
+    run as _run,
+    set_cli_path,
+    set_license_key,
+)
+
+__all__ = [
+    # Setup
+    "set_cli_path",
+    "set_license_key",
+    "initialize",
+    # Exceptions
+    "PdfEditorError",
+    "LicenseError",
+    "EvaluationLimitError",
+    # Inspection / text
+    "inspect",
+    "dump_structure",
+    "extract_text",
+    "extract_text_structured",
+    # Find & replace
+    "find_replace",
+    # Merge / split
+    "merge",
+    "split",
+    "extract_pages",
+    # Forms
+    "list_fields",
+    "fill_form",
+    # Redaction
+    "redact",
+    # Watermark / stamp
+    "watermark",
+    "stamp",
+    # Optimization
+    "optimize",
+    # Security
+    "encrypt",
+    "decrypt",
+    # Page editing
+    "rotate",
+    "crop",
+    "reorder",
+    "delete_pages",
+    # Images
+    "find_images",
+    "replace_image",
+    # Signatures
+    "sign",
+    "verify",
+    # PDF/A
+    "pdfa_validate",
+    "pdfa_convert",
+]
+
+__version__ = "3.4.1"
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Setup
+# ═══════════════════════════════════════════════════════════════════════
+
+def initialize(license_key: str | None = None) -> None:
+    """Store the license key for all subsequent operations.
+
+    Parameters
+    ----------
+    license_key : str, optional
+        License key in ``XXXX-XXXX-XXXX-XXXX`` format.
+        If None, the library operates in trial/evaluation mode.
+        Can also be set via the ``EXIS_PDF_LICENSE_KEY`` environment variable.
+    """
+    set_license_key(license_key)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Inspection / text extraction
+# ═══════════════════════════════════════════════════════════════════════
+
+def inspect(input_path: str) -> Any:
+    """Inspect PDF metadata, page info, fonts, and structure.
+
+    No license required.
+
+    Returns a namespace with attributes: ``version``, ``pageCount``,
+    ``title``, ``author``, ``producer``, ``creator``, ``creationDate``,
+    ``modificationDate``, ``isEncrypted``, ``hasFormFields``,
+    ``formFieldCount``, ``hasDigitalSignatures``, ``fontsUsed``, ``pages``.
+    """
+    return _run("inspect", input=input_path)
+
+
+def dump_structure(input_path: str) -> Any:
+    """Low-level structural dump for diagnostics. No license required."""
+    return _run("dump-structure", input=input_path)
+
+
+def extract_text(
+    input_path: str,
+    *,
+    pages: Sequence[int] | None = None,
+) -> Any:
+    """Extract plain text from a PDF.
+
+    Returns a namespace with ``pages`` (list of {pageNumber, text})
+    and ``fullText``.
+    """
+    return _run(
+        "extract-text",
+        input=input_path,
+        pages=_int_csv(pages),
+    )
+
+
+def extract_text_structured(
+    input_path: str,
+    *,
+    pages: Sequence[int] | None = None,
+) -> Any:
+    """Extract structured text with position and font metadata.
+
+    Each text block includes ``x``, ``y``, ``fontName``, ``fontSize``.
+    """
+    return _run(
+        "extract-text",
+        input=input_path,
+        pages=_int_csv(pages),
+        structured=True,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Find & replace
+# ═══════════════════════════════════════════════════════════════════════
+
+def find_replace(
+    input_path: str,
+    output_path: str,
+    search: str | None = None,
+    replace: str | None = None,
+    *,
+    pairs: list[dict[str, Any]] | None = None,
+    case_sensitive: bool = True,
+    whole_word: bool = False,
+    use_regex: bool = False,
+    page_range: Sequence[int] | None = None,
+    text_fitting: str = "none",
+    min_horizontal_scale: int = 70,
+    max_font_size_reduction: float = 1.5,
+    preserve_form_fields: bool = True,
+    use_incremental_update: bool = True,
+    replacement_text_color: dict | None = None,
+    replacement_highlight_color: dict | None = None,
+    replacement_bold: bool = False,
+    replacement_underline: bool = False,
+    replacement_strikethrough: bool = False,
+) -> Any:
+    """Find and replace text in a PDF.
+
+    Either provide ``search``/``replace`` for a single pair, or ``pairs``
+    as a list of ``{"search": "...", "replace": "...", "isRegex": false}``.
+
+    Returns a namespace with ``totalReplacements``, ``pagesModified``,
+    ``pagesSearched``, ``details``, ``warnings``.
+    """
+    fitting_map = {
+        "none": 0, "preserve_width": 1, "fit_to_page": 2, "adaptive": 3,
+    }
+
+    options: dict[str, Any] = {}
+    if not case_sensitive:
+        options["caseSensitive"] = False
+    if whole_word:
+        options["wholeWordOnly"] = True
+    if use_regex:
+        options["useRegex"] = True
+    if page_range:
+        options["pageRange"] = list(page_range)
+    if text_fitting != "none":
+        options["textFitting"] = fitting_map.get(text_fitting, 0)
+    if min_horizontal_scale != 70:
+        options["minHorizontalScale"] = min_horizontal_scale
+    if max_font_size_reduction != 1.5:
+        options["maxFontSizeReduction"] = max_font_size_reduction
+    if not preserve_form_fields:
+        options["preserveFormFields"] = False
+    if not use_incremental_update:
+        options["useIncrementalUpdate"] = False
+    if replacement_text_color:
+        options["replacementTextColor"] = replacement_text_color
+    if replacement_highlight_color:
+        options["replacementHighlightColor"] = replacement_highlight_color
+    if replacement_bold:
+        options["replacementBold"] = True
+    if replacement_underline:
+        options["replacementUnderline"] = True
+    if replacement_strikethrough:
+        options["replacementStrikethrough"] = True
+
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+    }
+    if options:
+        kwargs["options"] = json.dumps(options)
+
+    if pairs is not None:
+        kwargs["pairs"] = json.dumps(pairs)
+    else:
+        if search is None or replace is None:
+            raise ValueError("Provide either search/replace or pairs.")
+        kwargs["search"] = search
+        kwargs["replace"] = replace
+
+    return _run("find-replace", **kwargs)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Merge / split
+# ═══════════════════════════════════════════════════════════════════════
+
+def merge(
+    input_paths: Sequence[str],
+    output_path: str,
+) -> None:
+    """Merge multiple PDF files into one."""
+    _run("merge", inputs=list(input_paths), output=output_path)
+
+
+def split(input_path: str, output_dir: str) -> Any:
+    """Split a PDF into individual single-page PDFs.
+
+    Returns a namespace with ``pageCount`` and ``files``.
+    """
+    return _run("split", input=input_path, output_dir=output_dir)
+
+
+def extract_pages(
+    input_path: str,
+    output_path: str,
+    pages: Sequence[int],
+) -> None:
+    """Extract specific pages into a new PDF."""
+    _run(
+        "extract-pages",
+        input=input_path,
+        output=output_path,
+        pages=_int_csv(pages),
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Forms
+# ═══════════════════════════════════════════════════════════════════════
+
+def list_fields(input_path: str) -> Any:
+    """List all form fields in a PDF.
+
+    Returns a list of namespaces with ``name``, ``displayName``, ``type``,
+    ``value``, ``options``, ``isReadOnly``.
+    """
+    return _run("list-fields", input=input_path)
+
+
+def fill_form(
+    input_path: str,
+    output_path: str,
+    fields: dict[str, str],
+    *,
+    flatten: bool = False,
+) -> Any:
+    """Fill form fields and optionally flatten.
+
+    Parameters
+    ----------
+    fields : dict
+        Mapping of field name to value.
+    flatten : bool
+        If True, flatten the form after filling (makes fields non-editable).
+
+    Returns a namespace with ``fieldsFilled``, ``fieldsNotFound``,
+    ``filledFieldNames``, ``notFoundFieldNames``, ``warnings``.
+    """
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+        "fields": json.dumps(fields),
+    }
+    if flatten:
+        kwargs["flatten"] = True
+    return _run("fill-form", **kwargs)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Redaction
+# ═══════════════════════════════════════════════════════════════════════
+
+def redact(
+    input_path: str,
+    output_path: str,
+    redactions: list[dict[str, Any]],
+) -> Any:
+    """Redact text and/or areas in a PDF.
+
+    Each redaction dict can have: ``text``, ``isRegex``, ``caseSensitive``,
+    ``replaceWith``, ``pageNumber``, ``area`` (dict with x, y, width, height).
+
+    Returns a namespace with ``redactionsApplied``, ``pagesModified``,
+    ``warnings``.
+    """
+    return _run(
+        "redact",
+        input=input_path,
+        output=output_path,
+        redactions=json.dumps(redactions),
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Watermark / stamp
+# ═══════════════════════════════════════════════════════════════════════
+
+def watermark(
+    input_path: str,
+    output_path: str,
+    text: str,
+    *,
+    position: str | None = None,
+    font_size: float | None = None,
+    text_color: dict | None = None,
+    opacity: float | None = None,
+    page_range: Sequence[int] | None = None,
+) -> Any:
+    """Add a text watermark to a PDF.
+
+    Parameters
+    ----------
+    position : str, optional
+        One of "top", "bottom", "center", "across" (default: "across").
+    text_color : dict, optional
+        RGB color as ``{"r": 0.75, "g": 0.75, "b": 0.75}``.
+
+    Returns a namespace with ``pagesWatermarked``, ``totalPages``.
+    """
+    options: dict[str, Any] = {}
+    if position:
+        pos_map = {"top": 0, "bottom": 1, "center": 2, "across": 3}
+        options["position"] = pos_map.get(position.lower(), 3)
+    if font_size is not None:
+        options["fontSize"] = font_size
+    if text_color:
+        options["textColor"] = text_color
+    if opacity is not None:
+        options["opacity"] = opacity
+    if page_range:
+        options["pageRange"] = list(page_range)
+
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+        "text": text,
+    }
+    if options:
+        kwargs["options"] = json.dumps(options)
+
+    return _run("watermark", **kwargs)
+
+
+def stamp(
+    input_path: str,
+    output_path: str,
+    stamp_path: str,
+    *,
+    mode: str = "overlay",
+    page_range: Sequence[int] | None = None,
+    stamp_page_number: int = 1,
+    opacity: float = 1.0,
+) -> Any:
+    """Overlay or underlay a PDF stamp onto pages.
+
+    Parameters
+    ----------
+    mode : str
+        "overlay" (on top) or "underlay" (behind).
+
+    Returns a namespace with ``pagesStamped``.
+    """
+    options: dict[str, Any] = {}
+    if page_range:
+        options["pageRange"] = list(page_range)
+    if stamp_page_number != 1:
+        options["stampPageNumber"] = stamp_page_number
+    if opacity != 1.0:
+        options["opacity"] = opacity
+
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+        "stamp": stamp_path,
+        "mode": mode,
+    }
+    if options:
+        kwargs["options"] = json.dumps(options)
+
+    return _run("stamp", **kwargs)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Optimization
+# ═══════════════════════════════════════════════════════════════════════
+
+def optimize(
+    input_path: str,
+    output_path: str,
+    *,
+    compress_streams: bool = True,
+    remove_duplicate_objects: bool = True,
+    remove_metadata: bool = False,
+    downsample_images: bool = False,
+    max_image_dpi: int = 150,
+) -> Any:
+    """Optimize a PDF by compressing streams and removing duplicates.
+
+    Returns a namespace with ``originalSize``, ``optimizedSize``,
+    ``bytesSaved``, ``reductionPercent``, ``streamsCompressed``,
+    ``duplicatesRemoved``, ``imagesDownsampled``.
+    """
+    options: dict[str, Any] = {}
+    if not compress_streams:
+        options["compressStreams"] = False
+    if not remove_duplicate_objects:
+        options["removeDuplicateObjects"] = False
+    if remove_metadata:
+        options["removeMetadata"] = True
+    if downsample_images:
+        options["downsampleImages"] = True
+    if max_image_dpi != 150:
+        options["maxImageDpi"] = max_image_dpi
+
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+    }
+    if options:
+        kwargs["options"] = json.dumps(options)
+
+    return _run("optimize", **kwargs)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Security
+# ═══════════════════════════════════════════════════════════════════════
+
+def encrypt(
+    input_path: str,
+    output_path: str,
+    *,
+    user_password: str = "",
+    owner_password: str | None = None,
+    permissions: Sequence[str] | None = None,
+) -> None:
+    """Encrypt a PDF with AES-256 password protection.
+
+    Parameters
+    ----------
+    permissions : list of str, optional
+        Subset of: "Print", "ModifyContents", "CopyText",
+        "AddAnnotations", "FillForms", "PrintHighQuality", "All".
+    """
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+        "user_password": user_password,
+        "owner_password": owner_password or user_password,
+    }
+    if permissions:
+        kwargs["permissions"] = ",".join(permissions)
+    _run("encrypt", **kwargs)
+
+
+def decrypt(
+    input_path: str,
+    output_path: str,
+    password: str,
+) -> None:
+    """Decrypt a password-protected PDF."""
+    _run("decrypt", input=input_path, output=output_path, password=password)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Page editing
+# ═══════════════════════════════════════════════════════════════════════
+
+def rotate(
+    input_path: str,
+    output_path: str,
+    angle: int,
+    *,
+    pages: Sequence[int] | None = None,
+) -> Any:
+    """Rotate pages by the given angle (must be a multiple of 90).
+
+    Returns a namespace with ``pagesModified``.
+    """
+    return _run(
+        "rotate",
+        input=input_path,
+        output=output_path,
+        angle=str(angle),
+        pages=_int_csv(pages),
+    )
+
+
+def crop(
+    input_path: str,
+    output_path: str,
+    rect: dict[str, float],
+    *,
+    pages: Sequence[int] | None = None,
+) -> Any:
+    """Set the CropBox on pages.
+
+    Parameters
+    ----------
+    rect : dict
+        ``{"x": float, "y": float, "width": float, "height": float}``
+        in PDF points (72pt = 1 inch).
+
+    Returns a namespace with ``pagesModified``.
+    """
+    return _run(
+        "crop",
+        input=input_path,
+        output=output_path,
+        rect=json.dumps(rect),
+        pages=_int_csv(pages),
+    )
+
+
+def reorder(
+    input_path: str,
+    output_path: str,
+    order: Sequence[int],
+) -> None:
+    """Reorder pages. ``order`` is a sequence of 1-based page numbers."""
+    _run(
+        "reorder",
+        input=input_path,
+        output=output_path,
+        order=",".join(str(p) for p in order),
+    )
+
+
+def delete_pages(
+    input_path: str,
+    output_path: str,
+    pages: Sequence[int],
+) -> None:
+    """Delete specified pages (1-based) from a PDF."""
+    _run(
+        "delete-pages",
+        input=input_path,
+        output=output_path,
+        pages=_int_csv(pages),
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Images
+# ═══════════════════════════════════════════════════════════════════════
+
+def find_images(
+    input_path: str,
+    *,
+    output_dir: str | None = None,
+) -> Any:
+    """Find all images in a PDF.
+
+    Parameters
+    ----------
+    output_dir : str, optional
+        If provided, extracted image files are saved there.
+
+    Returns a namespace with ``images`` (list), ``totalImages``,
+    ``pagesSearched``.
+    """
+    kwargs: dict[str, Any] = {"input": input_path}
+    if output_dir:
+        kwargs["output_dir"] = output_dir
+    return _run("find-images", **kwargs)
+
+
+def replace_image(
+    input_path: str,
+    output_path: str,
+    image_path: str,
+    *,
+    page_range: Sequence[int] | None = None,
+    image_indices: Sequence[int] | None = None,
+    scale_mode: str | None = None,
+) -> Any:
+    """Replace images in a PDF with a new image (JPEG or PNG).
+
+    Parameters
+    ----------
+    scale_mode : str, optional
+        "match_original_size", "scale_to_fit", or "preserve_aspect_ratio".
+
+    Returns a namespace with ``imagesReplaced``, ``imagesFound``,
+    ``pagesSearched``.
+    """
+    options: dict[str, Any] = {}
+    if page_range:
+        options["pageRange"] = list(page_range)
+    if image_indices:
+        options["imageIndices"] = list(image_indices)
+    if scale_mode:
+        mode_map = {"match_original_size": 0, "preserve_aspect_ratio": 1, "scale_to_fit": 2}
+        options["scaleMode"] = mode_map.get(scale_mode.lower(), 0)
+
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+        "image": image_path,
+    }
+    if options:
+        kwargs["options"] = json.dumps(options)
+
+    return _run("replace-image", **kwargs)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Digital signatures
+# ═══════════════════════════════════════════════════════════════════════
+
+def sign(
+    input_path: str,
+    output_path: str,
+    cert_path: str,
+    *,
+    cert_password: str = "",
+    reason: str | None = None,
+    location: str | None = None,
+    signer_name: str | None = None,
+    visible: bool = False,
+    page: int | None = None,
+    rect: dict[str, float] | None = None,
+) -> None:
+    """Digitally sign a PDF with a PKCS#12 / PFX certificate.
+
+    Parameters
+    ----------
+    rect : dict, optional
+        Visible signature rectangle:
+        ``{"x": float, "y": float, "width": float, "height": float}``.
+    """
+    kwargs: dict[str, Any] = {
+        "input": input_path,
+        "output": output_path,
+        "cert": cert_path,
+        "cert_password": cert_password,
+    }
+    if reason:
+        kwargs["reason"] = reason
+    if location:
+        kwargs["location"] = location
+    if signer_name:
+        kwargs["signer_name"] = signer_name
+    if visible:
+        kwargs["visible"] = True
+        if page is not None:
+            kwargs["page"] = str(page)
+        if rect:
+            kwargs["rect"] = json.dumps(rect)
+
+    _run("sign", **kwargs)
+
+
+def verify(input_path: str, *, all_signatures: bool = False) -> Any:
+    """Verify digital signatures in a PDF.
+
+    Parameters
+    ----------
+    all_signatures : bool
+        If True, returns info for every signature field.
+
+    Returns a namespace (single) or list of namespaces with ``isSigned``,
+    ``signerName``, ``reason``, ``location``, ``signDate``, ``isValid``,
+    ``validationMessage``.
+    """
+    kwargs: dict[str, Any] = {"input": input_path}
+    if all_signatures:
+        kwargs["all"] = True
+    return _run("verify", **kwargs)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  PDF/A
+# ═══════════════════════════════════════════════════════════════════════
+
+def pdfa_validate(
+    input_path: str,
+    *,
+    level: str = "2b",
+) -> Any:
+    """Validate PDF/A compliance. No license required.
+
+    Parameters
+    ----------
+    level : str
+        Conformance level: "1b", "2b", "2u", "3b", or "3u".
+
+    Returns a namespace with ``isCompliant``, ``targetLevel``,
+    ``violations``.
+    """
+    return _run("pdfa-validate", input=input_path, level=level)
+
+
+def pdfa_convert(
+    input_path: str,
+    output_path: str,
+    *,
+    level: str = "2b",
+) -> None:
+    """Convert a PDF to PDF/A compliance."""
+    _run("pdfa-convert", input=input_path, output=output_path, level=level)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+#  Internal helpers
+# ═══════════════════════════════════════════════════════════════════════
+
+def _int_csv(values: Sequence[int] | None) -> str | None:
+    """Convert a sequence of ints to a comma-separated string, or None."""
+    if not values:
+        return None
+    return ",".join(str(v) for v in values)