PyPDFForm 4.8.1__tar.gz → 4.8.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.8.1
+Version: 4.8.2
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -28,11 +28,11 @@ 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,>=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.6; extra == "dev"

{pypdfform-4.8.1 → 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.1"
+__version__ = "4.8.2"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage

{pypdfform-4.8.1 → pypdfform-4.8.2}/PyPDFForm/cli/__init__.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,13 +132,34 @@ 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"]

{pypdfform-4.8.1 → pypdfform-4.8.2}/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
@@ -76,7 +77,7 @@ def json_file_option(help_text: str):
     )
 
 
-def cli_bad_parameter(
+def _cli_bad_parameter(
     message: str,
     param_hint: str,
     cause: BaseException,
@@ -95,6 +96,59 @@ def cli_bad_parameter(
     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.
@@ -113,7 +167,7 @@ def get_widget(wrapper: PdfWrapper, field: str, param_hint: str) -> Widget:
     try:
         return wrapper.widgets[field]
     except KeyError as exc:
-        cli_bad_parameter(
+        _cli_bad_parameter(
             f"Form field '{field}' does not exist.",
             param_hint=param_hint,
             cause=exc,
@@ -150,8 +204,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 +225,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.2}/PyPDFForm/cli/create.py

@@ -18,6 +18,7 @@ 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)
+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
@@ -132,7 +133,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 +161,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 +190,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)