PyPDFForm 4.8.1__tar.gz → 4.8.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.8.1
+Version: 4.8.3
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -20,19 +20,19 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cryptography<47.0.0,>=46.0.3
+Requires-Dist: cryptography<48.0.0,>=47.0.0
 Requires-Dist: fonttools<5.0.0,>=4.62.1
-Requires-Dist: pikepdf<11.0.0,>=10.5.0
+Requires-Dist: pikepdf<11.0.0,>=10.5.1
 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: typer<1.0.0,>=0.25.0; extra == "cli"
+Requires-Dist: jsonschema<5.0.0,>=4.26.0; extra == "cli"
 Provides-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: coverage<8.0.0,>=7.13.5; 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.6; extra == "dev"
@@ -41,7 +41,7 @@ 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"
-Requires-Dist: ruff<1.0.0,>=0.14.6; extra == "dev"
+Requires-Dist: ruff<1.0.0,>=0.15.12; extra == "dev"
 Dynamic: license-file
 
 <p align="center"><img src="https://github.com/chinapandaman/PyPDFForm/raw/master/docs/img/logo.png"></p>

{pypdfform-4.8.1 → pypdfform-4.8.3}/PyPDFForm/__init__.py

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

{pypdfform-4.8.1 → pypdfform-4.8.3}/PyPDFForm/cli/common.py

@@ -9,9 +9,10 @@ into the objects expected by `PdfWrapper` methods.
 
 import json
 from pathlib import Path
-from typing import Annotated, NoReturn
+from typing import Annotated, Any, NoReturn
 
 import typer
+from jsonschema import ValidationError, validate
 
 from .. import PdfWrapper
 from ..lib.middleware.base import Widget
@@ -79,7 +80,7 @@ def json_file_option(help_text: str):
 def cli_bad_parameter(
     message: str,
     param_hint: str,
-    cause: BaseException,
+    cause: BaseException | None = None,
 ) -> NoReturn:
     """
     Raises a Typer input error with a stable CLI message.
@@ -87,14 +88,71 @@ def cli_bad_parameter(
     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.
+        cause (BaseException, optional): Original exception that caused the CLI
+            error. Defaults to None.
 
     Raises:
         typer.BadParameter: Raised with the provided message and parameter hint.
     """
+    if cause is None:
+        raise typer.BadParameter(message, param_hint=param_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.
@@ -150,8 +208,10 @@ 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:
     """
@@ -169,16 +229,17 @@ def create_elements_from_file(
             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.
     """
-    with open(data, "r", encoding="utf-8") as f:
-        input_data = json.load(f)
+    input_data = load_json_file(data, schema, param_hint)
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
     ungrouped_input = []

{pypdfform-4.8.1 → pypdfform-4.8.3}/PyPDFForm/cli/create.py

@@ -17,7 +17,9 @@ 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)
+                     cli_bad_parameter, create_elements_from_file,
+                     json_file_option)
+from .schemas.create import ANNOTATION_SCHEMA, FIELD_SCHEMA, RAW_SCHEMA
 
 create_cli = typer.Typer(
     context_settings={"help_option_names": ["--help", "-h"]}, no_args_is_help=True
@@ -93,6 +95,13 @@ def extract(
     ] = None,
 ) -> None:
     """Extract pages from an existing PDF."""
+    if start is not None and end is not None and start > end:
+        message = "End page must be greater than or equal to start page."
+        cli_bad_parameter(
+            message,
+            param_hint="--end",
+        )
+
     PdfWrapper(str(pdf), **ctx.obj).pages[slice((start or 1) - 1, end)].write(output)
 
 
@@ -132,7 +141,16 @@ def field(
         "image": Fields.ImageField,
         "signature": Fields.SignatureField,
     }
-    create_elements_from_file(pdf, data, field_map, "bulk_create_fields", ctx, output)
+    create_elements_from_file(
+        pdf=pdf,
+        data=data,
+        element_map=field_map,
+        schema=FIELD_SCHEMA,
+        method_name="bulk_create_fields",
+        ctx=ctx,
+        param_hint="--file",
+        output=output,
+    )
 
 
 @create_cli.command(no_args_is_help=True)
@@ -151,7 +169,16 @@ def raw(
         "circle": RawElements.RawCircle,
         "ellipse": RawElements.RawEllipse,
     }
-    create_elements_from_file(pdf, data, raw_element_map, "draw", ctx, output)
+    create_elements_from_file(
+        pdf=pdf,
+        data=data,
+        element_map=raw_element_map,
+        schema=RAW_SCHEMA,
+        method_name="draw",
+        ctx=ctx,
+        param_hint="--file",
+        output=output,
+    )
 
 
 @create_cli.command(no_args_is_help=True)
@@ -171,7 +198,16 @@ def annotation(
         "strikeout": Annotations.StrikeOutAnnotation,
         "stamp": Annotations.RubberStampAnnotation,
     }
-    create_elements_from_file(pdf, data, annotation_map, "annotate", ctx, output)
+    create_elements_from_file(
+        pdf=pdf,
+        data=data,
+        element_map=annotation_map,
+        schema=ANNOTATION_SCHEMA,
+        method_name="annotate",
+        ctx=ctx,
+        param_hint="--file",
+        output=output,
+    )
 
 
 @create_cli.command(no_args_is_help=True)

pypdfform-4.8.3/PyPDFForm/cli/entry.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""
+Console script entry point for the optional PyPDFForm CLI.
+
+The CLI implementation depends on the optional ``cli`` extra. This lightweight
+wrapper lets the ``pypdfform`` command fail with installation guidance instead
+of an import traceback when those optional dependencies are absent.
+"""
+
+import importlib
+import sys
+
+CLI_DEPENDENCIES = {"jsonschema", "typer"}
+CLI_INSTALL_HINT = "pip install 'PyPDFForm[cli]'"
+
+
+def main() -> None:
+    """
+    Run the PyPDFForm CLI.
+
+    Raises:
+        SystemExit: Raised with exit code 1 when optional CLI dependencies are
+            missing.
+    """
+    try:
+        cli_module = importlib.import_module("PyPDFForm.cli.root")
+    except ModuleNotFoundError as exc:
+        if exc.name in CLI_DEPENDENCIES:
+            print(
+                "PyPDFForm CLI dependencies are not installed. "
+                f"Install them with: {CLI_INSTALL_HINT}",
+                file=sys.stderr,
+            )
+            raise SystemExit(1) from None
+        raise
+
+    getattr(cli_module, "cli_app")()

pypdfform-4.8.1/PyPDFForm/cli/__init__.py → pypdfform-4.8.3/PyPDFForm/cli/root.py

@@ -14,14 +14,14 @@ Commands:
     - `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 .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
@@ -132,18 +132,36 @@ def fill(
     ] = 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)
+
+    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)):
-            each.preserve_aspect_ratio = input_data.get(k, {}).get(
+        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"]