PyPDFForm 4.8.0__tar.gz → 4.8.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.8.0
+Version: 4.8.1
 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"
 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.1}/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.1"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage

pypdfform-4.8.1/PyPDFForm/cli/__init__.py

@@ -0,0 +1,149 @@
+# -*- 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.
+"""
+
+import json
+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
+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."""
+    with open(data, "r", encoding="utf-8") as f:
+        input_data = json.load(f)
+
+    obj = PdfWrapper(str(pdf), **ctx.obj)
+    for k, each in obj.widgets.items():
+        if k in input_data and isinstance(each, (Widgets.Image, Widgets.Signature)):
+            each.preserve_aspect_ratio = input_data.get(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.1/PyPDFForm/cli/common.py

@@ -0,0 +1,191 @@
+# -*- 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, NoReturn
+
+import typer
+
+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 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,
+    method_name: str,
+    ctx: typer.Context,
+    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.
+        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`.
+        output (Path, optional): Path where the modified PDF should be saved. If
+            omitted, the input PDF is overwritten. Defaults to None.
+    """
+    with open(data, "r", encoding="utf-8") as f:
+        input_data = json.load(f)
+
+    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)

pypdfform-4.8.1/PyPDFForm/cli/create.py

@@ -0,0 +1,237 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines CLI commands for creating PDF files and PDF content.
+
+It exposes the `create` command group for blank PDFs, extracted page ranges,
+merged PDFs, form fields, raw drawn elements, annotations, and coordinate grid
+views. Commands in this module translate command-line arguments or grouped JSON
+input into `PdfWrapper`, `BlankPage`, `Fields`, `RawElements`, and
+`Annotations` operations.
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from .. import (Annotations, BlankPage, Fields, PdfArray, PdfWrapper,
+                RawElements)
+from .common import (INPUT_PDF, OPTIONAL_OUTPUT_PDF, REQUIRED_OUTPUT_PDF,
+                     create_elements_from_file, json_file_option)
+
+create_cli = typer.Typer(
+    context_settings={"help_option_names": ["--help", "-h"]}, no_args_is_help=True
+)
+
+
+@create_cli.command(no_args_is_help=True)
+def blank(
+    ctx: typer.Context,
+    output: REQUIRED_OUTPUT_PDF,
+    count: Annotated[
+        int,
+        typer.Option(
+            "--count",
+            "-c",
+            min=1,
+            help="Number of blank pages to create.",
+        ),
+    ] = None,
+    width: Annotated[
+        float,
+        typer.Option(
+            "--width",
+            min=0.0,
+            help="Page width in points.",
+        ),
+    ] = None,
+    height: Annotated[
+        float,
+        typer.Option(
+            "--height",
+            min=0.0,
+            help="Page height in points.",
+        ),
+    ] = None,
+) -> None:
+    """Create a new blank PDF."""
+    params = {}
+    if width is not None:
+        params["width"] = width
+    if height is not None:
+        params["height"] = height
+
+    obj = BlankPage(**params)
+    if count is not None and count > 1:
+        obj = BlankPage(**params) * count
+
+    PdfWrapper(obj, **ctx.obj).write(output)
+
+
+@create_cli.command(no_args_is_help=True)
+def extract(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    output: REQUIRED_OUTPUT_PDF,
+    start: Annotated[
+        int,
+        typer.Option(
+            "--start",
+            "-s",
+            min=1,
+            help="First page to extract, starting at 1.",
+        ),
+    ] = None,
+    end: Annotated[
+        int,
+        typer.Option(
+            "--end",
+            "-e",
+            min=1,
+            help="Last page to extract, starting at 1.",
+        ),
+    ] = None,
+) -> None:
+    """Extract pages from an existing PDF."""
+    PdfWrapper(str(pdf), **ctx.obj).pages[slice((start or 1) - 1, end)].write(output)
+
+
+@create_cli.command(no_args_is_help=True)
+def merge(
+    ctx: typer.Context,
+    pdfs: Annotated[
+        list[Path],
+        typer.Argument(
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+            resolve_path=True,
+            help="Input PDF paths in merge order.",
+        ),
+    ],
+    output: REQUIRED_OUTPUT_PDF,
+) -> None:
+    """Merge multiple PDFs into one."""
+    PdfArray([PdfWrapper(str(pdf), **ctx.obj) for pdf in pdfs]).merge().write(output)
+
+
+@create_cli.command(no_args_is_help=True)
+def field(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    data: Annotated[Path, json_file_option("JSON file with form field definitions.")],
+    output: OPTIONAL_OUTPUT_PDF = None,
+) -> None:
+    """Add form fields to a PDF."""
+    field_map = {
+        "text": Fields.TextField,
+        "check": Fields.CheckBoxField,
+        "radio": Fields.RadioGroup,
+        "dropdown": Fields.DropdownField,
+        "image": Fields.ImageField,
+        "signature": Fields.SignatureField,
+    }
+    create_elements_from_file(pdf, data, field_map, "bulk_create_fields", ctx, output)
+
+
+@create_cli.command(no_args_is_help=True)
+def raw(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    data: Annotated[Path, json_file_option("JSON file with raw element definitions.")],
+    output: OPTIONAL_OUTPUT_PDF = None,
+) -> None:
+    """Draw text, images, and shapes on a PDF."""
+    raw_element_map = {
+        "text": RawElements.RawText,
+        "image": RawElements.RawImage,
+        "line": RawElements.RawLine,
+        "rectangle": RawElements.RawRectangle,
+        "circle": RawElements.RawCircle,
+        "ellipse": RawElements.RawEllipse,
+    }
+    create_elements_from_file(pdf, data, raw_element_map, "draw", ctx, output)
+
+
+@create_cli.command(no_args_is_help=True)
+def annotation(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    data: Annotated[Path, json_file_option("JSON file with annotation definitions.")],
+    output: OPTIONAL_OUTPUT_PDF = None,
+) -> None:
+    """Add annotations to a PDF."""
+    annotation_map = {
+        "text": Annotations.TextAnnotation,
+        "link": Annotations.LinkAnnotation,
+        "highlight": Annotations.HighlightAnnotation,
+        "underline": Annotations.UnderlineAnnotation,
+        "squiggly": Annotations.SquigglyAnnotation,
+        "strikeout": Annotations.StrikeOutAnnotation,
+        "stamp": Annotations.RubberStampAnnotation,
+    }
+    create_elements_from_file(pdf, data, annotation_map, "annotate", ctx, output)
+
+
+@create_cli.command(no_args_is_help=True)
+def grid(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    output: OPTIONAL_OUTPUT_PDF = None,
+    red: Annotated[
+        float,
+        typer.Option(
+            "--red",
+            "-r",
+            min=0.0,
+            max=1.0,
+            help="Grid red value, from 0 to 1.",
+        ),
+    ] = None,
+    green: Annotated[
+        float,
+        typer.Option(
+            "--green",
+            "-g",
+            min=0.0,
+            max=1.0,
+            help="Grid green value, from 0 to 1.",
+        ),
+    ] = None,
+    blue: Annotated[
+        float,
+        typer.Option(
+            "--blue",
+            "-b",
+            min=0.0,
+            max=1.0,
+            help="Grid blue value, from 0 to 1.",
+        ),
+    ] = None,
+    margin: Annotated[
+        float,
+        typer.Option(
+            "--margin",
+            "-m",
+            min=0.0,
+            help="Grid margin in points.",
+        ),
+    ] = None,
+) -> None:
+    """Add a coordinate grid to a PDF."""
+    params = {}
+    if any(
+        [
+            red is not None,
+            green is not None,
+            blue is not None,
+        ]
+    ):
+        params["color"] = (red or 0, green or 0, blue or 0)
+
+    if margin is not None:
+        params["margin"] = int(margin) if margin.is_integer() else margin
+    PdfWrapper(str(pdf), **ctx.obj).generate_coordinate_grid(**params).write(
+        output or pdf
+    )

pypdfform-4.8.1/PyPDFForm/cli/inspect.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines CLI commands for inspecting PDF form information.
+
+It exposes the `inspect` command group, which prints JSON for form schemas,
+current form values, generated sample data, and field rectangle metadata.
+Each command wraps read-only `PdfWrapper` properties so users can inspect forms
+from the terminal without writing Python code.
+"""
+
+import json
+
+import typer
+
+from .. import PdfWrapper
+from .common import FIELD_NAME, INPUT_PDF, get_widget
+
+inspect_cli = typer.Typer(
+    context_settings={"help_option_names": ["--help", "-h"]}, no_args_is_help=True
+)
+
+
+@inspect_cli.command(no_args_is_help=True)
+def schema(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+) -> None:
+    """Print the form schema as JSON."""
+    typer.echo(json.dumps(PdfWrapper(str(pdf), **ctx.obj).schema))
+
+
+@inspect_cli.command(no_args_is_help=True)
+def data(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+) -> None:
+    """Print current form data as JSON."""
+    typer.echo(json.dumps(PdfWrapper(str(pdf), **ctx.obj).data))
+
+
+@inspect_cli.command(no_args_is_help=True)
+def sample(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+) -> None:
+    """Print sample fill data as JSON."""
+    typer.echo(json.dumps(PdfWrapper(str(pdf), **ctx.obj).sample_data))
+
+
+@inspect_cli.command(no_args_is_help=True)
+def location(
+    ctx: typer.Context,
+    pdf: INPUT_PDF,
+    field: FIELD_NAME,
+) -> None:
+    """Print a form field's location and size as JSON."""
+    f = get_widget(PdfWrapper(str(pdf), **ctx.obj), field, "--field")
+
+    typer.echo(
+        json.dumps(
+            {
+                "page_number": f.page_number,
+                "x": f.x,
+                "y": f.y,
+                "width": f.width,
+                "height": f.height,
+            }
+        )
+    )