PyPDFForm 4.8.0__tar.gz → 4.8.2__tar.gz

{pypdfform-4.8.0 → pypdfform-4.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.8.0
+Version: 4.8.2
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -23,21 +23,21 @@ License-File: LICENSE
 Requires-Dist: cryptography<47.0.0,>=46.0.3
 Requires-Dist: fonttools<5.0.0,>=4.62.1
 Requires-Dist: pikepdf<11.0.0,>=10.5.0
-Requires-Dist: pillow<13.0.0,>=12.0.0
+Requires-Dist: pillow<13.0.0,>=12.2.0
 Requires-Dist: pypdf<7.0.0,>=6.10.1
 Requires-Dist: reportlab<5.0.0,>=4.4.6
 Provides-Extra: cli
 Requires-Dist: typer<1.0.0,>=0.24.1; extra == "cli"
+Requires-Dist: jsonschema<5.0.0,>=4.26.0; extra == "cli"
 Provides-Extra: dev
-Requires-Dist: black<27.0.0,>=25.11.0; extra == "dev"
+Requires-Dist: black<27.0.0,>=26.3.1; extra == "dev"
 Requires-Dist: coverage<8.0.0,>=7.12.0; extra == "dev"
 Requires-Dist: isort<9.0.0,>=8.0.1; extra == "dev"
-Requires-Dist: jsonschema<5.0.0,>=4.26.0; extra == "dev"
 Requires-Dist: mike<3.0.0,>=2.1.3; extra == "dev"
 Requires-Dist: mkdocs<2.0.0,>=1.6.1; extra == "dev"
-Requires-Dist: mkdocs-material<10.0.0,>=9.7.0; extra == "dev"
-Requires-Dist: pudb<2026.0.0,>=2025.1.3; extra == "dev"
-Requires-Dist: pylint<5.0.0,>=4.0.3; extra == "dev"
+Requires-Dist: mkdocs-material<10.0.0,>=9.7.6; extra == "dev"
+Requires-Dist: pudb<2026.0.0,>=2025.1.5; extra == "dev"
+Requires-Dist: pylint<5.0.0,>=4.0.5; extra == "dev"
 Requires-Dist: pyright<2.0.0,>=1.1.407; extra == "dev"
 Requires-Dist: pytest<10.0.0,>=9.0.3; extra == "dev"
 Requires-Dist: requests<3.0.0,>=2.33.1; extra == "dev"

{pypdfform-4.8.0 → pypdfform-4.8.2}/PyPDFForm/__init__.py

@@ -22,7 +22,7 @@ PyPDFForm aims to simplify PDF form manipulation, making it accessible to develo
 
 import logging
 
-__version__ = "4.8.0"
+__version__ = "4.8.2"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage

pypdfform-4.8.2/PyPDFForm/cli/__init__.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines the root command-line interface for PyPDFForm.
+
+It creates the Typer application, attaches the `create`, `inspect`, and `update`
+command groups, and exposes top-level options shared by those commands. The root
+callback collects global flags in the Typer context so each subcommand can
+initialize `PdfWrapper` with consistent settings.
+
+Commands:
+    - `fill`: Fill an existing PDF form from JSON data.
+    - `create`: Create PDFs, fields, annotations, raw elements, and grid views.
+    - `inspect`: Print form metadata and field data as JSON.
+    - `update`: Modify PDF metadata, field names, properties, geometry, and scripts.
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .. import PdfWrapper, Widgets, __version__
+from .common import (INPUT_PDF, OPTIONAL_OUTPUT_PDF, json_file_option,
+                     load_json_file)
+from .create import create_cli
+from .inspect import inspect_cli
+from .update import update_cli
+
+cli_app = typer.Typer(
+    context_settings={"help_option_names": ["--help", "-h"]}, no_args_is_help=True
+)
+cli_app.add_typer(
+    create_cli,
+    name="create",
+    help="Create PDFs and PDF elements.",
+)
+cli_app.add_typer(
+    inspect_cli,
+    name="inspect",
+    help="Inspect PDF form information.",
+)
+cli_app.add_typer(
+    update_cli,
+    name="update",
+    help="Update PDF metadata, fields, and scripts.",
+)
+
+
+def version_callback(value: bool) -> None:
+    """
+    Handles the global version option.
+
+    This callback is invoked eagerly by Typer when `--version` or `-v` is
+    passed. When the option is enabled, it prints the current PyPDFForm version
+    and exits before command parsing continues.
+
+    Args:
+        value (bool): Whether the version flag was supplied.
+
+    Raises:
+        typer.Exit: Raised after printing the version so the CLI exits without
+            running another command.
+    """
+    if value:
+        typer.echo(f"v{__version__}")
+        raise typer.Exit
+
+
+@cli_app.callback(
+    invoke_without_command=True,
+    help="Create, fill, inspect, and update PDF forms.",
+)
+def main(
+    ctx: typer.Context,
+    version: Annotated[  # pylint: disable=W0613
+        bool,
+        typer.Option(
+            "--version",
+            "-v",
+            callback=version_callback,
+            is_eager=True,
+            help="Show the PyPDFForm version and exit.",
+        ),
+    ] = False,
+    need_appearances: Annotated[
+        bool,
+        typer.Option(
+            "--need-appearances",
+            help="Ask PDF viewers to render form field appearances.",
+        ),
+    ] = False,
+    generate_appearance_streams: Annotated[
+        bool,
+        typer.Option(
+            "--generate-appearance-streams",
+            help="Generate form field appearance streams.",
+        ),
+    ] = False,
+    preserve_metadata: Annotated[
+        bool,
+        typer.Option(
+            "--preserve-metadata",
+            help="Preserve input PDF metadata.",
+        ),
+    ] = False,
+    use_full_widget_name: Annotated[
+        bool,
+        typer.Option(
+            "--use-full-widget-name",
+            help="Use full form field names for lookup.",
+        ),
+    ] = False,
+) -> None:
+    """Create, fill, inspect, and update PDF forms."""
+    ctx.obj = {
+        "need_appearances": need_appearances,
+        "generate_appearance_streams": generate_appearance_streams,
+        "preserve_metadata": preserve_metadata,
+        "use_full_widget_name": use_full_widget_name,
+    }
+
+
+@cli_app.command(no_args_is_help=True)
+def fill(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    data: Annotated[Path, json_file_option("JSON file with form field values.")],
+    output: OPTIONAL_OUTPUT_PDF = None,
+    flatten: Annotated[
+        bool,
+        typer.Option("--flatten", help="Flatten form fields after filling."),
+    ] = None,
+) -> None:
+    """Fill a PDF form with JSON data."""
+    obj = PdfWrapper(str(pdf), **ctx.obj)
+
+    schema = obj.schema
+    for key, widget in obj.widgets.items():
+        if isinstance(widget, (Widgets.Image, Widgets.Signature)):
+            schema["properties"][key] = {
+                "anyOf": [
+                    schema["properties"][key],
+                    {
+                        "type": "object",
+                        "properties": {
+                            "path": {"type": "string"},
+                            "preserve_aspect_ratio": {"type": "boolean"},
+                        },
+                        "required": ["path"],
+                        "additionalProperties": False,
+                    },
+                ]
+            }
+
+    input_data = load_json_file(data, schema, "--file")
+    for k, each in obj.widgets.items():
+        if (
+            k in input_data
+            and isinstance(each, (Widgets.Image, Widgets.Signature))
+            and isinstance(input_data[k], dict)
+        ):
+            each.preserve_aspect_ratio = input_data[k].get(
+                "preserve_aspect_ratio", each.preserve_aspect_ratio
+            )
+            input_data[k] = input_data[k]["path"]
+
+    obj.fill(input_data, flatten=flatten).write(output or pdf)
+
+
+__all__ = ["cli_app"]

pypdfform-4.8.2/PyPDFForm/cli/common.py

@@ -0,0 +1,248 @@
+# -*- coding: utf-8 -*-
+"""
+This module provides shared helpers for PyPDFForm CLI commands.
+
+It contains utilities for loading JSON command input, registering custom fonts
+once per command invocation, and converting grouped JSON element definitions
+into the objects expected by `PdfWrapper` methods.
+"""
+
+import json
+from pathlib import Path
+from typing import Annotated, Any, NoReturn
+
+import typer
+from jsonschema import ValidationError, validate
+
+from .. import PdfWrapper
+from ..lib.middleware.base import Widget
+
+INPUT_PDF = Annotated[
+    Path,
+    typer.Argument(
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        help="Input PDF path.",
+    ),
+]
+REQUIRED_OUTPUT_PDF = Annotated[
+    Path,
+    typer.Option(
+        "--output",
+        "-o",
+        file_okay=True,
+        dir_okay=False,
+        writable=True,
+        resolve_path=True,
+        help="Output PDF path.",
+    ),
+]
+OPTIONAL_OUTPUT_PDF = Annotated[
+    Path | None,
+    typer.Option(
+        "--output",
+        "-o",
+        file_okay=True,
+        dir_okay=False,
+        writable=True,
+        resolve_path=True,
+        help="Output PDF path. Overwrites the input when omitted.",
+    ),
+]
+FIELD_NAME = Annotated[str, typer.Option("--field", help="Form field name.")]
+
+
+def json_file_option(help_text: str):
+    """
+    Creates the common validated JSON file option.
+
+    Args:
+        help_text (str): Help text to display for the option.
+
+    Returns:
+        typer.Option: A configured `--file` / `-f` option for JSON file input.
+    """
+    return typer.Option(
+        "--file",
+        "-f",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+        resolve_path=True,
+        help=help_text,
+    )
+
+
+def _cli_bad_parameter(
+    message: str,
+    param_hint: str,
+    cause: BaseException,
+) -> NoReturn:
+    """
+    Raises a Typer input error with a stable CLI message.
+
+    Args:
+        message (str): Error message to display to the CLI user.
+        param_hint (str): CLI parameter associated with the error.
+        cause (BaseException): Original exception that caused the CLI error.
+
+    Raises:
+        typer.BadParameter: Raised with the provided message and parameter hint.
+    """
+    raise typer.BadParameter(message, param_hint=param_hint) from cause
+
+
+def _validation_error_path(exc: ValidationError) -> str:
+    """
+    Builds a dotted JSON path for a validation error.
+
+    Args:
+        exc (ValidationError): The JSON schema validation error.
+
+    Returns:
+        str: Dotted path for the failing instance location.
+    """
+    return ".".join(str(each) for each in exc.absolute_path)
+
+
+def load_json_file(data: Path, schema: dict, param_hint: str) -> Any:
+    """
+    Loads a JSON CLI input file and validates it against a schema.
+
+    Args:
+        data (Path): JSON file path.
+        schema (dict): JSON schema to validate against.
+        param_hint (str): CLI parameter associated with the JSON file.
+
+    Returns:
+        Any: Parsed and validated JSON input.
+
+    Raises:
+        typer.BadParameter: Raised when the file cannot be loaded or validation
+            fails.
+    """
+    try:
+        with open(data, "r", encoding="utf-8") as f:
+            input_data = json.load(f)
+    except (OSError, json.JSONDecodeError) as exc:
+        _cli_bad_parameter(
+            f"Invalid JSON file: {exc}",
+            param_hint=param_hint,
+            cause=exc,
+        )
+
+    try:
+        validate(instance=input_data, schema=schema)
+    except ValidationError as exc:
+        error_path = _validation_error_path(exc)
+        location = f" at {error_path}" if error_path else ""
+        _cli_bad_parameter(
+            f"Invalid JSON file{location}: {exc.message}",
+            param_hint=param_hint,
+            cause=exc,
+        )
+
+    return input_data
+
+
+def get_widget(wrapper: PdfWrapper, field: str, param_hint: str) -> Widget:
+    """
+    Look up a widget and report missing names as CLI input errors.
+
+    Args:
+        wrapper (PdfWrapper): PDF wrapper containing form widgets.
+        field (str): Form field name to look up.
+        param_hint (str): CLI parameter associated with the field name.
+
+    Returns:
+        Widget: The matching widget.
+
+    Raises:
+        typer.BadParameter: Raised when the widget name is not present.
+    """
+    try:
+        return wrapper.widgets[field]
+    except KeyError as exc:
+        _cli_bad_parameter(
+            f"Form field '{field}' does not exist.",
+            param_hint=param_hint,
+            cause=exc,
+        )
+
+
+def handle_font_registration(
+    obj: PdfWrapper, params: dict, registered_font: dict
+) -> None:
+    """
+    Registers a custom font referenced by CLI input.
+
+    CLI JSON files may provide a file path in a `font` parameter. This helper
+    registers each unique font path on the supplied `PdfWrapper` once, assigns
+    it a generated internal font name, and mutates `params["font"]` to that
+    registered name so downstream field or element constructors can use it.
+
+    Args:
+        obj (PdfWrapper): The wrapper for the PDF currently being modified.
+        params (dict): The element or widget parameters loaded from JSON. This
+            dictionary is mutated when it contains a `font` key.
+        registered_font (dict): Mapping of source font paths to generated
+            `PdfWrapper` font names for the current command invocation.
+    """
+    if "font" in params:
+        if params["font"] not in registered_font:
+            font_name = f"new_font_{len(registered_font)}"
+            obj.register_font(font_name, params["font"])
+            registered_font[params["font"]] = font_name
+        params["font"] = registered_font[params["font"]]
+
+
+def create_elements_from_file(
+    pdf: Path,
+    data: Path,
+    element_map: dict,
+    schema: dict,
+    method_name: str,
+    ctx: typer.Context,
+    param_hint: str,
+    output: Path | None = None,
+) -> None:
+    """
+    Creates PDF elements from grouped JSON definitions.
+
+    The input JSON is expected to group element definitions by type, such as
+    `text`, `image`, or `highlight`. Each group key is resolved through
+    `element_map`, each item is constructed after optional font registration,
+    and the resulting objects are passed to `method_name` on `PdfWrapper`.
+    The modified PDF is written to `output` or back to the input path.
+
+    Args:
+        pdf (Path): The path to the input PDF file.
+        data (Path): The path to the JSON file containing grouped element
+            definitions.
+        element_map (dict): Mapping from JSON group names to element classes or
+            callables used to construct each object.
+        schema (dict): JSON schema used to validate the grouped definitions.
+        method_name (str): Name of the `PdfWrapper` method that accepts the
+            constructed elements, such as `bulk_create_fields`, `draw`, or
+            `annotate`.
+        ctx (typer.Context): Typer context containing global wrapper options in
+            `ctx.obj`.
+        param_hint (str): CLI parameter associated with the JSON file.
+        output (Path, optional): Path where the modified PDF should be saved. If
+            omitted, the input PDF is overwritten. Defaults to None.
+    """
+    input_data = load_json_file(data, schema, param_hint)
+
+    obj = PdfWrapper(str(pdf), **ctx.obj)
+    ungrouped_input = []
+    registered_font = {}
+    for k, v in input_data.items():
+        for each in v:
+            handle_font_registration(obj, each, registered_font)
+            ungrouped_input.append(element_map[k](**each))
+
+    getattr(obj, method_name)(ungrouped_input).write(output or pdf)